# API documentation

## django_structlog

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

class django_structlog.middlewares.RequestMiddleware(get_response: Callable[[HttpRequest], HttpResponse | Awaitable[HttpResponse]])

  Bases: `object`

  `RequestMiddleware` adds request metadata to `structlog`’s logger context automatically.

      >>> MIDDLEWARE = [
      ...     # ...
      ...     'django_structlog.middlewares.RequestMiddleware',
      ... ]

  async_capable = True
  classmethod bind_ip(request: HttpRequest) → None
  static bind_user_id(request: HttpRequest) → None
  static format_request(request: HttpRequest) → str
  handle_response(request: HttpRequest, response: HttpResponse) → None
  prepare(request: HttpRequest) → None
  process_got_request_exception(sender: Type[Any], request: HttpRequest, **kwargs: Any) → None
  sync_capable = True

django_structlog.signals.bind_extra_request_failed_metadata = <django.dispatch.dispatcher.Signal object>

  Signal to add extra `structlog` bindings from `django`’s failed request and exception.

  Parameters:

    - logger – the logger

    - exception – the exception resulting of the request

    - log_kwargs – dictionary of log metadata for the `request_failed` event. It contains `request` and `code` keys. You may modify it to add extra information.

      >>> 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_failed_metadata)
      ... def bind_domain(request, logger, exception, log_kwargs, **kwargs):
      ...     current_site = get_current_site(request)
      ...     structlog.contextvars.bind_contextvars(domain=current_site.domain)

django_structlog.signals.bind_extra_request_finished_metadata = <django.dispatch.dispatcher.Signal object>

  Signal to add extra `structlog` bindings from `django`’s finished request and response.

  Parameters:

    - logger – the logger

    - response – the response resulting of the request

    - log_kwargs – dictionary of log metadata for the `request_finished` event. It contains `request` and `code` keys. You may modify it to add extra information.

      >>> 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_finished_metadata)
      ... def bind_domain(request, logger, response, log_kwargs, **kwargs):
      ...     current_site = get_current_site(request)
      ...     structlog.contextvars.bind_contextvars(domain=current_site.domain)

django_structlog.signals.bind_extra_request_metadata = <django.dispatch.dispatcher.Signal object>

  Signal to add extra `structlog` bindings from `django`’s request.

  Parameters:

    - request – the request returned by the view

    - logger – the logger

    - log_kwargs – dictionary of log metadata for the `request_started` event. It contains `request` and `user_agent` keys. You may modify it to add extra information.

      >>> 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, log_kwargs, **kwargs):
      ...     current_site = get_current_site(request)
      ...     structlog.contextvars.bind_contextvars(domain=current_site.domain)

django_structlog.signals.update_failure_response = <django.dispatch.dispatcher.Signal object>

  Signal to update response failure response before it is returned.

  Parameters:

    - request – the request returned by the view

    - response – the response resulting of the request

    - logger – the logger

    - exception – the exception

      >>> from django.dispatch import receiver
      >>> from django_structlog import signals
      >>> import structlog
      >>>
      >>> @receiver(signals.update_failure_response)
      ... def add_request_id_to_error_response(request, response, logger, exception, **kwargs):
      ...     context = structlog.contextvars.get_merged_contextvars(logger)
      ...     response['X-Request-ID'] = context["request_id"]

## django_structlog.celery

`celery` integration for `django_structlog`.

class django_structlog.celery.steps.DjangoStructLogInitStep(parent: Any, **kwargs: Any)

  Bases: `Step`

  `celery` worker boot step to initialize `django_structlog`.

      >>> from celery import Celery
      >>> from django_structlog.celery.steps import DjangoStructLogInitStep
      >>>
      >>> app = Celery("django_structlog_demo_project")
      >>> app.steps['worker'].add(DjangoStructLogInitStep)

  name = 'django_structlog.celery.steps.DjangoStructLogInitStep'

django_structlog.celery.signals.bind_extra_task_metadata = <django.dispatch.dispatcher.Signal object>

  Signal to add extra `structlog` bindings from `celery`’s task.

  Parameters:

    - task – the celery task being run

    - logger – the logger to bind more metadata or override existing bound metadata

      >>> from django.dispatch import receiver
      >>> from django_structlog.celery import signals
      >>> import structlog
      >>>
      >>> @receiver(signals.bind_extra_task_metadata)
      ... def receiver_bind_extra_task_metadata(sender, signal, task=None, logger=None, **kwargs):
      ...     structlog.contextvars.bind_contextvars(correlation_id=task.request.correlation_id)

django_structlog.celery.signals.modify_context_before_task_publish = <django.dispatch.dispatcher.Signal object>

  Signal to modify context passed over to `celery` task’s context. You must modify the `context` dict.

  Parameters:

    - context – the context dict that will be passed over to the task runner’s logger

    - task_routing_key – routing key of the task

    - task_properties – task’s message properties

      >>> from django.dispatch import receiver
      >>> from django_structlog.celery import signals
      >>>
      >>> @receiver(signals.modify_context_before_task_publish)
      ... def receiver_modify_context_before_task_publish(sender, signal, context, task_routing_key=None, task_properties=None, **kwargs):
      ...     keys_to_keep = {"request_id", "parent_task_id"}
      ...     new_dict = {
      ...         key_to_keep: context[key_to_keep]
      ...         for key_to_keep in keys_to_keep
      ...         if key_to_keep in context
      ...     }
      ...     context.clear()
      ...     context.update(new_dict)

django_structlog.celery.signals.pre_task_succeeded = <django.dispatch.dispatcher.Signal object>

  Signal to add `structlog` bindings from `celery`’s successful task.

  Parameters:

    - logger – the logger to bind more metadata or override existing bound metadata

    - result – result of the succeeding task

      >>> from django.dispatch import receiver
      >>> from django_structlog.celery import signals
      >>> import structlog
      >>>
      >>> @receiver(signals.pre_task_succeeded)
      ... def receiver_pre_task_succeeded(sender, signal, logger=None, result=None, **kwargs):
      ...     structlog.contextvars.bind_contextvars(result=str(result))