GraphQL
`traceReport(input:)` returns summary, selectors, service hops, failures, gaps, query model, and freshness. `traceReportJob(input:)` uses the same selector for larger batches.
Traceability
One action ID from browser click to partner callback.
KarmanFlow uses one canonical business correlation ID plus W3C trace context so operators, partners, and agent clients can pull one report instead of stitching logs by hand.
Trace path
One ID travels through every handoff.
The report starts from the business action ID, follows W3C trace context through each service hop, and marks any missing receipt, span, log, or export row as a gap.
Browser
Edge
GraphQL API
Worker
Connector
Partner callback
Report
Canonical headers
The headers every service and extension must preserve.
The KarmanFlow correlation header is the only accepted business action key. `traceparent` carries the distributed trace. Request and causation IDs explain each hop.
| Header | Rule | Value | Purpose |
|---|---|---|---|
x-karmanflow-correlation-id | Required after ingress | kfcor_<uuidv7> | Stable business action ID across retries, jobs, callbacks, receipts, logs, and reports. |
traceparent | Required when caller has a W3C trace | W3C Trace Context | Distributed trace ID and span parent for Cloud Trace and OTel joins. |
tracestate | Optional | W3C Trace Context | Vendor trace state. Preserve when forwarding. |
x-karmanflow-request-id | Required per hop | kfreq_<uuidv7> | One HTTP request, queue attempt, or worker attempt. |
x-karmanflow-causation-id | Required when caused by prior work | Command, event, job, or delivery attempt ID | Direct parent action that caused the next action. |
x-karmanflow-external-correlation-id | Optional | Partner-owned ID | Partner lookup key stored separately from the KarmanFlow correlation ID. |
Report surfaces
The same trace report is available to humans, agents, and client tools.
The runtime report starts with DB receipts and events, then joins Cloud Trace, Cloud Logging, and the trace index as those exporters are enabled in the environment.
MCP
`karmanflow.trace.report` and `karmanflow.trace.search` expose the same report spine to agent clients with the same scope checks.
Operations index
Cloud Logging, Cloud Trace, and the BigQuery trace index join on canonical correlation ID and W3C trace ID.
Partner extensions
Connector SDK helpers mint IDs, build canonical headers, and reject non-canonical correlation IDs before delivery.
Examples
Ask for one bounded report.
Interactive reports are capped at 100 correlation IDs and a 7-day window. Larger batches should run as report jobs against exported evidence.
GraphQL
query TraceReport($input: TraceReportInput!) {
traceReport(input: $input) {
summary
serviceHops
failures
gaps
queryModel
freshness
}
}MCP
{
"tool": "karmanflow.trace.report",
"input": {
"tenantId": "tnt_acme",
"environmentId": "sandbox",
"correlationId": "kfcor_01971882-070e-7000-8000-000000000001",
"limit": 100
}
}Partner rules
Small rules that keep trace data useful and safe.
Mint `kfcor_<uuidv7>` once at the trusted ingress if the caller did not provide one.
Do not accept `x-correlation-id`; only the KarmanFlow header is canonical.
Do not put PII, emails, order numbers, shop domains, or customer names into IDs.
Preserve `traceparent` and `tracestate` when forwarding, while creating a new request ID for each hop.
Store partner IDs only in `x-karmanflow-external-correlation-id` or the matching JSON field.
Report queries must filter by tenant, environment, time window, and correlation or trace ID.
Build with it
Every connector should leave a trace report behind.
Use the SDK helpers for Node connectors. Non-Node partners can follow the same headers and ID rules.