Argus adopte W3C Trace Context sur chaque requête. Envoyez un en-tête `traceparent` pour ancrer la trace dans votre backend d’observabilité, ou laissez Argus en générer un. Chaque réponse porte `X-Argus-Trace-ID` et `X-Argus-Span-ID` afin de corréler l’activité opérateur avec vos propres logs et tableaux de bord.
Argus accepte l’en-tête standard W3C `traceparent` au format `00-<trace-id-32hex>-<span-id-16hex>-<flags-2hex>`. L’en-tête optionnel `tracestate` est propagé tel quel comme état opaque du fournisseur. Si `traceparent` est absent ou mal formé, Argus génère un nouveau trace et span ID pour la requête, ce qui rend toute opération observable. Le contexte entrant s’applique à toutes les routes; aucun opt-in n’est requis.
Chaque réponse d’Argus, succès ou erreur, porte `X-Argus-Trace-ID` (trace ID 32-hex) et `X-Argus-Span-ID` (span ID 16-hex de la requête). Un `traceparent` complet est aussi ré-émis au format W3C pour les services en aval qui le consomment. Les en-têtes sont émis sans condition; les SDK clients les traitent comme optionnels et ne lèvent jamais d’erreur en cas d’absence.
Argus propage le contexte de trace actif à chaque appel de connecteur partenaire via une seule fabrique `traced_http`. Les requêtes HTTP sortantes vers les intégrations portent `traceparent` et `tracestate`, de sorte qu’un trace ID unique relie l’action opérateur à votre système en aval. Les jobs, enregistrements de provenance et entrées d’audit issus d’une requête tamponnent le même `trace_id` pour une corrélation de bout en bout.
`GET /v1/observability/traces/{trace_id}` renvoie l’arborescence de spans enregistrée pour un trace ID W3C 32-hex. L’endpoint requiert le scope `argus:observability:read` sur un bearer token. Une réponse 200 inclut le trace ID, le tenant ID, un tableau de spans (avec span ID, parent span ID, nom, heure de début en nanosecondes unix, durée en nanosecondes, code de statut et attributs), et un marqueur `ingestion: stored`. Si le backend OpenTelemetry est momentanément injoignable, l’endpoint renvoie 503 avec `ingestion: recorded` et `query_hint: use_your_backend` pour que votre outillage bascule vers votre propre stockage OTEL. La trace est tout de même enregistrée.
Les recherches de trace sont filtrées par l’attribut de ressource `tenant.id` et par l’attribut OpenTelemetry `service.namespace` réglé sur `argus-{tenant_id}`. Un bearer token émis pour le tenant A ne peut pas lire les spans du tenant B: une recherche croisée renvoie 404. Les attributs de span portant des marqueurs sensibles sont filtrés selon la clearance de l’appelant. Chaque appel à l’endpoint écrit une entrée d’audit comportant l’utilisateur, l’organisation, le tenant, le trace ID consulté et la disponibilité du backend OTEL à la lecture.
Les quatre SDK officiels (`@argus/connector-sdk`, `argus-connector-sdk`, `@argus/client`, `argus-client`) exposent `client.getLastResponseHeaders()` pour lire `X-Argus-Trace-ID` et `X-Argus-Span-ID` après toute opération. Utilisez `client.withTraceparent("00-<trace-id>-<span-id>-01")` sur un builder de requête pour ancrer un appel dans une trace existante de votre backend. Les en-têtes sont des métadonnées optionnelles; un appel SDK ne lève pas d’erreur s’ils sont absents.
# 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"
}