{"id":"observability-and-tracing","title":"Observability and tracing","description":"W3C Trace Context propagation, OpenTelemetry instrumentation, X-Argus-Trace-ID and X-Argus-Span-ID response headers, and a tenant-scoped trace lookup endpoint.","lastUpdated":"2026-05-08","sections":[{"id":"trace-lookup","title":"GET /v1/observability/traces/{trace_id} · Look up a recorded trace","content":"Route: GET /v1/observability/traces/{trace_id}\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nReturns a tenant-scoped span tree for a W3C trace ID.\n\nIntegration notes:\n- Requires the `argus:observability:read` scope on a bearer token.\n- Every Argus response carries `X-Argus-Trace-ID` and `X-Argus-Span-ID`.\n- Submit `traceparent` on requests to anchor the trace in your own observability backend.\n- Returns 503 with `query_hint: use_your_backend` if the OTEL backend is briefly unreachable; the trace was still recorded.","codeExamples":[{"language":"bash","code":"curl -H \"Authorization: Bearer $TOKEN\" https://api.knogin.com/v1/observability/traces/0af7651916cd43dd8448eb211c80319c","description":"Request example"},{"language":"json","code":"{\n  \"trace_id\": \"0af7651916cd43dd8448eb211c80319c\",\n  \"spans\": [...]\n}","description":"Response example"}]}],"relatedTopics":["identity-app-registration","oauth-service-tokens","jwks-token-verification","event-delivery-webhooks","graphql-transport-contract","async-jobs","sandbox-environment","provenance-and-compliance","discovery-and-governance"],"markdown":"# Observability and tracing\n\nW3C Trace Context propagation, OpenTelemetry instrumentation, X-Argus-Trace-ID and X-Argus-Span-ID response headers, and a tenant-scoped trace lookup endpoint.\n\n## GET /v1/observability/traces/{trace_id} · Look up a recorded trace\n\nRoute: GET /v1/observability/traces/{trace_id}\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nReturns a tenant-scoped span tree for a W3C trace ID.\n\nIntegration notes:\n- Requires the `argus:observability:read` scope on a bearer token.\n- Every Argus response carries `X-Argus-Trace-ID` and `X-Argus-Span-ID`.\n- Submit `traceparent` on requests to anchor the trace in your own observability backend.\n- Returns 503 with `query_hint: use_your_backend` if the OTEL backend is briefly unreachable; the trace was still recorded.\n\nRequest example\n\n```bash\ncurl -H \"Authorization: Bearer $TOKEN\" https://api.knogin.com/v1/observability/traces/0af7651916cd43dd8448eb211c80319c\n```\n\nResponse example\n\n```json\n{\n  \"trace_id\": \"0af7651916cd43dd8448eb211c80319c\",\n  \"spans\": [...]\n}\n```\n\n## Related Topics\n\n- [Identity and app registration](https://knogin.com/api/docs/identity-app-registration)\n- [OAuth and service tokens](https://knogin.com/api/docs/oauth-service-tokens)\n- [JWKS and token verification](https://knogin.com/api/docs/jwks-token-verification)\n- [Event delivery and webhooks](https://knogin.com/api/docs/event-delivery-webhooks)\n- [GraphQL transport contract](https://knogin.com/api/docs/graphql-transport-contract)\n- [Async jobs](https://knogin.com/api/docs/async-jobs)\n- [Sandbox environment](https://knogin.com/api/docs/sandbox-environment)\n- [Provenance and compliance](https://knogin.com/api/docs/provenance-and-compliance)\n- [Discovery and governance](https://knogin.com/api/docs/discovery-and-governance)","metadata":{"readingTime":"2 min","difficulty":"intermediate","tags":["integrations","api","oauth","webhooks","graphql"]}}