Quickstart

Requirements

  • Python 3.8 or newer

  • Django 3.2 or newer

  • Optional: celery

Additional requirements are installed along with the package.

Installation

  1. Install from PyPI using pip:

    pip install django-log-outgoing-requests

  2. Add log_outgoing_requests to INSTALLED_APPS in your Django project’s settings.py.

  3. Run python manage.py migrate to create the necessary database tables

If celery is installed in your environment, then the task to reset the admin configuration is automatically enabled.

Configuration

You must configure the LOGGING Django setting to integrate the formatter(s) and/or handler(s). Review the Django documentation about this setting if there is no configuration in place yet.

The snippet below provides an example of configuring the custom formatter and enabling the custom handler to save records to the database.

 1from log_outgoing_requests.formatters import HttpFormatter
 2
 3
 4LOGGING = {
 5    #...,
 6    "formatters": {
 7        #...,
 8        "outgoing_requests": {"()": HttpFormatter},
 9        # optionally provide the 'format' kwarg, like with the default formatter.
10    },
11    "handlers": {
12        #...,
13        "log_outgoing_requests": {
14            "level": "DEBUG",
15            "formatter": "outgoing_requests",
16            "class": "logging.StreamHandler",  # to write to stdout
17        },
18        "save_outgoing_requests": {
19            "level": "DEBUG",
20            # enabling saving to database
21            "class": "log_outgoing_requests.handlers.DatabaseOutgoingRequestsHandler",
22        },
23    },
24    "loggers": {
25        #...,
26        "log_outgoing_requests": {  # the logger name must be 'log_outgoing_requests'
27            "handlers": ["log_outgoing_requests", "save_outgoing_requests"],
28            "level": "DEBUG",
29            "propagate": True,
30        },
31    },
32}

The library ships with safe defaults for settings - essentially only emitting meta-information about requests and responses. To view request and response bodies, you likely want to apply the following non-default settings:

LOG_OUTGOING_REQUESTS_DB_SAVE = True # save logs enabled/disabled based on the boolean value
LOG_OUTGOING_REQUESTS_DB_SAVE_BODY = True # save request/response body
LOG_OUTGOING_REQUESTS_EMIT_BODY = True # log request/response body
LOG_OUTGOING_REQUESTS_MAX_AGE = 1 # delete requests older than 1 day

Note

A number of settings can be configured at runtime in the admin interface:

  • Saving to database (both the entire record and the request/response bodies)

  • Maximum body size

From a security and privacy perspective, we advise not enabling saving to the database by default via Django settings and instead rely on runtime configuration.

If Celery is installed but not configured in your environment, LOG_OUTGOING_REQUESTS_RESET_DB_SAVE_AFTER (which defines if/when database logging is reset after changes to the library config) should be set to None.

The library provides a Django management command as well as a Celery task to delete logs which are older than a specified time (by default, 1 day).

See Settings for all available settings and their meaning.

Usage

You don’t have to do anything in particular to get the functionality. Any request made via the requests library (even in third party packages) will pass through the logging machinery.

Logs

With correct configuration (see above), your logs should now be visible in the configured handler (stdout, file, log aggregation service…).

Additionally, if you have enabled logging to the database, the log records should be visible via Admin > Outgoing request logs > Outgoing request logs.

Runtime configuration

Via Admin > Outgoing request logs > Outgoing request log configuration you can specify/override some settings that influence the logging behaviour.