# django-structlog

|pypi| |wheels| |build-status| |docs| |coverage| |open_issues| |pull_requests|
|django| |python| |license| |black| |ruff|
|django_packages|
|watchers| |stars| |forks|

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.

## 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

# Contents, indices and tables

- Getting Started
  - Installation
  - Extending Request Log Metadata
  - Standard Loggers
- Configuration
  - Settings
- Celery Integration
  - Getting Started with Celery
  - Signals
- Commands
  - Prerequisites
  - Configuration
  - Results
- API documentation
  - django_structlog
  - django_structlog.celery
- Events and Metadata
  - Django’s RequestMiddleware
  - Celery
- Example outputs
  - Flat lines file (`logs/flat_lines.log`)
  - Json file (`logs/json.log`)
- How Tos
  - Bind `request_id` to response’s header
  - Bind `rest_framework_simplejwt` token’s user id
  - Bind AWS’s `X-Amzn-Trace-Id`
  - Filter logs from being recorded
- Running the tests
- Development
  - Prerequisites
  - Installation
  - Start Demo App
  - Building, Serving and Testing the Documentation Locally
- Demo app
- Change Log
  - 10.1.0 (May 30, 2025)
  - 10.0.0 (October 22, 2025)
  - 9.1.1 (April 7, 2025)
  - 9.1.0 (April 4, 2025)
  - 9.0.1 (January 29, 2025)
  - 9.0.0 (November 26, 2024)
  - 8.1.0 (May 24, 2024)
  - 8.0.0 (March 13, 2024)
  - 7.1.0 (December 20, 2023)
  - 7.0.0 (December 13, 2023)
  - 6.0.1 (November 29, 2023)
  - 6.0 (October 3, 2023)
  - 5.3.0 (June 30, 2023)
  - 5.2.0 (June 29, 2023)
  - 5.1.0 (April 22, 2023)
  - 5.0.2 (April 16, 2023)
  - 5.0.1 (March 24, 2023)
  - 5.0.0 (March 23, 2023)
  - 4.1.1 (February 7, 2023)
  - 4.1.0 (February 4, 2023)
  - 4.0.1 (October 25, 2022)
  - 4.0.0 (October 22, 2022)
  - 3.0.1 (August 2, 2022)
  - 3.0.0 (August 1, 2022)
  - 2.2.0 (November 18, 2021)
  - 2.1.3 (September 28, 2021)
  - 2.1.2 (August 31, 2021)
  - 2.1.1 (June 22, 2021)
  - 2.1.0 (November 26, 2020)
  - 2.0.0 (November 25, 2020)
  - 1.6.3 (November 11, 2020)
  - 1.6.2 (October 4, 2020)
  - 1.6.1 (August 13, 2020)
  - 1.6.0 (June 17, 2020)
  - 1.5.5 (June 16, 2020)
  - 1.5.4 (June 15, 2020)
  - 1.5.3 (June 15, 2020)
  - 1.5.2 (April 2, 2020)
  - 1.5.1 (March 18, 2020)
  - 1.5.0 (March 6, 2020)
  - 1.4.1 (February 8, 2020)
  - 1.4.0 (February 7, 2020)
  - 1.3.5 (December 23, 2019)
  - 1.3.4 (November 27, 2019)
  - 1.3.3 (October 6, 2019)
  - 1.3.2 (September 21, 2019)
  - 1.3.1 (September 4, 2019)
  - 1.3.0 (September 3, 2019)
  - 1.2.3 (May 18, 2019)
  - 1.2.2 (May 13, 2019)
  - 1.2.1 (May 8, 2019)
  - 1.2.0 (May 8, 2019)
  - 1.1.6 (May 8, 2019)
  - 1.1.5 (May 8, 2019)
  - 1.1.4 (April 22, 2019)
  - 1.1.3 (April 22, 2019)
  - 1.1.2 (April 19, 2019)
  - 1.1.1 (April 18, 2019)
  - 1.1 (April 16, 2019)
  - 1.0.4 to 1.0.7 (April 14, 2019)
  - 1.0.3 (April 14, 2019)
  - 1.0.2 (April 13, 2019)
  - 1.0.0 (April 13, 2019)
- Upgrade Guide
  - Upgrading to 10.0+
  - Upgrading to 9.0+
  - Upgrading to 8.0+
  - Upgrading to 7.0+
  - Upgrading to 6.0+
  - Upgrading to 5.0+
  - Upgrading to 4.0+
  - Upgrading to 3.0+
  - Upgrading to 2.0+
- Authors
- Acknowledgments
- Licence

- Index

- Module Index

- Search Page