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 3c59500
Showing 1 changed file with 199 additions and 0 deletions.
199 changes: 199 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,199 @@
[![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)

# Django GUID

Django GUID loads or generates [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) for incoming requests. Once an ID is defined, it may be attached to application
logs as a filter. This makes it easy to correlate logs from a single HTTP request, and makes debugging simple.

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

## Examples

Here is an example, containing logs from 3 different requests, with a request-id filter:

```regexp
INFO ... [773fa6885e03493498077a273d1b7f2d] project.views This is a DRF view log, and should have a GUID.
WARNING ... [773fa6885e03493498077a273d1b7f2d] project.services.file Some warning in a function
INFO ... [0d1c3919e46e4cd2b2f4ac9a187a8ea1] project.views This is a DRF view log, and should have a GUID.
INFO ... [99d44111e9174c5a9494275aa7f28858] project.views This is a DRF view log, and should have a GUID.
WARNING ... [0d1c3919e46e4cd2b2f4ac9a187a8ea1] project.services.file Some warning in a function
WARNING ... [99d44111e9174c5a9494275aa7f28858] project.services.file Some warning in a function
```

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

```regexp
INFO ... project.views This is a DRF view log, and should have a GUID.
WARNING ... project.services.file Some warning in a function
INFO ... project.views This is a DRF view log, and should have a GUID.
INFO ... project.views This is a DRF view log, and should have a GUID.
WARNING ... project.services.file Some warning in a function
WARNING ... project.services.file Some warning in a function
```

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

Please sign in to comment.