diff --git a/CHANGES/6248.doc b/CHANGES/6248.doc new file mode 100644 index 0000000000..4f41b2650d --- /dev/null +++ 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 index 23e2e1e0b0..8d895020cc 100644 --- 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 new file mode 100644 index 0000000000..3ce68fc4fd --- /dev/null +++ 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 index 54db181a6d..8e0210cd54 100644 --- 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/).