Skip to content

Correlating with your logs

A request that went wrong leaves a trace in three places: your client, GraphPilot, and your origin. This guide joins them, so an investigation that starts in any one of them can continue in the other two. GraphPilot gives you two ids to join on:

  • The request id, which GraphPilot mints for every request it handles and records the request under. You can send it to your origin and to the caller.
  • A correlation id, which your client chooses and sends. GraphPilot records it with the request and on every log line for it.

The running example is a checkout flow whose client already sends x-correlation-id on every call, and whose origin logs x-request-id beside each request line.

What you need

Section titled “What you need”
  • A deployed service and its gpilot.toml.
  • An origin that logs a request header of your choice, and a client that can send one.

1. Send the request id to your origin

Section titled “1. Send the request id to your origin”

Name the header your origin already logs:

gpilot.toml
[origin]
request_id_header = "x-request-id"

Every request that reaches your origin now carries GraphPilot’s id under that name. If a client sends a header of the same name, GraphPilot’s value replaces it. A name in the gp- namespace, or one that is not a valid header name, refuses the deployment. Details are on request ids.

2. Show it to the caller

Section titled “2. Show it to the caller”
gpilot.toml
[response]
request_id_header = true

Every response now carries gp-request-id. A customer opening a support case can quote it, and your client can log it next to its own error.

3. Read your client’s correlation id

Section titled “3. Read your client’s correlation id”

By default GraphPilot reads a correlation id from GP-Correlation-ID. Your client already sends its own header, so name that one instead:

gpilot.toml
[telemetry]
correlation_header = "x-correlation-id"

GraphPilot records the value with the request and forwards the header to your origin unchanged. Nothing is generated when the header is missing: that request simply has no correlation id. The default GP-Correlation-ID is forwarded too, although it is in the reserved gp- namespace. See correlation ids.

Keep the two names apart. If origin.request_id_header and telemetry.correlation_header were the same, GraphPilot’s request id would replace your client’s correlation id on its way to your origin.

Deploy with gpilot deploy.

4. Find a request from either end

Section titled “4. Find a request from either end”

From your origin’s log line, take the x-request-id value. In Insights, the request list’s Request ID column (every plan; add it under Columns, it is hidden by default) shows it, and the request’s Overview tab shows it as Entry ID.

From your client’s correlation id, filter by it:

Terminal window
gpilot requests --correlation-id checkout-42 --since 1h

In Insights, type correlation.id:checkout-42 into the filter bar. Filtering by correlation id, in the portal and in the CLI, needs Airliner (Business) or above. On every plan, the request’s Overview tab shows its Correlation ID and Entry ID, so you can narrow the list by path, status and time and read both ids there.

From a customer’s gp-request-id, it is the same id your origin logged, so search your logs for it first.

Check that it works

Section titled “Check that it works”

Send one request with a correlation id and read the id back:

Terminal window
curl -sS -D- -o/dev/null "https://$GRAPHPILOT_HOST/products/42" \
  -H 'x-correlation-id: checkout-42' | grep -iE '^gp-(cache|request-id):'
gp-cache: MISS
gp-request-id: <request id>

Your origin’s log has a line for that request with that <request id> as x-request-id, and x-correlation-id: checkout-42. Insights shows the request with both. Send the request again: now gp-cache: HIT, a new gp-request-id, and no line in your origin’s log.

Pitfalls

Section titled “Pitfalls”
  • A cache hit never reaches your origin. A request id GraphPilot reported that your origin has no record of is normally a hit, not a lost request. Read gp-cache to tell them apart.
  • Only stored telemetry can be searched. Insights and gpilot requests read request telemetry, which is stored up to your plan’s logged-request allowance, not while the account runs in lean mode, and not for a request the service leaves out with telemetry.record. For a request that was not stored, the response headers and your origin’s log are the evidence.
  • A correlation id is whatever the client sent. It is for joining logs, not for trusting. Do not partition or authorize on it.
  • The CLI finds a request by its id. gpilot requests --request-id <ID>, and it prints each row’s id as id with -o json. It also finds requests by correlation id, path, method, status, operation, surrogate key or client IP (each filter needs the same plan as in Insights), and --wide adds the id to the table. In Insights, the Request ID column shows the id of every listed request.
Section titled “Related”