Argus adopteert W3C Trace Context op elk verzoek. Stuur een `traceparent`-header om de trace te verankeren in je eigen observability backend, of laat Argus er een genereren. Elke respons draagt `X-Argus-Trace-ID` en `X-Argus-Span-ID` zodat je operatoractiviteit kunt correleren met je eigen logs en dashboards.
Argus accepteert de standaard W3C-header `traceparent` in het formaat `00-<trace-id-32hex>-<span-id-16hex>-<flags-2hex>`. De optionele header `tracestate` wordt als ondoorzichtige vendorstaat ongewijzigd doorgegeven. Ontbreekt `traceparent` of is hij ongeldig, dan genereert Argus een nieuwe trace- en span-ID voor het verzoek zodat elke operatie waarneembaar blijft. De inkomende trace-context geldt voor alle routes; er is geen opt-in.
Elke respons van Argus, succes of fout, draagt `X-Argus-Trace-ID` (32-hex trace-ID) en `X-Argus-Span-ID` (16-hex span-ID voor dat verzoek). Een volledige `traceparent` wordt ook opnieuw uitgegeven in standaard W3C-vorm voor downstream services die hem verbruiken. Responsheaders worden onvoorwaardelijk uitgegeven; client-SDK’s beschouwen ze als optioneel en gooien nooit een fout bij afwezigheid.
Argus geeft de actieve tracecontext door aan elke partnerconnector-aanroep via één enkele `traced_http`-factory. Uitgaande HTTP-verzoeken naar integraties dragen `traceparent` en `tracestate`, zodat één trace-ID de operatoractie aan je downstream-systeem koppelt. Jobs, provenance-records en audit-entries die ontstaan uit een verzoek stempelen dezelfde `trace_id` voor end-to-end-correlatie.
`GET /v1/observability/traces/{trace_id}` geeft de opgeslagen span-boom terug voor een 32-hex W3C trace-ID. Het endpoint vereist het scope `argus:observability:read` op een bearer token. Een 200-respons bevat trace-ID, tenant-ID, een array van spans (met span-ID, parent span-ID, naam, starttijd in unix-nanoseconden, duur in nanoseconden, statuscode en attributen) en een `ingestion: stored`-marker. Als de OpenTelemetry-backend kort niet bereikbaar is, geeft het endpoint 503 terug met `ingestion: recorded` en `query_hint: use_your_backend`, zodat je tooling kan terugvallen op je eigen OTEL-opslag. De trace is nog steeds opgenomen.
Trace-lookups worden gefilterd op het resource-attribuut `tenant.id` en het OpenTelemetry-attribuut `service.namespace` ingesteld op `argus-{tenant_id}`. Een bearer token uitgegeven voor tenant A kan geen span-data van tenant B lezen: een cross-tenant-lookup geeft 404. Span-attributen met gevoelige markers worden gefilterd op de clearance van de aanroeper. Elke aanroep van het lookup-endpoint schrijft een audit-entry met gebruiker, organisatie, tenant, gelezen trace-ID en bereikbaarheid van de OTEL-backend op leesmoment.
De vier officiële SDK’s (`@argus/connector-sdk`, `argus-connector-sdk`, `@argus/client`, `argus-client`) bieden `client.getLastResponseHeaders()` om `X-Argus-Trace-ID` en `X-Argus-Span-ID` te lezen na elke operatie. Gebruik `client.withTraceparent("00-<trace-id>-<span-id>-01")` op een request builder om een oproep te verankeren in een bestaande trace van je backend. De headers worden als optionele metadata behandeld; een SDK-aanroep gooit geen fout als ze ontbreken.
# Round-trip a request with an existing traceparent
curl -i \
-H "traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01" \
-H "Authorization: Bearer $TOKEN" \
https://api.knogin.com/v1/profiles/abc
# Response excerpt
# HTTP/1.1 200 OK
# X-Argus-Trace-ID: 0af7651916cd43dd8448eb211c80319c
# X-Argus-Span-ID: <fresh 16-hex>
# traceparent: 00-0af7651916cd43dd8448eb211c80319c-<server-span>-01
# Look up the recorded trace
curl -H "Authorization: Bearer $TOKEN" \
https://api.knogin.com/v1/observability/traces/0af7651916cd43dd8448eb211c80319c{
"trace_id": "0af7651916cd43dd8448eb211c80319c",
"tenant_id": "tnt_123",
"spans": [
{
"span_id": "b7ad6b7169203331",
"parent_span_id": null,
"name": "POST /v1/profiles/{id}/enrich",
"start_unix_nano": 1746715200000000000,
"duration_ns": 412000000,
"status_code": "OK",
"attributes": { "http.status_code": 200, "tenant.id": "tnt_123" }
}
],
"ingestion": "stored"
}