Skip to content

Commit 002dd25

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

File tree

1 file changed

+200
-0
lines changed

1 file changed

+200
-0
lines changed

‎README.md‎

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