Managing HTTP correlation IDs

An HTTP correlation ID is a unique ID that you can use to track requests as they make their way through the system.

In a distributed system, a request often travels across multiple subsystems. PingAuthorize adds a correlation ID to every operation associated with that request, so you can locate and group related log messages for that request.

PingAuthorize, PingDirectory, and their related products support correlation IDs for all HTTP requests received through the HTTP(S) Connection Handler. Learn more in Configuring HTTP connection handlers in the PingDirectory documentation.

When PingAuthorize receives an HTTP request, it checks for a recognized correlation ID header (for example, X-Correlation-Id) and uses that value if present. Otherwise, the server generates a new UUID. The server then propagates this ID through the rest of the request lifecycle, including policy evaluation, service-specific handling, and the HTTP response.

The following sections explain how to configure and use these IDs.

Where correlation IDs are recorded

The server records the correlation ID in the following places:

Location Description

Location	Description
HTTP response header	HTTP responses include the correlation ID in a response header (default is `Correlation-Id`).
Trace log	Each trace log entry for a request includes the correlation ID. This includes `GATEWAY REQUEST` and `GATEWAY RESPONSE` entries for API gateway traffic. Other trace messages can also carry the `correlationID` field, such as `HTTP service call`.
HTTP operation or access log	HTTP operation log publishers receive the correlation ID in the request state and write it in both JSON-formatted and text-based HTTP operation log outputs.
Policy decision log	Policy evaluation entries include the correlation ID, enabling you to cross-reference a policy decision with its corresponding trace log entries.
Downstream LDAP server access log	For SCIM requests handled by the LDAP Store Adapter, the server passes the correlation ID to PingDirectory or PingDirectoryProxy as an Intermediate Client Request Control. It appears in the downstream server’s access log under the `via` key. If the server is a PingDirectoryProxy, the control is forwarded in turn to the downstream LDAP server.

HTTP response header

HTTP responses include the correlation ID in a response header (default is Correlation-Id).

Trace log

Each trace log entry for a request includes the correlation ID. This includes GATEWAY REQUEST and GATEWAY RESPONSE entries for API gateway traffic. Other trace messages can also carry the correlationID field, such as HTTP service call.

HTTP operation or access log

HTTP operation log publishers receive the correlation ID in the request state and write it in both JSON-formatted and text-based HTTP operation log outputs.

Policy decision log

Policy evaluation entries include the correlation ID, enabling you to cross-reference a policy decision with its corresponding trace log entries.

Downstream LDAP server access log

For SCIM requests handled by the LDAP Store Adapter, the server passes the correlation ID to PingDirectory or PingDirectoryProxy as an Intermediate Client Request Control. It appears in the downstream server’s access log under the via key. If the server is a PingDirectoryProxy, the control is forwarded in turn to the downstream LDAP server.

HTTP correlation ID examples

The following examples show how to locate log entries using a correlation ID.

Example: Server-generated correlation ID (SCIM)

When a client doesn’t supply a correlation ID header, PingAuthorize generates a UUID and returns it in the response. This example shows how to use that value to find related log entries.

Make a SCIM 2 GET request without a correlation ID header:

GET https://localhost:8443/scim/v2/Me HTTP/1.1
Accept: /
Accept-Encoding: gzip, deflate
Authorization: Bearer ...
Connection: keep-alive
Host: localhost:1443
User-Agent: HTTPie/0.9.9

The response includes a Correlation-Id header with a server-generated UUID. The ellipsis (…) indicates lines removed for brevity.

HTTP/1.1 200 OK
Content-Length: 903
Content-Type: application/scim+json
Correlation-Id: c52af735-788d-4798-be3b-8d1f3c8f9d64
Date: Mon, 15 Mar 2021 15:23:06 GMT
Request-Id: 371

{
    "mail": [
        "user.0@example.com"
    ],
    "initials": [
        "AOR"
    ],
    "homePhone": [
        "+1 295 940 2750"
    ],
    "pager": [
        "+1 604 109 3407"
    ],
    "givenName": [
        "Anett"
    ],
   ...
}

Use the correlation ID value from the response to search the debug trace log for all log entries associated with this request. Replace the example value with the value from your response:

$ grep 'correlationID="c52af735-788d-4798-be3b-8d1f3c8f9d64"' <PAZ_Home>/logs/debug-trace

The output includes one or more trace log entries, such as HTTP REQUEST and HTTP RESPONSE, all sharing the same correlationID value.

Use the same correlation ID to search the policy decision log for the authorization decision made for this request:

$ grep 'correlationID="c52af735-788d-4798-be3b-8d1f3c8f9d64"' <PAZ_Home>/logs/policy-decision

The output includes the policy decision log entry for this request, showing the authorization outcome with the same correlationID value.

Example: Client-supplied correlation ID (API gateway)

When a client supplies a recognized correlation ID header, PingAuthorize uses that value throughout the request lifecycle. For API gateway requests, the correlation ID appears in all five trace log entry types, letting you trace the full path of a request.

Make a gateway request with a Correlation-Id header:

GET /api/orders/42 HTTP/1.1
Host: paz.example.com
Authorization: Bearer eyJ...
Correlation-Id: f47ac10b-58cc-4372-a567-0e02b2c3d479

Search the debug trace log for the supplied correlation ID value:

$ grep 'correlationID="f47ac10b-58cc-4372-a567-0e02b2c3d479"' <PAZ_Home>/logs/debug-trace

The output includes all five trace log entry types for this request, each including the same correlationID value:

... HTTP REQUEST requestID=123 correlationID="f47ac10b-58cc-4372-a567-0e02b2c3d479" method=GET url="https://paz.example.com:443/api/orders/42" ...
... GATEWAY REQUEST requestID=123 correlationID="f47ac10b-58cc-4372-a567-0e02b2c3d479" method=GET url="https://backend.internal:8080/api/orders/42" ...
... POLICY REQUEST requestID=123 correlationID="f47ac10b-58cc-4372-a567-0e02b2c3d479" trustFrameworkVersion="V2" ...
... POLICY RESULT requestID=123 correlationID="f47ac10b-58cc-4372-a567-0e02b2c3d479" authorized="true" decision="PERMIT" ...
... GATEWAY RESPONSE requestID=123 correlationID="f47ac10b-58cc-4372-a567-0e02b2c3d479" status=200 ...
... HTTP RESPONSE requestID=123 correlationID="f47ac10b-58cc-4372-a567-0e02b2c3d479" status=200 ...

Configuration properties

The following connection handler properties control correlation ID behavior:

correlation-id-request-header: The request headers the server checks for a correlation ID, in the order listed. If a request includes more than one, the server uses the first match. Learn more in Configuring correlation IDs.
correlation-id-response-header: The name of the correlation ID header returned in HTTP responses. The default is Correlation-Id. Learn more in Configuring correlation IDs.
use-correlation-id-header: Set to false to disable correlation ID tracking entirely. When disabled, PingAuthorize doesn’t record the correlationID field in any log entries. Learn more in Enabling or disabling correlation ID support.

Server SDK support

For Server SDK extensions that have access to the current HttpServletRequest, the extension can retrieve the current correlation ID as a string through the HttpServletRequest's com.pingidentity.pingdata.correlation_id attribute.

For example:

(String) request.getAttribute("com.pingidentity.pingdata.correlation_id");