A Argus adota W3C Trace Context em cada requisição. Envia um cabeçalho `traceparent` para ancorar a trace no teu backend de observabilidade, ou deixa que a Argus gere um. Cada resposta transporta `X-Argus-Trace-ID` e `X-Argus-Span-ID` para que possas correlacionar a atividade do operador com os teus próprios logs e dashboards.
A Argus aceita o cabeçalho padrão W3C `traceparent` no formato `00-<trace-id-32hex>-<span-id-16hex>-<flags-2hex>`. O cabeçalho opcional `tracestate` é propagado como estado opaco do fornecedor. Se `traceparent` faltar ou for inválido, a Argus gera um novo trace e span ID para a requisição, mantendo cada operação observável. O contexto de entrada aplica-se a todas as rotas; não há opt-in.
Cada resposta da Argus, sucesso ou erro, transporta `X-Argus-Trace-ID` (trace ID 32-hex) e `X-Argus-Span-ID` (span ID 16-hex da requisição). Um `traceparent` completo é também reemitido em forma W3C padrão para os serviços a jusante que o consomem. Os cabeçalhos de resposta são emitidos sem condição; os SDKs clientes tratam-nos como opcionais e nunca lançam exceção na ausência.
A Argus propaga o contexto de trace ativo para cada chamada de conector parceiro através de uma única fábrica `traced_http`. As requisições HTTP de saída para integrações transportam `traceparent` e `tracestate`, de modo que um único trace ID liga a ação do operador ao teu sistema a jusante. Jobs, registos de provenance e entradas de auditoria originados numa requisição carimbam o mesmo `trace_id` para correlação ponta a ponta.
`GET /v1/observability/traces/{trace_id}` devolve a árvore de spans gravada para um trace ID W3C de 32 hex. O endpoint exige o scope `argus:observability:read` num bearer token. Uma resposta 200 inclui o trace ID, o tenant ID, um array de spans (com span ID, parent span ID, nome, hora de início em nanosegundos unix, duração em nanosegundos, código de estado e atributos) e um marcador `ingestion: stored`. Se o backend OpenTelemetry estiver brevemente inacessível, o endpoint devolve 503 com `ingestion: recorded` e `query_hint: use_your_backend` para que a tua tooling recorra ao teu próprio armazenamento OTEL. A trace foi mesmo assim registada.
As procuras de trace são filtradas pelo atributo de recurso `tenant.id` e pelo atributo OpenTelemetry `service.namespace` definido como `argus-{tenant_id}`. Um bearer token emitido para o tenant A não consegue ler spans do tenant B: uma procura cruzada devolve 404. Os atributos de span com marcadores sensíveis são filtrados contra a clearance do solicitante. Cada chamada ao endpoint de procura escreve uma entrada de auditoria com utilizador, organização, tenant, trace ID lido e disponibilidade do backend OTEL no momento da leitura.
Os quatro SDK oficiais (`@argus/connector-sdk`, `argus-connector-sdk`, `@argus/client`, `argus-client`) expõem `client.getLastResponseHeaders()` para ler `X-Argus-Trace-ID` e `X-Argus-Span-ID` após qualquer operação. Usa `client.withTraceparent("00-<trace-id>-<span-id>-01")` num request builder para ancorar uma chamada numa trace existente do teu backend. Os cabeçalhos são tratados como metadados opcionais; uma chamada SDK não lança exceção se estiverem 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"
}