Logs de acesso

Os logs de acesso são a linha a linha do que aconteceu no tráfego da API. São a visão certa para responder "o que aconteceu naquela requisição das 14h32?" — desde que ela esteja dentro da retenção.

Retenção de 3 dias

A retenção é de 3 dias (72 horas) e isso é dito explicitamente na resposta da consulta (retention_hours: 72). Não há como consultar além disso: para histórico, o caminho é o uso agregado, não os logs.

Consultar

GET /v1/apis/{apiId}/logs?since=…&limit=…

• devolve até 500 linhas (200 por padrão na configuração);
• since no futuro → 400 (reason = since_in_future); since antes da retenção é ajustado para o começo dela; sem since, a janela padrão é a última hora;
• as linhas são filtradas pela API: só aparecem as requisições daquela API;
• se a fonte não estiver configurada no ambiente, a resposta é 503.

Campos por linha

Campo	O que é
ts	momento da requisição
request_id	identificador da requisição no gateway
service_id	identificador do serviço da API no runtime
route_id	identificador da rota que casou
consumer	consumidor identificado, quando houve
status	status devolvido ao cliente
bytes_in, bytes_out	bytes recebidos e enviados
request_time	tempo total da requisição
upstream_time	tempo gasto no backend
server_port	porta que atendeu a requisição

Os identificadores de rota, serviço e consumidor são preenchidos também nas recusas do componente de autenticação — por isso uma linha de 401 ainda mostra qual rota e qual consumidor estavam em jogo.

O que os logs não contêm

• Authorization;
• cookies;
• chaves de API;
• corpo da requisição ou da resposta;
• query string.

Nenhum desses dados é gravado. Se você precisa depurar o conteúdo de uma chamada, reproduza o caso na ferramenta de teste ou no seu próprio ambiente.

Diagnosticando com logs

Pergunta	Como ler
"o erro foi meu ou do gateway?"	status e upstream_time: 502/504 com upstream_time alto é o backend; 401/403 é autenticação e autorização
"a requisição chegou ao gateway?"	se não há linha, o host ou o caminho não chegaram ao gateway (DNS, endereço errado) ou a fonte de logs não está configurada
"qual rota casou?"	route_id
"quem chamou?"	consumer, quando a API identifica consumidor

Correlação com o suporte

O gateway acrescenta X-Request-Id à resposta (se você não enviar um) e devolve o mesmo valor no cabeçalho. Ao abrir um atendimento, envie o X-Request-Id, o horário com fuso, o endereço da API, o método, o caminho e o status. Sem isso, a investigação começa do zero.

X-Correlation-Id é aceito se for um token seguro (até 128 caracteres) e é devolvido na resposta; ele também aparece nos registros da administração.

Próximos passos

• Uso e métricas: totais, séries e p95/p99.
• Erros e diagnóstico: o que cada status quer dizer.
• Como chamar uma API publicada: cabeçalhos que o gateway trata.