Drains de telemetria

Um drain envia continuamente a telemetria das suas aplicações para uma ferramenta externa: um backend OTLP (Grafana Cloud, Honeycomb, New Relic, um OpenTelemetry Collector próprio), Datadog, Elastic, OpenSearch, um servidor syslog, um webhook HTTPS ou um bucket S3 ou Azure Blob para arquivamento. A plataforma coleta os dados como sempre (logs, métricas e traces continuam disponíveis nas telas de observabilidade) e o drain envia uma cópia ao destino escolhido.

Cada drain tem:

um escopo: a organização inteira ou um projeto;
uma fonte: telemetry (os sinais logs, metrics e traces das aplicações) ou audit (a trilha de auditoria da organização);
filtros opcionais por projeto, ambiente, aplicação e nível de log;
uma amostragem opcional (logs e traces);
um destino com as credenciais dele, guardadas no cofre da organização.

Como criar

No portal, abra Drains na organização (todos os projetos) ou no projeto e clique em Novo drain. O assistente mostra os campos de cada tipo de destino, guarda as credenciais em campos de senha e permite Testar conexão antes de ativar. O drain nasce como rascunho (DRAFT) e só começa a enviar dados depois de Ativar.

Para criar ou alterar drains da organização é preciso o papel Admin da organização. Nos drains de projeto basta o papel Admin do projeto. Qualquer membro com acesso pode ver os drains e o histórico de entrega.

Pela API (escopos de token drains:read e drains:write):

Operação	Método e caminho
Catálogo de destinos (tipos, campos e sinais aceitos)	`GET /api/v1/drain-destinations`
Listar e criar drains da organização	`GET`/`POST /api/v1/orgs/{orgId}/drains`
Listar e criar drains de um projeto	`GET`/`POST /api/v1/orgs/{orgId}/projects/{projectId}/drains`
Ler, alterar e excluir (com `If-Match`)	`GET`/`PUT`/`DELETE …/drains/{id}`
Gravar ou rotacionar as credenciais	`PUT …/drains/{id}/credentials`
Testar a conexão e ver os últimos testes	`POST …/drains/{id}/test` e `GET …/drains/{id}/tests`
Ativar, pausar e retomar	`POST …/drains/{id}/activate`, `/pause`, `/resume`
Entrega por hora (enviados, falhas, descartes, fila)	`GET …/drains/{id}/delivery?from=&to=`

As credenciais são gravadas e nunca lidas de volta: a API e o portal mostram só se elas existem e quando foram trocadas. A troca entra em vigor em até 2 minutos, sem perder o que está na fila.

O catálogo GET /api/v1/drain-destinations é a referência dos campos de cada tipo. Os exemplos abaixo mostram o corpo do POST de criação. O bloco credentials vai no mesmo pedido ou depois, em PUT …/credentials.

Destinos

O corpo de criação tem sempre a mesma forma:

Campo	Uso
`name`	nome do drain
`source`	`telemetry` (padrão: logs, métricas e traces das aplicações) ou `audit` (trilha de auditoria)
`type`	tipo do destino, um dos listados abaixo
`endpoint`	URL do destino (`https://…`, ou `tls://host:6514` no syslog); alguns tipos derivam o endpoint de outro campo
`settings`	campos do tipo que não são segredo (índice, bucket, região, container, site)
`credentials`	segredos: nos tipos OTLP, Loki e webhook são os cabeçalhos HTTP (nome → valor); nos demais, os campos do tipo
`signals`	`logs`, `metrics` e/ou `traces`, conforme o tipo e o plano
`filters`, `sampling`	opcionais (veja abaixo)

OTLP HTTP (`otlp_http`)

Para Grafana Cloud, Honeycomb, New Relic, Loki 3 (/otlp) ou qualquer receptor OTLP/HTTP.

{
  "name": "grafana-cloud",
  "type": "otlp_http",
  "endpoint": "https://otlp-gateway-prod-sa-east-1.grafana.net/otlp",
  "credentials": { "Authorization": "Basic <instância:token em base64>" },
  "signals": ["logs", "metrics"]
}

OTLP gRPC (`otlp_grpc`)

{
  "name": "collector-proprio",
  "type": "otlp_grpc",
  "endpoint": "https://otel.exemplo.com.br:4317",
  "credentials": { "x-api-key": "<chave>" },
  "signals": ["traces"]
}

Datadog (`datadog`)

O endpoint vem do site (datadoghq.com, datadoghq.eu, us3.datadoghq.com, us5.datadoghq.com, ap1.datadoghq.com ou ddog-gov.com).

{
  "name": "datadog",
  "type": "datadog",
  "settings": { "site": "datadoghq.com" },
  "credentials": { "apiKey": "<DD_API_KEY>" },
  "signals": ["logs", "metrics"]
}

Loki (`loki`)

Loki 3 recebe OTLP em /otlp. Só logs.

{
  "name": "loki",
  "type": "loki",
  "endpoint": "https://logs-prod-024.grafana.net/otlp",
  "credentials": { "Authorization": "Basic <usuário:token em base64>" },
  "signals": ["logs"]
}

Elasticsearch (`elasticsearch`)

Logs, métricas e traces. Autenticação por apiKey ou por username e password.

{
  "name": "elastic",
  "type": "elasticsearch",
  "endpoint": "https://meu-deploy.es.sa-east-1.aws.elastic-cloud.com:9243",
  "settings": { "index": "logs-atlas-default" },
  "credentials": { "apiKey": "<chave codificada>" },
  "signals": ["logs"]
}

OpenSearch (`opensearch`)

Logs e traces (o exportador de métricas do OpenSearch ainda não é estável).

{
  "name": "opensearch",
  "type": "opensearch",
  "endpoint": "https://search.exemplo.com.br:9200",
  "settings": { "index": "atlas-logs" },
  "credentials": { "username": "atlas", "password": "<senha>" },
  "signals": ["logs"]
}

Syslog sobre TLS (`syslog_tls`)

RFC 5424 sobre TLS, porta 6514. Só logs.

{
  "name": "siem",
  "type": "syslog_tls",
  "endpoint": "tls://syslog.exemplo.com.br:6514",
  "settings": { "appName": "atlas" },
  "signals": ["logs"]
}

Webhook HTTPS (`webhook`)

O corpo é OTLP/JSON. A autenticação é por cabeçalho secreto e TLS: não há assinatura HMAC por requisição. Quem precisa de assinatura usa as notificações de eventos (assinaturas de webhook da organização).

{
  "name": "meu-endpoint",
  "type": "webhook",
  "endpoint": "https://ingest.exemplo.com.br/atlas",
  "credentials": { "Authorization": "Bearer <token>" },
  "signals": ["logs"]
}

S3 e compatíveis (`s3`)

Arquivamento (exige o recurso drains.archive do plano). Sem endpoint, usa o S3 da AWS na região; informe o endpoint para provedores compatíveis (R2, Wasabi, MinIO).

{
  "name": "arquivo-s3",
  "type": "s3",
  "settings": { "bucket": "minha-empresa-logs", "region": "sa-east-1", "prefix": "atlas" },
  "credentials": { "accessKeyId": "<id>", "secretAccessKey": "<segredo>" },
  "signals": ["logs"]
}

Azure Blob (`azure_blob`)

Arquivamento (exige drains.archive).

{
  "name": "arquivo-azure",
  "type": "azure_blob",
  "endpoint": "https://minhaconta.blob.core.windows.net",
  "settings": { "container": "atlas-logs" },
  "credentials": { "connectionString": "<connection string com SharedAccessSignature>" },
  "signals": ["logs"]
}

Splunk HEC (`splunk_hec`)

{
  "name": "splunk",
  "type": "splunk_hec",
  "endpoint": "https://http-inputs-minhaempresa.splunkcloud.com",
  "settings": { "index": "atlas" },
  "credentials": { "token": "<HEC token>" },
  "signals": ["logs"]
}

Sentry (`sentry`)

Envia as exceções (spans com erro) para o projeto do Sentry. O DSN é o segredo do drain e define o endpoint; só traces.

{
  "name": "sentry",
  "type": "sentry",
  "credentials": { "dsn": "https://<chave>@o0.ingest.sentry.io/<projeto>" },
  "signals": ["traces"]
}

Trilha de auditoria (`source: audit`)

A fonte audit exporta os registros de auditoria da organização (quem fez o quê, quando e de onde) como logs OTLP, cada um com o hash da cadeia (atlas.audit.hash e atlas.audit.prev_hash). É o caminho para levar a auditoria a um SIEM. Só existe em drains de organização e só nos tipos otlp_http, elasticsearch, syslog_tls, webhook, s3, azure_blob e splunk_hec. Só Owner e Admin criam.

{
  "name": "auditoria-siem",
  "source": "audit",
  "type": "webhook",
  "endpoint": "https://siem.exemplo.com.br/atlas",
  "credentials": { "Authorization": "Bearer <token>" }
}

Filtros e amostragem

{
  "filters": {
    "projectIds": ["<projeto>"],
    "environmentIds": ["<produção>"],
    "applicationIds": [],
    "minLevel": "warn"
  },
  "sampling": { "logs": 25, "traces": 10 }
}

Filtros vazios incluem tudo e são combinados com E. Os ids precisam ser da sua organização. Um drain de projeto só vê o próprio projeto.
minLevel (trace, debug, info, warn, error, fatal) vale só para logs.
A amostragem (1 a 100%) vale para logs e traces. Métricas não são amostradas.

Cada registro chega com os atributos de recurso atlas.org, atlas.project, atlas.env e atlas.app e, nos logs, com o nível em severity_number. Os atributos internos de coleta são removidos.

Entrega

Pelo menos uma vez: se o destino falhar, a plataforma tenta de novo por até 30 minutos, com espera crescente de 5 s a 5 min, a partir de uma fila em disco por drain. Depois de uma nova tentativa o destino pode receber duplicatas. Cada registro de log leva atlas.record_id, um identificador estável que serve para deduplicar no destino.
Sem garantia de ordem entre lotes.
Descarte contado: com a fila cheia (o tamanho depende do plano) ou depois de esgotadas as tentativas, os registros são descartados e contados em dropped, com o motivo (queue_full ou retry_exhausted), na entrega do drain.
Isolamento: um destino lento ocupa só a fila do próprio drain. Os outros drains e as telas de observabilidade da plataforma não são afetados.
Dados já retidos antes da criação do drain não são reenviados.

IP de saída e portas

Os dados saem da plataforma pelo IP de saída do cluster da sua região, mostrado na tela de criação do drain e na página da organização. Libere esse IP no firewall do destino, se ele restringir origens.

O destino precisa ter endereço público e usar uma destas portas: 443, 4317, 4318, 6514, 9200 ou 9243. Endereços privados, de link-local ou internos da plataforma são recusados no cadastro e no teste. Se o nome do destino passar a resolver para um endereço proibido, o drain vai para FAILING com o motivo blocked.

Teste de conexão

Testar conexão (até 5 testes por minuto por drain) envia um dado de teste marcado com atlas.drain.test=true. Para OTLP e webhook é um log, para Datadog é a validação da chave, para Elastic e OpenSearch é um documento no índice, para syslog é uma mensagem RFC 5424 e para S3 e Azure é o arquivo atlas-drain-test/<timestamp>.json. Para Sentry é um evento de teste no envelope do projeto e para Splunk HEC é um evento. O resultado é succeeded (com a latência) ou failed com uma destas categorias:

Categoria	Significado
`blocked`	O endereço ou a porta não são permitidos (privado, interno ou porta fora da lista). Nenhuma conexão foi feita.
`dns`	O nome do destino não resolveu.
`tls`	Falha no handshake TLS ou certificado inválido.
`auth`	O destino recusou a credencial (401/403 ou equivalente).
`timeout`	O destino não respondeu a tempo.
`rejected`	O destino recusou o dado (por exemplo, 400 ou índice inexistente) ou a conexão foi recusada.
`error`	Outra falha; a mensagem traz o detalhe, sem a credencial.

Saúde do drain

Estado	Quando
`ACTIVE`	Enviando normalmente.
`FAILING`	Mais de 50% de falhas nos últimos 15 minutos, configuração inválida ou destino bloqueado. Volta a `ACTIVE` sozinho depois de 15 minutos com menos de 5% de falhas.
`DISABLED`	Ficou 24 horas em `FAILING`. Para de enviar até ser reativado (`POST …/activate`).
`PAUSED`	Pausado por alguém (`POST …/pause`), pelo teto mensal do plano (motivo `quota`) ou porque o plano deixou de incluir o sinal ou o arquivamento (motivo `plan_limit`). `POST …/resume` retoma quando o motivo deixa de existir.

Mudanças de estado geram os eventos drain.failing, drain.recovered, drain.disabled e drain.quota_reached, que você pode receber por e-mail, Slack, Teams ou webhook nas assinaturas de eventos da organização.

Limites por plano

Recurso	Starter	Pro	Business	Enterprise
Drains por organização (de organização e de projeto)	1	3	10	50
Logs	sim	sim	sim	sim
Métricas	não	sim	sim	sim
Traces	não	não	sim	sim
Arquivamento (`s3`, `azure_blob`)	não	sim	sim	sim
Fila por drain	64 MB	256 MB	1 GB	4 GB
Teto mensal (milhões de registros enviados)	10	100	1.000	sem teto

Acima do número de drains, a criação responde 422 com o código quota.exceeded. Um sinal ou destino fora do plano responde 403 com o código plan.feature_unavailable.
Ao atingir o teto mensal, os drains são pausados com o motivo quota até o próximo ciclo. Nenhuma requisição da sua aplicação é bloqueada.
O volume exportado é medido em milhões de registros (drain_million_records) e aparece na página Plano e uso e na fatura. A estimativa em GB no portal é só informativa. Veja Planos e limites.
Se o plano for rebaixado, os drains existentes continuam. Sinais e arquivamento que deixam de existir no plano são pausados sem apagar a configuração e voltam quando o recurso é religado.

Como criar​

Destinos​

OTLP HTTP (otlp_http)​

OTLP gRPC (otlp_grpc)​

Datadog (datadog)​

Loki (loki)​

Elasticsearch (elasticsearch)​

OpenSearch (opensearch)​

Syslog sobre TLS (syslog_tls)​

Webhook HTTPS (webhook)​

S3 e compatíveis (s3)​

Azure Blob (azure_blob)​

Splunk HEC (splunk_hec)​

Sentry (sentry)​

Trilha de auditoria (source: audit)​

Filtros e amostragem​

Entrega​

IP de saída e portas​

Teste de conexão​

Saúde do drain​

Limites por plano​