From e54b80e061d169044da18c23a2235a3dd4af39b5 Mon Sep 17 00:00:00 2001 From: Col Crunch Date: Fri, 13 Mar 2020 00:33:35 -0400 Subject: [PATCH 1/4] Add a common logger (and specific log file) for extensions to utilize. --- .../project_template/project_name/settings/base.py | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/allianceauth/project_template/project_name/settings/base.py b/allianceauth/project_template/project_name/settings/base.py index 4e1efa02..fdcf679c 100644 --- a/allianceauth/project_template/project_name/settings/base.py +++ b/allianceauth/project_template/project_name/settings/base.py @@ -218,6 +218,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': 'INFO', + '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', @@ -234,6 +242,11 @@ LOGGING = { 'handlers': ['log_file', 'console', 'notifications'], 'level': 'DEBUG', }, + 'allianceauth.extensions': { + 'handlers': ['extension_file', 'console'], + 'level': 'DEBUG', + 'propagate': False, + }, 'django': { 'handlers': ['log_file', 'console'], 'level': 'ERROR', From 527d7ef6712b26e1ae05ea3981ca1daa2147baad Mon Sep 17 00:00:00 2001 From: Col Crunch Date: Fri, 13 Mar 2020 04:42:09 -0400 Subject: [PATCH 2/4] Change level of `extension_file` handler, rename the logger from `allianceauth.extensions` to `extensions` and remove `propagate` from the logger. --- allianceauth/project_template/project_name/settings/base.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/allianceauth/project_template/project_name/settings/base.py b/allianceauth/project_template/project_name/settings/base.py index fdcf679c..d438ed83 100644 --- a/allianceauth/project_template/project_name/settings/base.py +++ b/allianceauth/project_template/project_name/settings/base.py @@ -219,7 +219,7 @@ LOGGING = { 'backupCount': 5, # edit this line to change number of log backups }, 'extension_file': { - 'level': 'INFO', + 'level': 'DEBUG', 'class': 'logging.handlers.RotatingFileHandler', 'filename': os.path.join(BASE_DIR, 'log/extensions.log'), 'formatter': 'verbose', @@ -242,10 +242,9 @@ LOGGING = { 'handlers': ['log_file', 'console', 'notifications'], 'level': 'DEBUG', }, - 'allianceauth.extensions': { + 'extensions': { 'handlers': ['extension_file', 'console'], 'level': 'DEBUG', - 'propagate': False, }, 'django': { 'handlers': ['log_file', 'console'], From 38aaf545c6a53fcff82a593584ccfeee1eb15a81 Mon Sep 17 00:00:00 2001 From: Col Crunch Date: Fri, 13 Mar 2020 14:42:09 -0400 Subject: [PATCH 3/4] Add some very basic docs for logging changes --- docs/development/custom/index.md | 1 + docs/development/custom/logging.md | 17 +++++++++++++++++ 2 files changed, 18 insertions(+) create mode 100644 docs/development/custom/logging.md diff --git a/docs/development/custom/index.md b/docs/development/custom/index.md index d0f51068..72882345 100644 --- a/docs/development/custom/index.md +++ b/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 ``` diff --git a/docs/development/custom/logging.md b/docs/development/custom/logging.md new file mode 100644 index 00000000..9727e339 --- /dev/null +++ b/docs/development/custom/logging.md @@ -0,0 +1,17 @@ +# 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 +The extensions logger should not be directly used by custom apps as the error messages logged to it +will not be labeled with the correct name. In order to correctly use the extensions logger please follow +the code below. + +```python +import logging + +logger = logging.getLogger('extensions.' + __name__) +logger.name = __name__ +``` + +This works by creating a child logger of the extension logger which propagates all log entries +to the parent (extensions) logger. \ No newline at end of file From 76ebd21163e9b05fbcc3a58195989dc9618165a5 Mon Sep 17 00:00:00 2001 From: Col Crunch Date: Fri, 13 Mar 2020 15:21:15 -0400 Subject: [PATCH 4/4] Add function to `services.hooks` to provide a concise way for creating loggers for extensions/plugins. Revise basic documentation to use this function. --- allianceauth/services/hooks.py | 23 +++++++++++++++++++++++ docs/development/custom/logging.md | 10 ++++------ 2 files changed, 27 insertions(+), 6 deletions(-) diff --git a/allianceauth/services/hooks.py b/allianceauth/services/hooks.py index 44c90900..10a30fa3 100644 --- a/allianceauth/services/hooks.py +++ b/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 diff --git a/docs/development/custom/logging.md b/docs/development/custom/logging.md index 9727e339..edba7315 100644 --- a/docs/development/custom/logging.md +++ b/docs/development/custom/logging.md @@ -2,15 +2,13 @@ Alliance Auth provides a logger for use with custom apps to make everyone's life a little easier. ## Using the Extensions Logger -The extensions logger should not be directly used by custom apps as the error messages logged to it -will not be labeled with the correct name. In order to correctly use the extensions logger please follow -the code below. +AllianceAuth provides a helper function to get the logger for the current module to reduce the amount of +code you need to write. ```python -import logging +from allianceauth.services.hooks import get_extension_logger -logger = logging.getLogger('extensions.' + __name__) -logger.name = __name__ +logger = get_extension_logger(__name__) ``` This works by creating a child logger of the extension logger which propagates all log entries