Expand docs on correlation id

fixes #6248
pulp · Feb 3, 2025 · 21f2c21 · 21f2c21
1 parent 6e333a3
commit 21f2c21
Show file tree

Hide file tree

Showing 4 changed files with 64 additions and 6 deletions.
diff --git a/CHANGES/6248.doc b/CHANGES/6248.doc
@@ -0,0 +1 @@
+Expanded docs on correlation id.
diff --git a/docs/admin/reference/settings.md b/docs/admin/reference/settings.md
@@ -401,12 +401,10 @@ You can update them using:
 
 ### DJANGO_GUID
 
-Pulp uses `django-guid` to append correlation IDs to logging messages. Correlation IDs are
-autogenerated by default but can also be sent as a header with each request. They are also
-returned as a header in the response and are recorded in the `logging_cid` field of tasks.
-
-For more information on how to configure the `DJANGO_GUID` setting, see the [django-guid
-settings documentation](https://django-guid.readthedocs.io/en/latest/settings.html).
+Pulp uses `django-guid` to append correlation IDs to logging messages. For more information on how
+to configure the `DJANGO_GUID` setting, see the [django-guid settings
+documentation](https://django-guid.readthedocs.io/en/latest/settings.html). To read more about using
+correlation id in Pulp, read [our guide](site:pulp/docs/user/guides/correllation-id/).
 
 
 

diff --git a/docs/user/guides/correlation-id.md b/docs/user/guides/correlation-id.md
@@ -0,0 +1,54 @@
+# Correlation ID
+
+Pulp provides support for correlation ids that are helpful to correlate requests to log messages and
+tasks. Correlation IDs are autogenerated by default but can also be set via pulp-cli or sent as a
+header with each request. Correlation ids are also returned as a header in the response and are
+recorded in the `logging_cid` field of tasks.
+
+To view the correlation id for an API request, see the `Correlation-ID` header in the response:
+
+```
+$ http POST ${SERVER_ADDR}${REPO_HREF}sync/
+...
+Correlation-ID: 47ebc1b6a77642e2b9eca645d3277aa5
+...
+```
+
+All log messages in Pulp that are correlated with the request will be prepended with the correlation
+id:
+
+```
+pulp [47ebc1b6a77642e2b9eca645d3277aa5]: 127.0.0.1 - admin [31/Jan/2025:20:09:34 +0000] "POST /pulp/api/v3/repositories/file/file/0194b8e9-5425-799b-ad0a-86c71e160158/sync/ HTTP/1.1" 202 67 "-" "HTTPie/3.2.1"
+pulp [47ebc1b6a77642e2b9eca645d3277aa5]: pulpcore.tasking.tasks:INFO: Starting task 0194bdfb-aa1e-72fb-b3bd-8e6e3f36dedb in domain: default
+pulp [47ebc1b6a77642e2b9eca645d3277aa5]: pulpcore.tasking.tasks:INFO: Task completed 0194bdfb-aa1e-72fb-b3bd-8e6e3f36dedb in domain: default
+```
+
+Any task that was executed will also have the correlation id set on its `logging_cid` field:
+
+```
+$ pulp task list --cid 47ebc1b6a77642e2b9eca645d3277aa5
+...
+    "logging_cid": "47ebc1b6a77642e2b9eca645d3277aa5",
+...
+```
+
+## Setting correlation id
+
+It's possible to set the correlation id using the pulp-cli:
+
+```bash
+$ pulp --cid 1646c5896b48414698a260374dcb6849 file repository sync --name myfilerepo
+```
+
+Or when sending a request directly to Pulp:
+
+```
+$ http ${SERVER_ADDR}${REPO_HREF}sync/ Correlation-ID:1646c5896b48414698a260374dcb6849
+...
+Correlation-ID: 1646c5896b48414698a260374dcb6849
+```
+
+By default Pulp expects a 32 character UUID to be sent via a "Correlation-ID" header. However,
+support for correlation id is highly customizable in terms of what headers Pulp uses and what
+formats it accepts. For information how to customize correlation id header name and format, see [the
+settings documentation](site:pulpcore/docs/admin/reference/settings/#django_guid).
diff --git a/docs/user/guides/troubleshoot-tasks.md b/docs/user/guides/troubleshoot-tasks.md
@@ -46,3 +46,8 @@ Cancel a running task:
 # warning canceling tasks may break higher level workflows
 pulp task cancel --href "$TASK_HREF"
 ```
+
+## Tracing workloads
+
+To help users better trace workloads in Pulp, Pulp provides [support for correlation
+ids](site:pulpcore/docs/user/guides/correlation-id/).