Argus przyjmuje W3C Trace Context w każdym żądaniu. Wyślij nagłówek `traceparent`, aby zakotwiczyć trace we własnym backendzie observability, albo pozwól, by Argus go wygenerował. Każda odpowiedź zawiera `X-Argus-Trace-ID` i `X-Argus-Span-ID`, dzięki czemu możesz korelować aktywność operatora z własnymi logami i dashboardami.
Argus akceptuje standardowy nagłówek W3C `traceparent` w formacie `00-<trace-id-32hex>-<span-id-16hex>-<flags-2hex>`. Opcjonalny nagłówek `tracestate` jest propagowany jako nieprzezroczysty stan vendora. Jeśli `traceparent` jest brakujący lub zniekształcony, Argus generuje nowe trace i span ID dla żądania, utrzymując obserwowalność każdej operacji. Przychodzący kontekst dotyczy wszystkich tras; nie ma opt-in.
Każda odpowiedź Argusa, sukces lub błąd, niesie `X-Argus-Trace-ID` (trace ID 32-hex) i `X-Argus-Span-ID` (span ID 16-hex dla tego żądania). Kompletne `traceparent` jest dodatkowo emitowane w standardowej formie W3C dla serwisów downstream. Nagłówki odpowiedzi emitowane są bezwarunkowo; klienci SDK traktują je jako opcjonalne i nigdy nie rzucają wyjątku przy braku.
Argus propaguje aktywny kontekst trace do każdego wywołania konektora partnerskiego poprzez jedną fabrykę `traced_http`. Wychodzące żądania HTTP do integracji niosą `traceparent` i `tracestate`, dzięki czemu pojedynczy trace ID łączy akcję operatora z twoim systemem downstream. Joby, rekordy provenance i wpisy audytu pochodzące z żądania stemplują to samo `trace_id` dla korelacji end-to-end.
`GET /v1/observability/traces/{trace_id}` zwraca zapisane drzewo spanów dla trace ID W3C 32-hex. Endpoint wymaga scope `argus:observability:read` na bearer tokenie. Odpowiedź 200 zawiera trace ID, tenant ID, tablicę spanów (każdy z span ID, parent span ID, nazwą, czasem startu w nanosekundach unix, czasem trwania w nanosekundach, kodem statusu i atrybutami) oraz marker `ingestion: stored`. Jeśli backend OpenTelemetry jest chwilowo niedostępny, endpoint zwraca 503 z `ingestion: recorded` i `query_hint: use_your_backend`, dzięki czemu twoje narzędzia mogą skorzystać z własnego magazynu OTEL. Trace mimo to został zapisany.
Wyszukiwania trace są filtrowane po atrybucie zasobu `tenant.id` i atrybucie OpenTelemetry `service.namespace` ustawionym na `argus-{tenant_id}`. Bearer token wystawiony dla tenanta A nie może odczytać danych spanów tenanta B: wyszukiwanie cross-tenant zwraca 404. Atrybuty spanów z markerami wrażliwymi są filtrowane wobec clearance wywołującego. Każde wywołanie endpointu zapisuje wpis audytu z użytkownikiem, organizacją, tenantem, odczytanym trace ID i dostępnością backendu OTEL w momencie odczytu.
Wszystkie cztery oficjalne SDK (`@argus/connector-sdk`, `argus-connector-sdk`, `@argus/client`, `argus-client`) udostępniają `client.getLastResponseHeaders()` do odczytu `X-Argus-Trace-ID` i `X-Argus-Span-ID` po każdej operacji. Użyj `client.withTraceparent("00-<trace-id>-<span-id>-01")` na request builderze, aby zakotwiczyć wywołanie w istniejącej trace twojego backendu. Nagłówki traktowane są jako opcjonalne metadane; wywołanie SDK nie rzuca wyjątku, jeśli ich brakuje.
# 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"
}