django-structlog

django-structlog is a structured logging integration for Django project using structlog

Logging will then produce additional cohesive metadata on each logs that makes it easier to track events or incidents.

Additional Popular Integrations

Django REST framework

Django REST framework is supported by default. But when using it with rest_framework.authentication.TokenAuthentication (or other DRF authentications) user_id will be only be in request_finished and request_failed instead of each logs.

See #37 for details.

django-ninja

django-ninja is supported by default 🥷.

Celery

Celery’s task logging requires additional configurations, see documentation for details.

Django Tasks

(Experimental) Django 6.0+’s django.tasks logging requires additional configurations, see documentation for details.

Logging comparison

Standard logging:

>>> import logging
>>> logger = logging.get_logger(__name__)
>>> logger.info("An error occurred")

An error occurred

Well… ok

With django-structlog and flat_line:

>>> import structlog
>>> 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'

With django-structlog and json

>>> import structlog
>>> 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

Getting Started

These steps will show how to integrate the middleware to your awesome application.

Installation

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 your settings.py

import structlog

LOGGING = {
    "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 with structlog instead of logging.

import structlog
logger = structlog.get_logger(__name__)

Extending Request Log Metadata

By default only a request_id and the user_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.

from django.contrib.sites.shortcuts import get_current_site
from django.dispatch import receiver
from django_structlog import signals
import structlog


@receiver(signals.bind_extra_request_metadata)
def bind_domain(request, logger, **kwargs):
    current_site = get_current_site(request)
    structlog.contextvars.bind_contextvars(domain=current_site.domain)

Standard Loggers

It is also possible to log using standard python logger.

In your formatters, add the foreign_pre_chain section, and then add structlog.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 need
                structlog.processors.TimeStamper(fmt="iso"),
                structlog.stdlib.add_logger_name,
                structlog.stdlib.add_log_level,
                structlog.stdlib.PositionalArgumentsFormatter(),
            ],
        },
    },
    #...
 }

Example outputs

Flat lines file (logs/flat_lines.log)

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=200
timestamp='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=201
timestamp='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'

Json file (logs/json.log)

{"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"}

Upgrade Guide

Upgrading to 11.0+

Minimum requirements

requires python 3.11+
requires django 5.2+
(when using celery) requires celery 5.5+

Upstream x-request-id and x-correlation-id headers

x-request-id and x-correlation-id are not trusted by default anymore. If you want to preserve the previous behavior or start to use them, use DJANGO_STRUCTLOG_TRUST_UPSTREAM_REQUEST_ID = True and/or DJANGO_STRUCTLOG_TRUST_UPSTREAM_CORRELATION_ID = True.

Upgrading to 10.0+

Minimum requirements

requires python 3.10+

Upgrading to 9.0+

Minimum requirements

requires python 3.9+
django 4.2 and 5.0+ are supported

Type hints

django-structlog now uses python type hints and is being validated with mypy --strict.

For drf-standardized-errors users

Now unhandled exceptions when using drf-standardized-errors will be intercepted and the exception logged properly.

If you also use structlog-sentry, the exception will now be propagated as expected.

Other libraries alike may be affected by this change.

Internal changes in how RequestMiddleware handles exceptions

This only affects you if you implemented a middleware inheriting from RequestMiddleware and you overrode the process_exception method.

Did you?

If so:

RequestMiddleware.process_exception was renamed to RequestMiddleware._process_exception, you should to the same in the middleware.

Upgrading to 8.0+

A new keyword argument log_kwargs was 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:

from django.contrib.sites.shortcuts import get_current_site
from django.dispatch import receiver
from django_structlog import signals
import structlog

@receiver(signals.bind_extra_request_metadata)
def my_receiver(request, logger, log_kwargs, **kwargs): # <- add `log_kwargs` if necessary
    ...

@receiver(signals.bind_extra_request_finished_metadata)
def my_receiver_finished(request, logger, response, log_kwargs, **kwargs): # <- add `log_kwargs` if necessary
    ...

@receiver(signals.bind_extra_request_failed_metadata)
def my_receiver_failed(request, logger, exception, log_kwargs, **kwargs): # <- add `log_kwargs` if necessary
    ...

Upgrading to 7.0+

The dependency django-ipware was upgraded to version 6. This library is used to retrieve the request’s ip address.

Version 6 may have some breaking 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.

Upgrading to 6.0+

Minimum requirements

requires python 3.8+

Changes to do

Add django_structlog to installed app

INSTALLED_APP = [
    # ...
    "django_structlog",
    # ...
]

Make sure you use django_structlog.middlewares.RequestMiddleware

If you used any of the experimental async or sync middlewares, you do not need to anymore. Make sure you use django_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
]

(If you use celery) Make sure you use DJANGO_STRUCTLOG_CELERY_ENABLED = True

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

Upgrading to 5.0+

Minimum requirements

requires asgiref 3.6+

Upgrading to 4.0+

django-structlog drops support of django below 3.2.

Minimum requirements

requires django 3.2+
requires python 3.7+
requires structlog 21.4.0+
(optionally) requires celery 5.1+

Changes if you use celery

You can now install django-structlog explicitly with celery extra in order to validate the compatibility with your version of celery.

django-structlog[celery]==4.0.0

See Installing “Extras” for more information about this pip feature.

Upgrading to 3.0+

django-structlog now use structlog.contextvars.bind_contextvars instead of threadlocal.

Minimum requirements

requires python 3.7+
requires structlog 21.4.0+

Changes you need to do

1. Update structlog settings

add structlog.contextvars.merge_contextvars as first processors
remove context_class=structlog.threadlocal.wrap_dict(dict),
(if you use standard loggers) add structlog.contextvars.merge_contextvars in foreign_pre_chain
(if you use standard loggers) remove django_structlog.processors.inject_context_dict,

structlog.configure(
    processors=[
        structlog.contextvars.merge_contextvars, # <---- add this
        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,
    ],
    # context_class=structlog.threadlocal.wrap_dict(dict), # <---- remove this
    logger_factory=structlog.stdlib.LoggerFactory(),
    cache_logger_on_first_use=True,
)

# If you use standard logging
LOGGING = {
    "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 this
                structlog.processors.TimeStamper(fmt="iso"),
                structlog.stdlib.add_logger_name,
                structlog.stdlib.add_log_level,
                structlog.stdlib.PositionalArgumentsFormatter(),
            ],
        },
    },
    #...
 }

2. Replace all logger.bind with structlog.contextvars.bind_contextvars

@receiver(bind_extra_request_metadata)
def bind_domain(request, logger, **kwargs):
    current_site = get_current_site(request)
    # logger.bind(domain=current_site.domain)
    structlog.contextvars.bind_contextvars(domain=current_site.domain)

Upgrading to 2.0+

django-structlog was originally developed using the debug configuration ExceptionPrettyPrinter 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.

Running the tests

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 redis
pip install -r requirements.txt
env DJANGO_SETTINGS_MODULE=config.settings.test pytest test_app
env DJANGO_SETTINGS_MODULE=config.settings.test_demo_app pytest django_structlog_demo_project
docker compose stop redis

Demo app

docker compose up --build

Open http://127.0.0.1:8000/ in your browser.

Navigate while looking into the log files and shell’s output.

Authors

Jules Robichaud-Gagnon - Initial work - jrobichaud

See also the list of contributors who participated in this project.

Acknowledgments

Very huge thanks to my awesome 🦄 and generous employer TLM 🩵💜❤️🧡💚🐈‍⬛ for letting me maintain this project on my work hours because it believes in open source.
Big thanks to @ferd for his bad opinions that inspired the author enough to spend time on this library.
This issue helped the author to figure out how to integrate structlog in Django.
This stack overflow question was also helpful.

License

This project is licensed under the MIT License - see the LICENSE file for details

Metadata

Release files for django-structlog 11.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for django-structlog 11.0.0
File	Size	Uploaded	Provenance
django_structlog-11.0.0.tar.gz	25.2 kB	Oct 24, 2026	With provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for django-structlog 11.0.0
File	Interpreter	ABI	Platform	Reset
django_structlog-11.0.0-py3-none-any.whl 21.0 kB Oct 24, 2026 With provenance	Python 3	none	any	Details

Total release size: 46.2 kB

Release files / django_structlog-11.0.0.tar.gz

Download URL	django_structlog-11.0.0.tar.gz
Size	25.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`4ec327f669543b05941c5a1ba7881e9a400493a0098d71a5dce0fc7b0ce97558`
BLAKE2b-256 checksum How to use checksums	`cc50ddd2c8f0477b964d162271bbf28c5a3d1f98f4b6fbf72b2527a1ea76f86e`
Upload date	Oct 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/jrobichaud/django-structlog
Publishing commit: github.com/jrobichaud/django-structlog/tree/b4e1108f3f9de2d0a5a0ce97b4ce4b5fc25912e6

Workflow

Publishing configuration: github.com/jrobichaud/django-structlog/blob/b4e1108f3f9de2d0a5a0ce97b4ce4b5fc25912e6/.github/workflows/main.yml
Publishing logs: github.com/jrobichaud/django-structlog/actions/runs/40119024266/attempts/1

Artifact

Subject: django_structlog-11.0.0.tar.gz
SHA-256 checksum: 4ec327f669543b05941c5a1ba7881e9a400493a0098d71a5dce0fc7b0ce97558 Verifying attestations

Release files / django_structlog-11.0.0-py3-none-any.whl

Download URL	django_structlog-11.0.0-py3-none-any.whl
Size	21.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`4f5d3822bfa1667fec6324e959b6824a4c3fd975b0d5143f0b5bec3ec97f3463`
BLAKE2b-256 checksum How to use checksums	`ff366e3742fd9c8f151563e08f5be19128497ad31110ca719d7a08cf94b5e95e`
Upload date	Oct 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/jrobichaud/django-structlog
Publishing commit: github.com/jrobichaud/django-structlog/tree/b4e1108f3f9de2d0a5a0ce97b4ce4b5fc25912e6

Workflow

Publishing configuration: github.com/jrobichaud/django-structlog/blob/b4e1108f3f9de2d0a5a0ce97b4ce4b5fc25912e6/.github/workflows/main.yml
Publishing logs: github.com/jrobichaud/django-structlog/actions/runs/40119024266/attempts/1

Artifact

Subject: django_structlog-11.0.0-py3-none-any.whl
SHA-256 checksum: 4f5d3822bfa1667fec6324e959b6824a4c3fd975b0d5143f0b5bec3ec97f3463 Verifying attestations

Security for django-structlog 11.0.0

Report project as malware

Provenance

Full provenance

All 2 files in this release have been uploaded with provenance metadata.

Attestation for django_structlog-11.0.0.tar.gz

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/jrobichaud/django-structlog
Publishing commit: github.com/jrobichaud/django-structlog/tree/b4e1108f3f9de2d0a5a0ce97b4ce4b5fc25912e6

Workflow

Publishing configuration: github.com/jrobichaud/django-structlog/blob/b4e1108f3f9de2d0a5a0ce97b4ce4b5fc25912e6/.github/workflows/main.yml
Publishing logs: github.com/jrobichaud/django-structlog/actions/runs/40119024266/attempts/1

Artifact

Subject: django_structlog-11.0.0.tar.gz
SHA-256 checksum: 4ec327f669543b05941c5a1ba7881e9a400493a0098d71a5dce0fc7b0ce97558 Verifying attestations

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.