Merge branch 'common_logger' into 'master'

Extensions Logging

See merge request allianceauth/allianceauth!1180

allianceauth/project_template/project_name/settings/base.py

@@ -220,6 +220,14 @@ LOGGING = {
             'maxBytes': 1024 * 1024 * 5,  # edit this line to change max log file size
             'backupCount': 5,  # edit this line to change number of log backups
         },
+        'extension_file': {
+            'level': 'DEBUG',
+            'class': 'logging.handlers.RotatingFileHandler',
+            'filename': os.path.join(BASE_DIR, 'log/extensions.log'),
+            'formatter': 'verbose',
+            'maxBytes': 1024 * 1024 * 5,  # edit this line to change max log file size
+            'backupCount': 5,  # edit this line to change number of log backups
+        },
         'console': {
             'level': 'DEBUG',  # edit this line to change logging level to console
             'class': 'logging.StreamHandler',
@@ -236,6 +244,10 @@ LOGGING = {
             'handlers': ['log_file', 'console', 'notifications'],
             'level': 'DEBUG',
         },
+        'extensions': {
+            'handlers': ['extension_file', 'console'],
+            'level': 'DEBUG',
+        },
         'django': {
             'handlers': ['log_file', 'console'],
             'level': 'ERROR',

allianceauth/services/hooks.py

@@ -9,6 +9,29 @@ from allianceauth.hooks import get_hooks
 from .models import NameFormatConfig
 
 
+def get_extension_logger(name):
+    """
+    Takes the name of a plugin/extension and generates a child logger of the extensions logger
+    to be used by the extension to log events to the extensions logger.
+
+    The logging level is decided by whether or not DEBUG is set to true in the project settings. If
+    DEBUG is set to false, then the logging level is set to INFO.
+
+    :param: name: the name of the extension doing the logging
+    :return: an extensions child logger
+    """
+    import logging
+    from django.conf import settings
+
+    logger = logging.getLogger('extensions.' + name)
+    logger.name = name
+    logger.level = logging.INFO
+    if settings.DEBUG:
+        logger.level = logging.DEBUG
+
+    return logger
+
+
 class ServicesHook:
     """
     Abstract base class for creating a compatible services

docs/development/custom/index.md

@@ -9,4 +9,5 @@ This section describes how to extend **Alliance Auth** with custom apps and serv
     integrating-services
     menu-hooks
     url-hooks
+    logging
 ```

docs/development/custom/logging.md

@@ -0,0 +1,15 @@
+# Logging from Custom Apps
+Alliance Auth provides a logger for use with custom apps to make everyone's life a little easier.
+
+## Using the Extensions Logger
+AllianceAuth provides a helper function to get the logger for the current module to reduce the amount of
+code you need to write.
+
+```python
+from allianceauth.services.hooks import get_extension_logger
+
+logger = get_extension_logger(__name__)
+```
+
+This works by creating a child logger of the extension logger which propagates all log entries
+to the parent (extensions) logger.