Skip to content

Commit

Permalink
docs: Create markdown readme
Browse files Browse the repository at this point in the history
Contains rewrites
  • Loading branch information
sondrelg committed Nov 27, 2022
1 parent 4d6fc81 commit 2ed63a6
Showing 1 changed file with 202 additions and 0 deletions.
202 changes: 202 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,202 @@
# Django GUID

[![package version](https://img.shields.io/pypi/v/django-guid.svg)](https://pypi.org/pypi/django-guid)
[![codecov](https://codecov.io/gh/snok/django-guid/branch/master/graph/badge.svg)](https://codecov.io/gh/snok/django-guid)
[![downloads](https://img.shields.io/badge/python-3.7+-blue.svg)](https://pypi.python.org/pypi/django-guid#downloads)
[![django versions](https://img.shields.io/pypi/djversions/django-guid?color=0C4B33&logo=django&logoColor=white&label=django)](https://pypi.python.org/pypi/django-guid)
[![asgi](https://img.shields.io/badge/ASGI-supported-brightgreen.svg)](https://img.shields.io/badge/ASGI-supported-brightgreen.svg)
[![wsgi](https://img.shields.io/badge/WSGI-supported-brightgreen.svg)](https://img.shields.io/badge/WSGI-supported-brightgreen.svg)


The middleware adds an ID to your logs that is unique to each incoming request. [Correlation IDs](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields?highlight=x-request-id#:~:text=Csrf%2DToken%3A%20i8XNjC4b8KVok4uw5RftR38Wgp2BFwql-,X%2DRequest%2DID,-%2C%5Bstackoverflow2%201)
(also knows as request IDs) make it easy to correlate logs from a single HTTP request, and makes debugging simple.

Django GUID also includes ways of extending correlation IDs to Celery workers and Sentry issues.

For the purposes of this package, a GUID (globally unique identifier) is equivalent
to a UUID (universally unique identifier).

## Examples

With a request-id filter:

```
INFO [773fa6885e03493498077a273d1b7f2d] project.views Fetching resource
INFO [0d1c3919e46e4cd2b2f4ac9a187a8ea1] project.views Fetching resource
INFO [99d44111e9174c5a9494275aa7f28858] project.views Fetching resource
INFO [99d44111e9174c5a9494275aa7f28858] project.services Finished fetching resource successfully
INFO [773fa6885e03493498077a273d1b7f2d] project.services Finished fetching resource successfully
ERROR [0d1c3919e46e4cd2b2f4ac9a187a8ea1] project.services Something went wrong!
```

The correlation ID makes it possible to know which logs belong to which request.
Here are the same logs, without the filter:

```
INFO project.views Fetching resource
INFO project.views Fetching resource
INFO project.views Fetching resource
INFO project.services Finished fetching resource successfully
INFO project.services Finished fetching resource successfully
ERROR project.services Something went wrong!
```

## Installation

```shell
pip install django-guid
```

## Settings

Package settings are added in your `settings.py`:

```python
DJANGO_GUID = {
'GUID_HEADER_NAME': 'X-Request-ID',
'VALIDATE_GUID': True,
'RETURN_HEADER': True,
'EXPOSE_HEADER': True,
'INTEGRATIONS': [],
'IGNORE_URLS': [],
'UUID_LENGTH': 32,
}
```


**Optional Parameters**

* `GUID_HEADER_NAME`

> The name of the GUID to look for in a header in an incoming request. Remember that it's case insensitive.
Default: `Correlation-ID`

* `VALIDATE_GUID`
> Whether the `GUID_HEADER_NAME` should be validated or not.
If the GUID sent to through the header is not a valid GUID (`uuid.uuid4`).

Default: `True`

* `RETURN_HEADER`
> Whether to return the GUID (Correlation-ID) as a header in the response or not.
It will have the same name as the `GUID_HEADER_NAME` setting.

Default: `True`

* `EXPOSE_HEADER`
> Whether to return `Access-Control-Expose-Headers` for the GUID header if
`RETURN_HEADER` is `True`, has no effect if `RETURN_HEADER` is `False`.
This is allows the JavaScript Fetch API to access the header when CORS is enabled.

Default: `True`

* `INTEGRATIONS`
> Whether to enable any custom or available integrations with `django_guid`.
As an example, using `SentryIntegration()` as an integration would set Sentry's `transaction_id` to
match the GUID used by the middleware.

Default: `[]`

* `IGNORE_URLS`
> URL endpoints where the middleware will be disabled. You can put your health check endpoints here.
Default: `[]`

* `UUID_LENGTH`
> Lets you optionally trim the length of the package generated UUIDs.
Default: `32`

## Configuration


Once settings have set up, add the following to your projects' `settings.py`:

### 1. Installed apps

Add `django_guid` to your `INSTALLED_APPS`:

```python
INSTALLED_APPS = [
'django_guid',
]
```

### 2. Middleware

Add the `django_guid.middleware.guid_middleware` to your `MIDDLEWARE`:

```python
MIDDLEWARE = [
'django_guid.middleware.guid_middleware',
...
]
```

It is recommended that you add the middleware at the top, so that the remaining middleware loggers include the requests GUID.

### 3. Logging configuration

Add `django_guid.log_filters.CorrelationId` as a filter in your `LOGGING` configuration:

```python
LOGGING = {
...
'filters': {
'correlation_id': {
'()': 'django_guid.log_filters.CorrelationId'
}
}
}
```

Put that filter in your handler:

```python
LOGGING = {
...
'handlers': {
'console': {
'class': 'logging.StreamHandler',
'formatter': 'medium',
'filters': ['correlation_id'],
}
}
}
```

And make sure to add the new `correlation_id` filter to one or all of your formatters:

```python
LOGGING = {
...
'formatters': {
'medium': {
'format': '%(levelname)s %(asctime)s [%(correlation_id)s] %(name)s %(message)s'
}
}
}
```

If these settings were confusing, you might find the repo examples helpful.

### 4. Django GUID logger (optional)

If you wish to see the Django GUID middleware outputs, you may configure a logger for the module.
Simply add django_guid to your loggers in the project, like in the example below:

```python
LOGGING = {
...
'loggers': {
'django_guid': {
'handlers': ['console', 'logstash'],
'level': 'WARNING',
'propagate': False,
}
}
}
```

This could be useful for debugging problems with request ID propagation. If a received request header containing a request ID is misconfigured, we will not raise exceptions, but will generate warning logs.

0 comments on commit 2ed63a6

Please sign in to comment.