Argus übernimmt W3C Trace Context für jede Anfrage. Senden Sie einen `traceparent`-Header, um den Trace in Ihrem eigenen Observability-Backend zu verankern, oder lassen Sie Argus einen erzeugen. Jede Antwort trägt `X-Argus-Trace-ID` und `X-Argus-Span-ID`, sodass Sie Operator-Aktivität mit Ihren Logs und Dashboards korrelieren können.
Argus akzeptiert den Standard-W3C-Header `traceparent` im Format `00-<trace-id-32hex>-<span-id-16hex>-<flags-2hex>`. Der optionale Header `tracestate` wird als opaker Vendor-State weitergegeben. Fehlt `traceparent` oder ist es ungültig, erzeugt Argus eine neue Trace- und Span-ID für die Anfrage, sodass jede Operation beobachtbar bleibt. Der eingehende Trace-Kontext gilt für alle Routen; es gibt kein Opt-in.
Jede Antwort von Argus, Erfolg oder Fehler, trägt `X-Argus-Trace-ID` (32-hex Trace-ID) und `X-Argus-Span-ID` (16-hex Span-ID der Anfrage). Ein vollständiger `traceparent` wird zusätzlich im Standard-W3C-Format für nachgelagerte Dienste re-emittiert. Antwort-Header werden bedingungslos gesetzt; Client-SDKs behandeln sie als optional und werfen niemals einen Fehler bei Abwesenheit.
Argus gibt den aktiven Trace-Kontext über eine zentrale `traced_http`-Factory an jeden Partnerkonnektor-Aufruf weiter. Ausgehende HTTP-Aufrufe an Integrationen tragen `traceparent` und `tracestate`, sodass eine einzige Trace-ID Operator-Aktion und Downstream-System verbindet. Jobs, Provenance-Datensätze und Audit-Einträge, die aus einer Anfrage entstehen, stempeln dieselbe `trace_id` für die durchgängige Korrelation.
`GET /v1/observability/traces/{trace_id}` liefert den aufgezeichneten Span-Baum für eine 32-hex W3C-Trace-ID. Der Endpunkt erfordert den Scope `argus:observability:read` auf einem Bearer-Token. Eine 200-Antwort enthält Trace-ID, Tenant-ID, ein Array von Spans (mit Span-ID, Parent-Span-ID, Name, Startzeit in Unix-Nanosekunden, Dauer in Nanosekunden, Status-Code und Attributen) sowie den Marker `ingestion: stored`. Ist das OpenTelemetry-Backend kurzzeitig nicht erreichbar, antwortet der Endpunkt mit 503, `ingestion: recorded` und `query_hint: use_your_backend`, damit Ihre Werkzeuge auf den eigenen OTEL-Speicher umschalten. Der Trace wurde dennoch aufgezeichnet.
Trace-Lookups werden über das Ressourcen-Attribut `tenant.id` und das OpenTelemetry-Attribut `service.namespace` mit dem Wert `argus-{tenant_id}` gefiltert. Ein für Tenant A ausgestelltes Bearer-Token kann keine Span-Daten von Tenant B lesen: ein Cross-Tenant-Lookup liefert 404. Span-Attribute mit sensitiven Markern werden gegen die Clearance des Aufrufers gefiltert. Jeder Aufruf des Lookup-Endpunkts schreibt einen Audit-Eintrag mit Benutzer, Organisation, Tenant, gelesener Trace-ID und Erreichbarkeit des OTEL-Backends zum Lesezeitpunkt.
Alle vier offiziellen SDKs (`@argus/connector-sdk`, `argus-connector-sdk`, `@argus/client`, `argus-client`) bieten `client.getLastResponseHeaders()`, um `X-Argus-Trace-ID` und `X-Argus-Span-ID` nach jedem Aufruf zu lesen. Verwenden Sie `client.withTraceparent("00-<trace-id>-<span-id>-01")` an einem Request-Builder, um einen Aufruf in einen bestehenden Trace Ihres Backends einzubinden. Die Header gelten als optionale Metadaten; ein SDK-Aufruf wirft bei Abwesenheit keinen Fehler.
# 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"
}