- Notifications
You must be signed in to change notification settings - Fork37
Structured Logging for Django
License
jrobichaud/django-structlog
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
django-structlog is a structured logging integration forDjango project usingstructlog
Logging will then produce additional cohesive metadata on each logs that makes it easier to track events or incidents.
Django REST framework is supported by default. But when using it withrest_framework.authentication.TokenAuthentication (or other DRF authentications)user_id will be only be inrequest_finished andrequest_failed instead of each logs.
See#37 for details.
django-ninja is supported by default 🥷.
Celery's task logging requires additional configurations, seedocumentation for details.
>>>importlogging>>>logger=logging.get_logger(__name__)>>>logger.info("An error occurred")
An error occurred
Well... ok
>>>importstructlog>>>logger=structlog.get_logger(__name__)>>>logger.info("an_error_occurred",bar="Buz")
timestamp='2019-04-13T19:39:31.089925Z' level='info' event='an_error_occurred' logger='my_awesome_project.my_awesome_module' request_id='3a8f801c-072b-4805-8f38-e1337f363ed4' user_id=1 ip='0.0.0.0' bar='Buz'
Then you can search with commands like:
$ cat logs/flat_line.log| grep request_id='3a8f801c-072b-4805-8f38-e1337f363ed4'
>>>importstructlog>>>logger=structlog.get_logger(__name__)>>>logger.info("an_error_occurred",bar="Buz")
{"request_id":"3a8f801c-072b-4805-8f38-e1337f363ed4","user_id":1,"ip":"0.0.0.0","event":"an_error_occurred","timestamp":"2019-04-13T19:39:31.089925Z","logger":"my_awesome_project.my_awesome_module","level":"info","bar":"Buz"}Then you can search with commands like:
$ cat logs/json.log| jq'.[] | select(.request_id="3a8f801c-072b-4805-8f38-e1337f363ed4")' -s
These steps will show how to integrate the middleware to your awesome application.
Install the library
pip install django-structlog
Add app
INSTALLED_APP= [# ..."django_structlog",# ...]
Add middleware
MIDDLEWARE= [# ..."django_structlog.middlewares.RequestMiddleware",]
Add appropriate structlog configuration to yoursettings.py
importstructlogLOGGING= {"version":1,"disable_existing_loggers":False,"formatters": {"json_formatter": {"()":structlog.stdlib.ProcessorFormatter,"processor":structlog.processors.JSONRenderer(), },"plain_console": {"()":structlog.stdlib.ProcessorFormatter,"processor":structlog.dev.ConsoleRenderer(), },"key_value": {"()":structlog.stdlib.ProcessorFormatter,"processor":structlog.processors.KeyValueRenderer(key_order=['timestamp','level','event','logger']), }, },"handlers": {# Important notes regarding handlers.## 1. Make sure you use handlers adapted for your project.# These handlers configurations are only examples for this library.# See python's logging.handlers: https://docs.python.org/3/library/logging.handlers.html## 2. You might also want to use different logging configurations depending of the environment.# Different files (local.py, tests.py, production.py, ci.py, etc.) or only conditions.# See https://docs.djangoproject.com/en/dev/topics/settings/#designating-the-settings"console": {"class":"logging.StreamHandler","formatter":"plain_console", },"json_file": {"class":"logging.handlers.WatchedFileHandler","filename":"logs/json.log","formatter":"json_formatter", },"flat_line_file": {"class":"logging.handlers.WatchedFileHandler","filename":"logs/flat_line.log","formatter":"key_value", }, },"loggers": {"django_structlog": {"handlers": ["console","flat_line_file","json_file"],"level":"INFO", },# Make sure to replace the following logger's name for yours"django_structlog_demo_project": {"handlers": ["console","flat_line_file","json_file"],"level":"INFO", }, }}structlog.configure(processors=[structlog.contextvars.merge_contextvars,structlog.stdlib.filter_by_level,structlog.processors.TimeStamper(fmt="iso"),structlog.stdlib.add_logger_name,structlog.stdlib.add_log_level,structlog.stdlib.PositionalArgumentsFormatter(),structlog.processors.StackInfoRenderer(),structlog.processors.format_exc_info,structlog.processors.UnicodeDecoder(),structlog.stdlib.ProcessorFormatter.wrap_for_formatter, ],logger_factory=structlog.stdlib.LoggerFactory(),cache_logger_on_first_use=True,)
Start logging withstructlog instead oflogging.
importstructloglogger=structlog.get_logger(__name__)
By default only arequest_id and theuser_id are bound from the request but pertinent log metadata may vary from a project to another.
If you need to add more metadata from the request you can implement a convenient signal receiver to bind them. You can also override existing bound metadata the same way.
fromdjango.contrib.sites.shortcutsimportget_current_sitefromdjango.dispatchimportreceiverfromdjango_structlogimportsignalsimportstructlog@receiver(signals.bind_extra_request_metadata)defbind_domain(request,logger,**kwargs):current_site=get_current_site(request)structlog.contextvars.bind_contextvars(domain=current_site.domain)
It is also possible to log using standard python logger.
In your formatters, add theforeign_pre_chain section, and then addstructlog.contextvars.merge_contextvars:
LOGGING= {"version":1,"disable_existing_loggers":False,"formatters": {"json_formatter": {"()":structlog.stdlib.ProcessorFormatter,"processor":structlog.processors.JSONRenderer(),# Add this section:"foreign_pre_chain": [structlog.contextvars.merge_contextvars,# <---- add this# customize the rest as you needstructlog.processors.TimeStamper(fmt="iso"),structlog.stdlib.add_logger_name,structlog.stdlib.add_log_level,structlog.stdlib.PositionalArgumentsFormatter(), ], }, }, ... }
timestamp='2019-04-13T19:39:29.321453Z' level='info' event='request_started' logger='django_structlog.middlewares.request' request_id='c53dff1d-3fc5-4257-a78a-9a567c937561' user_id=1 ip='0.0.0.0' request=GET / user_agent='Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.86 Safari/537.36'timestamp='2019-04-13T19:39:29.345207Z' level='info' event='request_finished' logger='django_structlog.middlewares.request' request_id='c53dff1d-3fc5-4257-a78a-9a567c937561' user_id=1 ip='0.0.0.0' code=200timestamp='2019-04-13T19:39:31.086155Z' level='info' event='request_started' logger='django_structlog.middlewares.request' request_id='3a8f801c-072b-4805-8f38-e1337f363ed4' user_id=1 ip='0.0.0.0' request=POST /success_task user_agent='Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.86 Safari/537.36'timestamp='2019-04-13T19:39:31.089925Z' level='info' event='Enqueuing successful task' logger='django_structlog_demo_project.home.views' request_id='3a8f801c-072b-4805-8f38-e1337f363ed4' user_id=1 ip='0.0.0.0'timestamp='2019-04-13T19:39:31.147590Z' level='info' event='task_enqueued' logger='django_structlog.middlewares.celery' request_id='3a8f801c-072b-4805-8f38-e1337f363ed4' user_id=1 ip='0.0.0.0' child_task_id='6b11fd80-3cdf-4de5-acc2-3fd4633aa654'timestamp='2019-04-13T19:39:31.153081Z' level='info' event='This is a successful task' logger='django_structlog_demo_project.taskapp.celery' task_id='6b11fd80-3cdf-4de5-acc2-3fd4633aa654' request_id='3a8f801c-072b-4805-8f38-e1337f363ed4' user_id=1 ip='0.0.0.0'timestamp='2019-04-13T19:39:31.160043Z' level='info' event='request_finished' logger='django_structlog.middlewares.request' request_id='3a8f801c-072b-4805-8f38-e1337f363ed4' user_id=1 ip='0.0.0.0' code=201timestamp='2019-04-13T19:39:31.162372Z' level='info' event='task_succeed' logger='django_structlog.middlewares.celery' task_id='6b11fd80-3cdf-4de5-acc2-3fd4633aa654' request_id='3a8f801c-072b-4805-8f38-e1337f363ed4' user_id=1 ip='0.0.0.0' result='None'
{"request_id":"c53dff1d-3fc5-4257-a78a-9a567c937561","user_id":1,"ip":"0.0.0.0","request":"GET /","user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.86 Safari/537.36","event":"request_started","timestamp":"2019-04-13T19:39:29.321453Z","logger":"django_structlog.middlewares.request","level":"info"}{"request_id":"c53dff1d-3fc5-4257-a78a-9a567c937561","user_id":1,"ip":"0.0.0.0","code":200,"event":"request_finished","timestamp":"2019-04-13T19:39:29.345207Z","logger":"django_structlog.middlewares.request","level":"info"}{"request_id":"3a8f801c-072b-4805-8f38-e1337f363ed4","user_id":1,"ip":"0.0.0.0","request":"POST /success_task","user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.86 Safari/537.36","event":"request_started","timestamp":"2019-04-13T19:39:31.086155Z","logger":"django_structlog.middlewares.request","level":"info"}{"request_id":"3a8f801c-072b-4805-8f38-e1337f363ed4","user_id":1,"ip":"0.0.0.0","event":"Enqueuing successful task","timestamp":"2019-04-13T19:39:31.089925Z","logger":"django_structlog_demo_project.home.views","level":"info"}{"request_id":"3a8f801c-072b-4805-8f38-e1337f363ed4","user_id":1,"ip":"0.0.0.0","child_task_id":"6b11fd80-3cdf-4de5-acc2-3fd4633aa654","event":"task_enqueued","timestamp":"2019-04-13T19:39:31.147590Z","logger":"django_structlog.middlewares.celery","level":"info"}{"task_id":"6b11fd80-3cdf-4de5-acc2-3fd4633aa654","request_id":"3a8f801c-072b-4805-8f38-e1337f363ed4","user_id":1,"ip":"0.0.0.0","event":"This is a successful task","timestamp":"2019-04-13T19:39:31.153081Z","logger":"django_structlog_demo_project.taskapp.celery","level":"info"}{"request_id":"3a8f801c-072b-4805-8f38-e1337f363ed4","user_id":1,"ip":"0.0.0.0","code":201,"event":"request_finished","timestamp":"2019-04-13T19:39:31.160043Z","logger":"django_structlog.middlewares.request","level":"info"}{"task_id":"6b11fd80-3cdf-4de5-acc2-3fd4633aa654","request_id":"3a8f801c-072b-4805-8f38-e1337f363ed4","user_id":1,"ip":"0.0.0.0","result":"None","event":"task_succeed","timestamp":"2019-04-13T19:39:31.162372Z","logger":"django_structlog.middlewares.celery","level":"info"}- requires python 3.9+
- django 4.2 and 5.0+ are supported
django-structlog now usespython type hints and is being validated withmypy--strict.
Now unhandled exceptions when usingdrf-standardized-errors will be intercepted and the exception logged properly.
If you also usestructlog-sentry, the exception will now be propagated as expected.
Other libraries alike may be affected by this change.
This only affects you if you implemented a middleware inheriting fromRequestMiddleware and you overrode theprocess_exception method.
Did you?
If so:
RequestMiddleware.process_exceptionwas renamed toRequestMiddleware._process_exception, you should to the same in the middleware.
- A new keyword argument
log_kwargswas added to the the optional signals: django_structlog.signals.bind_extra_request_metadata;django_structlog.signals.bind_extra_request_finished_metadata;django_structlog.signals.bind_extra_request_failed_metadata.
It should not affect you if you have a**kwargs in the signature of your receivers.
log_kwargs is a dictionary containing the log metadata that will be added to their respective logs ("request_started","request_finished","request_failed").
If you use any of these signals, you may need to update your receiver to accept this new argument:
fromdjango.contrib.sites.shortcutsimportget_current_sitefromdjango.dispatchimportreceiverfromdjango_structlogimportsignalsimportstructlog@receiver(signals.bind_extra_request_metadata)defmy_receiver(request,logger,log_kwargs,**kwargs):# <- add `log_kwargs` if necessary ...@receiver(signals.bind_extra_request_finished_metadata)defmy_receiver_finished(request,logger,response,log_kwargs,**kwargs):# <- add `log_kwargs` if necessary ...@receiver(signals.bind_extra_request_failed_metadata)defmy_receiver_failed(request,logger,exception,log_kwargs,**kwargs):# <- add `log_kwargs` if necessary ...
The dependencydjango-ipware was upgraded to version 6. This library is used to retrieve the request's ip address.
Version 6 may have somebreaking changes if you did customizations.
It should not affect most of the users but if you did some customizations, you might need to update your configurations.
- requires python 3.8+
INSTALLED_APP= [# ..."django_structlog",# ...]
If you used any of the experimental async or sync middlewares, you do not need to anymore.Make sure you usedjango_structlog.middlewares.RequestMiddleware instead of any of the other request middlewares commented below:
MIDDLEWARE+= [# "django_structlog.middlewares.request_middleware_router", # <- remove# "django_structlog.middlewares.requests.SyncRequestMiddleware", # <- remove# "django_structlog.middlewares.requests.AsyncRequestMiddleware", # <- remove"django_structlog.middlewares.RequestMiddleware",# <- make sure you use this one]
It is only applicable if you use celery integration.
django_structlog.middlewares.CeleryMiddleware has been remove in favor of a django settings.
MIDDLEWARE+= ["django_structlog.middlewares.RequestMiddleware",# "django_structlog.middlewares.CeleryMiddleware", # <- remove this]DJANGO_STRUCTLOG_CELERY_ENABLED=True# <-- add this
- requires asgiref 3.6+
django-structlog drops support of django below 3.2.
- requires django 3.2+
- requires python 3.7+
- requires structlog 21.4.0+
- (optionally) requires celery 5.1+
You can now installdjango-structlog explicitly withcelery extra in order to validate the compatibility with your version ofcelery.
django-structlog[celery]==4.0.0
SeeInstalling “Extras” for more information about thispip feature.
django-structlog now usestructlog.contextvars.bind_contextvars instead ofthreadlocal.
- requires python 3.7+
- requires structlog 21.4.0+
- add
structlog.contextvars.merge_contextvarsas firstprocessors - remove
context_class=structlog.threadlocal.wrap_dict(dict), - (if you use standard loggers) add
structlog.contextvars.merge_contextvarsin foreign_pre_chain - (if you use standard loggers) remove
django_structlog.processors.inject_context_dict,
structlog.configure(processors=[structlog.contextvars.merge_contextvars,# <---- add thisstructlog.stdlib.filter_by_level,structlog.processors.TimeStamper(fmt="iso"),structlog.stdlib.add_logger_name,structlog.stdlib.add_log_level,structlog.stdlib.PositionalArgumentsFormatter(),structlog.processors.StackInfoRenderer(),structlog.processors.format_exc_info,structlog.processors.UnicodeDecoder(),structlog.stdlib.ProcessorFormatter.wrap_for_formatter, ],# context_class=structlog.threadlocal.wrap_dict(dict), # <---- remove thislogger_factory=structlog.stdlib.LoggerFactory(),cache_logger_on_first_use=True,)# If you use standard loggingLOGGING= {"version":1,"disable_existing_loggers":False,"formatters": {"json_formatter": {"()":structlog.stdlib.ProcessorFormatter,"processor":structlog.processors.JSONRenderer(),"foreign_pre_chain": [structlog.contextvars.merge_contextvars,# <---- add this# django_structlog.processors.inject_context_dict, # <---- remove thisstructlog.processors.TimeStamper(fmt="iso"),structlog.stdlib.add_logger_name,structlog.stdlib.add_log_level,structlog.stdlib.PositionalArgumentsFormatter(), ], }, }, ... }
@receiver(bind_extra_request_metadata)defbind_domain(request,logger,**kwargs):current_site=get_current_site(request)# logger.bind(domain=current_site.domain)structlog.contextvars.bind_contextvars(domain=current_site.domain)
django-structlog was originally developed using the debug configurationExceptionPrettyPrinter which led to incorrect handling of exception.
- remove
structlog.processors.ExceptionPrettyPrinter(),of your processors. - make sure you have
structlog.processors.format_exc_info,in your processors if you want appropriate exception logging.
Note: For the moment redis is needed to run the tests. The easiest way is to start docker demo's redis.
docker compose up -d redispip install -r requirements.txtenv CELERY_BROKER_URL=redis://0.0.0.0:6379 DJANGO_SETTINGS_MODULE=config.settings.test pytest test_appenv CELERY_BROKER_URL=redis://0.0.0.0:6379 DJANGO_SETTINGS_MODULE=config.settings.test_demo_app pytest django_structlog_demo_projectdocker compose stop redis
docker compose up --build
Openhttp://127.0.0.1:8000/ in your browser.
Navigate while looking into the log files and shell's output.
- Jules Robichaud-Gagnon -Initial work -jrobichaud
See also the list ofcontributors who participated in this project.
- Very huge thanks to my awesome 🦄 and generous employerTLM 🩵💜❤️🧡💚🐈⬛ for letting me maintain this project on my work hours because it believes in open source.
- Big thanks to@ferd for hisbad opinions that inspired the author enough to spend time on this library.
- This issue helped the author to figure out how to integrate
structlogin Django. - This stack overflow question was also helpful.
This project is licensed under the MIT License - see theLICENSE file for details
About
Structured Logging for Django