Argus adopta W3C Trace Context en cada solicitud. Envía un encabezado `traceparent` para anclar la traza en tu backend de observabilidad, o deja que Argus genere uno. Cada respuesta lleva `X-Argus-Trace-ID` y `X-Argus-Span-ID` para que puedas correlacionar la actividad del operador con tus propios logs y dashboards.
Argus acepta el encabezado estándar W3C `traceparent` con el formato `00-<trace-id-32hex>-<span-id-16hex>-<flags-2hex>`. El encabezado opcional `tracestate` se propaga como estado opaco del proveedor. Si `traceparent` falta o es inválido, Argus genera un nuevo trace y span ID para la solicitud, manteniendo cada operación observable. El contexto entrante aplica a todas las rutas; no hay opt-in.
Cada respuesta de Argus, exitosa o de error, incluye `X-Argus-Trace-ID` (trace ID de 32 hex) y `X-Argus-Span-ID` (span ID de 16 hex para esa solicitud). También se re-emite un `traceparent` completo en formato W3C para los servicios descendentes que lo consumen. Los encabezados de respuesta se emiten siempre; los SDKs los tratan como opcionales y nunca lanzan excepción si faltan.
Argus propaga el contexto de traza activo a cada llamada de conector mediante un único factory `traced_http`. Las solicitudes HTTP salientes a integraciones llevan `traceparent` y `tracestate`, de modo que un único trace ID enlaza la acción del operador con tu sistema descendente. Los jobs, registros de provenance y entradas de auditoría que se originan en una solicitud sellan el mismo `trace_id` para la correlación de extremo a extremo.
`GET /v1/observability/traces/{trace_id}` devuelve el árbol de spans grabado para un trace ID W3C de 32 hex. El endpoint requiere el scope `argus:observability:read` sobre un bearer token. Una respuesta 200 incluye el trace ID, el tenant ID, un array de spans (con span ID, parent span ID, nombre, hora de inicio en nanosegundos unix, duración en nanosegundos, código de estado y atributos) y un marcador `ingestion: stored`. Si el backend OpenTelemetry está temporalmente fuera de alcance, el endpoint devuelve 503 con `ingestion: recorded` y `query_hint: use_your_backend` para que tus herramientas usen tu propio almacenamiento OTEL. La traza igualmente se registró.
Las búsquedas de traza se filtran por el atributo de recurso `tenant.id` y por el atributo OpenTelemetry `service.namespace` establecido en `argus-{tenant_id}`. Un bearer token emitido para el tenant A no puede leer datos de spans del tenant B: una búsqueda cruzada devuelve 404. Los atributos de span con marcadores sensibles se filtran contra la clearance del solicitante. Cada llamada al endpoint de búsqueda escribe una entrada de auditoría con el usuario, la organización, el tenant, el trace ID consultado y si el backend OTEL estaba alcanzable en el momento de la lectura.
Los cuatro SDK oficiales (`@argus/connector-sdk`, `argus-connector-sdk`, `@argus/client`, `argus-client`) exponen `client.getLastResponseHeaders()` para leer `X-Argus-Trace-ID` y `X-Argus-Span-ID` tras cualquier operación. Usa `client.withTraceparent("00-<trace-id>-<span-id>-01")` en un request builder para anclar la llamada en una traza existente de tu backend. Los encabezados se tratan como metadatos opcionales; el SDK no lanza excepción si están ausentes.
# 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"
}