Argus adotta W3C Trace Context su ogni richiesta. Invia un header `traceparent` per ancorare la trace al tuo backend di osservabilità, oppure lascia che Argus ne generi uno. Ogni risposta porta `X-Argus-Trace-ID` e `X-Argus-Span-ID` per correlare l’attività dell’operatore con i tuoi log e dashboard.
Argus accetta l’header standard W3C `traceparent` nel formato `00-<trace-id-32hex>-<span-id-16hex>-<flags-2hex>`. L’header opzionale `tracestate` viene propagato come stato opaco del fornitore. Se `traceparent` manca o è malformato, Argus genera un nuovo trace e span ID per la richiesta, mantenendo ogni operazione osservabile. Il contesto di ingresso si applica a tutte le rotte; nessun opt-in.
Ogni risposta di Argus, di successo o errore, porta `X-Argus-Trace-ID` (trace ID 32-hex) e `X-Argus-Span-ID` (span ID 16-hex della richiesta). Un `traceparent` completo è ri-emesso in forma W3C standard per i servizi a valle che lo consumano. Gli header di risposta sono emessi sempre; gli SDK client li trattano come opzionali e non lanciano mai un’eccezione in assenza.
Argus propaga il contesto di trace attivo a ogni chiamata di connettore partner tramite un’unica factory `traced_http`. Le richieste HTTP in uscita verso le integrazioni portano `traceparent` e `tracestate`, in modo che un singolo trace ID colleghi l’azione dell’operatore al tuo sistema a valle. Job, record di provenance e voci di audit originati da una richiesta marcano lo stesso `trace_id` per la correlazione end-to-end.
`GET /v1/observability/traces/{trace_id}` restituisce l’albero degli span registrato per un trace ID W3C 32-hex. L’endpoint richiede lo scope `argus:observability:read` su un bearer token. Una risposta 200 include trace ID, tenant ID, un array di span (con span ID, parent span ID, nome, ora di inizio in nanosecondi unix, durata in nanosecondi, codice di stato e attributi) e un marker `ingestion: stored`. Se il backend OpenTelemetry è temporaneamente irraggiungibile, l’endpoint risponde 503 con `ingestion: recorded` e `query_hint: use_your_backend`, così la tua tooling può ripiegare sul tuo storage OTEL. La trace è comunque registrata.
I lookup di trace sono filtrati sull’attributo di risorsa `tenant.id` e sull’attributo OpenTelemetry `service.namespace` impostato a `argus-{tenant_id}`. Un bearer token emesso per il tenant A non può leggere span del tenant B: un lookup cross-tenant restituisce 404. Gli attributi di span con marker sensibili sono filtrati rispetto alla clearance del chiamante. Ogni chiamata all’endpoint scrive una voce di audit con utente, organizzazione, tenant, trace ID letto e raggiungibilità del backend OTEL al momento della lettura.
Tutti e quattro gli SDK ufficiali (`@argus/connector-sdk`, `argus-connector-sdk`, `@argus/client`, `argus-client`) espongono `client.getLastResponseHeaders()` per leggere `X-Argus-Trace-ID` e `X-Argus-Span-ID` dopo ogni operazione. Usa `client.withTraceparent("00-<trace-id>-<span-id>-01")` su un request builder per ancorare una chiamata in una trace esistente del tuo backend. Gli header sono trattati come metadata opzionali; una chiamata SDK non lancia eccezioni se mancano.
# 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"
}