Observabilidade

Toda requisição do data plane vira uma linha auditável. O que ela guarda é decisão da organização.

A trilha

GET /v1/logs devolve as linhas do data plane do workspace da chave — nunca de outro, mesmo dentro da mesma organização (pedir outro recusa 403 workspace_nao_permitido). Da mais recente para a mais antiga. Linhas de falha de autenticação, que não têm organização conhecida, nunca aparecem.

bash

curl -sS "$AVALON_BASE_URL/v1/logs?limite=20" \
  -H "Authorization: Bearer $AVALON_API_KEY"

Cada linha carrega o id que saiu no cabeçalho x-avalon-request-id da resposta — inclusive em streaming, onde ele sai antes do primeiro quadro. É esse par que permite correlacionar o que o seu cliente viu com o que a plataforma gravou.

Metadata: o eixo que você define

O cabeçalho x-metadata aceita um JSON de pares texto→texto e anexa esses pares à linha da trilha. É o que permite agrupar consumo por cliente, por feature ou por time sem que a plataforma precise conhecer o seu domínio. O campo _user tem papel especial: é por ele que o braço do titular da LGPD acha (e apaga) o que uma pessoa gerou. Em embeddings e completions, o campo user do corpo alimenta metadata._user automaticamente.

Feedback por requisição

POST /v1/feedback anexa uma avaliação a uma linha da trilha: request_id (o mesmo id do cabeçalho), valor inteiro entre -10 e 10 (a escala da Portkey — um positivo/negativo de integração vira 1/-1), e peso opcional entre 0 e 1 (padrão 1) — o divisor da média ponderada. Um id inexistente e um id de outro workspace respondem 404 igual: um 403 aqui confirmaria que o id existe, o que já é vazamento.

Streaming e guardrails de saída

O que a trilha mostra de uma requisição em streaming depende de a config ter, ou não, um guardrail que pode recusar a saída. O console nunca calcula nem simula essa decisão — só mostra o que aconteceu.

As duas rotas do streaming
Config	O que acontece
Sem output-deny (ou async)	bytes fluem; guardrail async loga depois (246), nunca 446
Com output-deny (async OFF)	o usuário optou por latência: bufferiza, roda o check, então 446 ou repassa

Por padrão o gateway não segura os bytes: a resposta chega a você no mesmo ritmo em que o provedor a produz. Isso só muda quando você liga um guardrail que pode recusar a saída — aí a resposta é acumulada, o guardrail roda, e só então ela segue ou é recusada. Quem decide é sempre o servidor, a cada requisição.

Exportação

O console exporta a listagem filtrada em JSONL — uma linha JSON por registro, o formato que qualquer pipeline de análise consome sem parser especial. A exportação respeita exatamente os filtros da tela: o que você vê é o que sai.

Modo de registro e retenção

Duas alavancas independentes decidem o que fica gravado:

As duas alavancas de conformidade
Alavanca	Efeito
Modo de registro `GET/PUT /v1/privacy-mode`	`completo` grava conteúdo de requisição e resposta na trilha; `metadados` grava os dois como NULL — nunca mascarados — preservando tokens, custo, latência, metadata e código de erro. Um valor fora dos dois recusa `400 modo_invalido`: parecer que funcionou é a pior falha possível num controle de conformidade.
Retenção	Dois eixos separados: a retenção da LINHA vem do plano comercial (fixa, não editável por rota); a retenção do CONTEÚDO é da organização e se configura no console. "Nunca expira" é um valor decidido, não uma configuração faltando.

Ler o modo exige configs.read; trocá-lo exige configs.update — ler e mudar não são a mesma autoridade.
A troca é auditada com os valores anterior e novo na própria linha da trilha.
Em embeddings, o modo completo grava um RESUMO da resposta ({object, itens, dims, usage}), nunca o vetor — o cliente recebe a resposta íntegra.