> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Encaminhamento de logs

> Encaminhe registros operacionais amostrados para o seu endpoint HTTPS.

Para a lista compartilhada de destinos e a escolha da origem, consulte [Destinos](/pt-br/console/drains).

Selecione um projeto e abra **Configurações do projeto → Destinos**. Proprietários e administradores da equipe veem e gerenciam aqui os destinos de logs e de análises. Os membros veem os metadados dos destinos com os endereços ocultos. **Adicionar destino → Logs** encaminha registros operacionais; **Adicionar destino → Análises** envia as [análises por hora dos números](/pt-br/console/analytics-collectors#enviar-retratos-json-por-hora).

Em **Logs**, o menu de exportação também abre os destinos de logs e a amostragem
de rastros. Um destino encaminha novos registros de requisições de API, de estado
de sessão e de entregas de webhook depois que você o ativa. Ele não preenche logs
anteriores nem inclui ações de auditoria das Configurações, corpo de mensagens,
dados de pareamento, cabeçalhos de requisição ou credenciais.

## Adicione um destino

1. Abra **Configurações do projeto → Destinos** e escolha **Adicionar destino → Logs**.
2. Use **Endpoint personalizado**, informe um nome e informe uma URL HTTPS pública de destino.
3. Escolha a codificação **JSON** ou **NDJSON**. Um segredo de assinatura é
   gerado para o novo destino; copie-o para o seu receptor. Você pode
   substituí-lo por um segredo de 16 a 256 caracteres, gerá-lo de novo ou
   apagá-lo para entregas sem assinatura.
4. Se quiser, ative **Cabeçalhos personalizados** e adicione nomes e valores.
5. Escolha **Adicionar destino** para salvar.

Um projeto aceita até cinco destinos, somando logs e análises. A lista mostra se cada destino está
ativado ou pausado, as contagens de entregas pendentes e com falha e o último
status HTTP ou erro registrado. Pause, retome ou exclua um destino nessa lista.
Excluir um destino remove as entregas dele que estão na fila. Os valores salvos
dos cabeçalhos personalizados e os segredos de assinatura não são retornados pela
visualização da configuração. Os membros da equipe veem os metadados dos destinos; as URLs de destino e os nomes dos cabeçalhos ficam visíveis apenas para proprietários e administradores. A origem, o escopo de números, a janela e a codificação ficam fixos quando um destino é criado; crie um novo destino para alterá-los.

**Integrações nativas** está marcada como **Em breve** e não está disponível.
Os destinos precisam resolver para endereços públicos. Redirecionamentos,
credenciais na URL, fragmentos e cabeçalhos reservados de transporte ou de
assinatura são rejeitados.

## Amostre os registros encaminhados

Abra **Amostragem de rastros** para adicionar até 20 regras. Cada regra define
uma porcentagem de 0 a 100 e, opcionalmente, corresponde a um tipo de log, a um
tipo de evento ou a um identificador compatível e um valor. As regras são
executadas na ordem exibida; a primeira regra correspondente é aplicada.
Registros sem uma regra correspondente são encaminhados a 100%.

A amostragem agrupa os registros pelo ID da requisição ou pelo ID do evento,
quando existe um. Registros repetidos com a mesma identidade recebem a mesma
decisão de amostragem determinística para uma mesma taxa. As atualizações de
entrega de um webhook compartilham a identidade do evento dele. Este controle
amostra os registros operacionais enviados aos destinos; ele não altera os logs
armazenados, o histórico de auditoria das Configurações nem a retenção de
mensagens.

## Receba as entregas

Com **JSON**, o seu endpoint recebe um **POST** HTTPS com `Content-Type: application/json`.
O envelope contém um ID de entrega estável e um registro operacional:

```json theme={null}
{
  "version": 1,
  "deliveryId": "018f0000-0000-7000-8000-000000000001",
  "records": [
    {
      "id": "api:018f0000-0000-7000-8000-000000000002",
      "projectId": "018f0000-0000-7000-8000-000000000003",
      "type": "api",
      "kind": "messages.send",
      "metadata": {
        "httpMethod": "POST",
        "route": "/api/messages",
        "httpStatus": 200,
        "requestId": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30",
        "traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
      }
    }
  ]
}
```

Com **NDJSON**, o tipo de conteúdo é `application/x-ndjson`. Cada linha contém
um envelope com `version`, `deliveryId` e um único objeto `record`. Uma entrega
contém uma linha e termina com uma quebra de linha; as quebras de linha dentro
de strings continuam escapadas. Logs e análises aceitam essa codificação.

```json theme={null}
{
  "version": 1,
  "deliveryId": "018f0000-0000-7000-8000-000000000001",
  "record": {
    "id": "api:018f0000-0000-7000-8000-000000000002",
    "type": "api",
    "kind": "messages.send"
  }
}
```

Os registros de API incluem `requestId` e `traceId`. `traceId` é o ID de trace W3C da requisição; quando a requisição enviou um
cabeçalho `traceparent` válido, ele é o ID de trace de quem fez a chamada. Use-o para relacionar os logs encaminhados aos seus próprios traces.

Use o cabeçalho `Idempotency-Key`, que corresponde ao `deliveryId`, para eliminar
duplicatas nas novas tentativas. Uma resposta 2xx conclui uma entrega. Outras
respostas e falhas de conexão são tentadas novamente depois de um minuto, cinco
minutos, 15 minutos, uma hora e seis horas, com no máximo seis tentativas e não
depois de 24 horas da entrada do registro na fila. A entrega acontece pelo menos
uma vez: confirme somente depois que o seu endpoint tiver aceitado o registro de
forma durável. Os diagnósticos de entrega retidos expiram depois de sete dias.

### Verifique as assinaturas

Toda requisição inclui `X-Polymorfa-Timestamp` em segundos Unix. Com um segredo
de assinatura configurado, `X-Polymorfa-Signature` contém `sha256=` seguido de um
digest hexadecimal HMAC-SHA256. No NDJSON, inclua a quebra de linha final. Calcule o HMAC com o seu segredo de assinatura sobre exatamente estes bytes:

```text theme={null}
X-Polymorfa-Timestamp + "." + original HTTP request body
```

Compare as assinaturas em tempo constante e rejeite horários antigos. Verifique
os bytes originais da requisição antes de interpretar ou serializar de novo o
JSON. As novas tentativas preservam o ID de entrega e criam um novo horário e uma
nova assinatura.

Pausar interrompe novas entregas e novas entradas na fila desse destino; uma
requisição em andamento pode terminar. Retomar permite que as entregas elegíveis
na fila continuem. Se o suporte desativar o encaminhamento do projeto, as
configurações de amostragem e de destinos continuam visíveis, enquanto as novas
entradas na fila e os claims de entrega são interrompidos. Os logs armazenados e o
histórico de auditoria continuam disponíveis.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.