Skip to content

Commit 3c59500

Browse files
sondrelgsondrelg
committed
docs: Create markdown readme
Contains rewrites
1 parent 4d6fc81 commit 3c59500

File tree

1 file changed

+199
-0
lines changed

1 file changed

+199
-0
lines changed

‎README.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
[![package version](https://img.shields.io/pypi/v/django-guid.svg)](https://pypi.org/pypi/django-guid)
2+
[![codecov](https://codecov.io/gh/snok/django-guid/branch/master/graph/badge.svg)](https://codecov.io/gh/snok/django-guid)
3+
[![downloads](https://img.shields.io/badge/python-3.7+-blue.svg)](https://pypi.python.org/pypi/django-guid#downloads)
4+
[![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)
5+
[![asgi](https://img.shields.io/badge/ASGI-supported-brightgreen.svg)](https://img.shields.io/badge/ASGI-supported-brightgreen.svg)
6+
[![wsgi](https://img.shields.io/badge/WSGI-supported-brightgreen.svg)](https://img.shields.io/badge/WSGI-supported-brightgreen.svg)
7+
8+
# Django GUID
9+
10+
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)
11+
(also knows as request IDs) for incoming requests. Once an ID is defined, it may be attached to application
12+
logs as a filter. This makes it easy to correlate logs from a single HTTP request, and makes debugging simple.
13+
14+
For the purposes of this package, a GUID (globally unique identifier) is equivalent
15+
to a UUID (universally unique identifier).
16+
17+
## Examples
18+
19+
Here is an example, containing logs from 3 different requests, with a request-id filter:
20+
21+
```regexp
22+
INFO ... [773fa6885e03493498077a273d1b7f2d] project.views This is a DRF view log, and should have a GUID.
23+
WARNING ... [773fa6885e03493498077a273d1b7f2d] project.services.file Some warning in a function
24+
INFO ... [0d1c3919e46e4cd2b2f4ac9a187a8ea1] project.views This is a DRF view log, and should have a GUID.
25+
INFO ... [99d44111e9174c5a9494275aa7f28858] project.views This is a DRF view log, and should have a GUID.
26+
WARNING ... [0d1c3919e46e4cd2b2f4ac9a187a8ea1] project.services.file Some warning in a function
27+
WARNING ... [99d44111e9174c5a9494275aa7f28858] project.services.file Some warning in a function
28+
```
29+
30+
The correlation ID makes it possible to tell which logs belong to which request. Here are the same logs, without the filter:
31+
32+
```regexp
33+
INFO ... project.views This is a DRF view log, and should have a GUID.
34+
WARNING ... project.services.file Some warning in a function
35+
INFO ... project.views This is a DRF view log, and should have a GUID.
36+
INFO ... project.views This is a DRF view log, and should have a GUID.
37+
WARNING ... project.services.file Some warning in a function
38+
WARNING ... project.services.file Some warning in a function
39+
```
40+
41+
## Installation
42+
43+
```shell
44+
pip install django-guid
45+
```
46+
47+
## Settings
48+
49+
Package settings are added in your `settings.py`:
50+
51+
```python
52+
DJANGO_GUID = {
53+
'GUID_HEADER_NAME': 'X-Request-ID',
54+
'VALIDATE_GUID': True,
55+
'RETURN_HEADER': True,
56+
'EXPOSE_HEADER': True,
57+
'INTEGRATIONS': [],
58+
'IGNORE_URLS': [],
59+
'UUID_LENGTH': 32,
60+
}
61+
```
62+
63+
64+
**Optional Parameters**
65+
66+
* `GUID_HEADER_NAME`
67+
68+
> The name of the GUID to look for in a header in an incoming request. Remember that it's case insensitive.
69+
70+
Default: `Correlation-ID`
71+
72+
* `VALIDATE_GUID`
73+
> Whether the `GUID_HEADER_NAME` should be validated or not.
74+
If the GUID sent to through the header is not a valid GUID (`uuid.uuid4`).
75+
76+
Default: `True`
77+
78+
* `RETURN_HEADER`
79+
> Whether to return the GUID (Correlation-ID) as a header in the response or not.
80+
It will have the same name as the `GUID_HEADER_NAME` setting.
81+
82+
Default: `True`
83+
84+
* `EXPOSE_HEADER`
85+
> Whether to return `Access-Control-Expose-Headers` for the GUID header if
86+
`RETURN_HEADER` is `True`, has no effect if `RETURN_HEADER` is `False`.
87+
This is allows the JavaScript Fetch API to access the header when CORS is enabled.
88+
89+
Default: `True`
90+
91+
* `INTEGRATIONS`
92+
> Whether to enable any custom or available integrations with `django_guid`.
93+
As an example, using `SentryIntegration()` as an integration would set Sentry's `transaction_id` to
94+
match the GUID used by the middleware.
95+
96+
Default: `[]`
97+
98+
* `IGNORE_URLS`
99+
> URL endpoints where the middleware will be disabled. You can put your health check endpoints here.
100+
101+
Default: `[]`
102+
103+
* `UUID_LENGTH`
104+
> Lets you optionally trim the length of the package generated UUIDs.
105+
106+
Default: `32`
107+
108+
## Configuration
109+
110+
111+
Once settings have set up, add the following to your projects' `settings.py`:
112+
113+
### 1. Installed apps
114+
115+
Add `django_guid` to your `INSTALLED_APPS`:
116+
117+
```python
118+
INSTALLED_APPS = [
119+
'django_guid',
120+
]
121+
```
122+
123+
### 2. Middleware
124+
125+
Add the `django_guid.middleware.guid_middleware` to your `MIDDLEWARE`:
126+
127+
```python
128+
MIDDLEWARE = [
129+
'django_guid.middleware.guid_middleware',
130+
...
131+
]
132+
```
133+
134+
It is recommended that you add the middleware at the top, so that the remaining middleware loggers include the requests GUID.
135+
136+
### 3. Logging configuration
137+
138+
Add `django_guid.log_filters.CorrelationId` as a filter in your `LOGGING` configuration:
139+
140+
```python
141+
LOGGING = {
142+
...
143+
'filters': {
144+
'correlation_id': {
145+
'()': 'django_guid.log_filters.CorrelationId'
146+
}
147+
}
148+
}
149+
```
150+
151+
Put that filter in your handler:
152+
153+
```python
154+
LOGGING = {
155+
...
156+
'handlers': {
157+
'console': {
158+
'class': 'logging.StreamHandler',
159+
'formatter': 'medium',
160+
'filters': ['correlation_id'],
161+
}
162+
}
163+
}
164+
```
165+
166+
And make sure to add the new `correlation_id` filter to one or all of your formatters:
167+
168+
```python
169+
LOGGING = {
170+
...
171+
'formatters': {
172+
'medium': {
173+
'format': '%(levelname)s %(asctime)s [%(correlation_id)s] %(name)s %(message)s'
174+
}
175+
}
176+
}
177+
```
178+
179+
If these settings were confusing, you might find the repo examples helpful.
180+
181+
### 4. Django GUID logger (optional)
182+
183+
If you wish to see the Django GUID middleware outputs, you may configure a logger for the module.
184+
Simply add django_guid to your loggers in the project, like in the example below:
185+
186+
```python
187+
LOGGING = {
188+
...
189+
'loggers': {
190+
'django_guid': {
191+
'handlers': ['console', 'logstash'],
192+
'level': 'WARNING',
193+
'propagate': False,
194+
}
195+
}
196+
}
197+
```
198+
199+
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 commit comments

Comments
 (0)