Métricas Prometheus
curl -fsS \
-H 'Authorization: Bearer CHAVE_MONITORAMENTO' \
'https://dns01.exemplo.net/api/v1/monitoring/metrics'
Guia público de integração
Configure coleta autorizada em Prometheus, Grafana e Zabbix, consulte amostras JSON e mantenha cada credencial limitada à sua finalidade.
As requisições devem usar a URL HTTPS de gerência do próprio appliance, com certificado válido e acesso permitido somente pela rede de gerência autorizada.
Endpoints
Cada recurso tem uma chave própria, gerada no painel indicado. As credenciais não são intercambiáveis e o recurso precisa existir na versão instalada.
| Método e endpoint | Seção no painel | Chave necessária | Finalidade | Resposta |
|---|---|---|---|---|
GET/api/v1/monitoring/metrics |
Sistema > Monitoramento > Gerar chave | Monitoramento agregado | Coleta de métricas pelo Prometheus. | Texto Prometheus |
GET/api/v1/monitoring/snapshot |
Sistema > Monitoramento > Gerar chave | Monitoramento agregado | Amostra agregada para Zabbix e integrações JSON. | JSON |
GET/api/v1/monitoring/ip-details |
Sistema > Monitoramento > Consulta de IPs | Consulta de IPs | Candidatos recentes e medidas registradas como vigentes. | JSON restrito |
GET/api/v1/monitoring/dns-protect/events |
Sistema > Monitoramento > Eventos do DNS Protect | Eventos do DNS Protect | Eventos exportáveis da amostra mais recente. | JSON restrito |
GET/api/v1/dns-mitigation/status |
Protect > Mitigação DNS > API de Mitigação DNS | Mitigação DNS | Consulta do estado da API de mitigação. | JSON de estado |
Ela pode autorizar mudanças de configuração. Este guia documenta somente a consulta GET de estado. Para coleta, prefira a chave de monitoramento agregado e não habilite a chave de mitigação quando os indicadores agregados forem suficientes.
Acesso
A integração parte do appliance. O administrador do cliente gera a chave no painel e configura o coletor dentro da rede autorizada.
Se a seção não existir, o endpoint ainda não está disponível nessa instalação.
O certificado e o nome do host devem ser válidos. Não desative a validação TLS.
A chave aparece uma única vez. Guarde-a imediatamente em um cofre de segredos.
Use Authorization: Bearer SUA_CHAVE. Nunca coloque a chave na URL, em query string, dashboard ou chamado.
Gerar outra chave invalida a anterior. Atualize o cofre e o coletor antes da próxima coleta.
A revogação encerra o acesso da integração sem interromper o serviço DNS.
Validação inicial
Troque apenas o host e a chave fictícios. Os exemplos mantêm a validação do certificado e não enviam credenciais na URL.
curl -fsS \
-H 'Authorization: Bearer CHAVE_MONITORAMENTO' \
'https://dns01.exemplo.net/api/v1/monitoring/metrics'
curl -fsS \
-H 'Authorization: Bearer CHAVE_MONITORAMENTO' \
'https://dns01.exemplo.net/api/v1/monitoring/snapshot'
curl -fsS \
-H 'Authorization: Bearer CHAVE_CONSULTA_IPS' \
'https://dns01.exemplo.net/api/v1/monitoring/ip-details'
curl -fsS \
-H 'Authorization: Bearer CHAVE_EVENTOS' \
'https://dns01.exemplo.net/api/v1/monitoring/dns-protect/events'
curl -fsS \
-H 'Authorization: Bearer CHAVE_MITIGACAO' \
'https://dns01.exemplo.net/api/v1/dns-mitigation/status'
Prometheus e Grafana
Crie um job por appliance, com arquivo de credencial protegido. O Grafana consulta o Prometheus; ele não deve apontar diretamente para o appliance.
scrape_configs:
- job_name: core-dns-01
scheme: https
metrics_path: /api/v1/monitoring/metrics
scrape_interval: 60s
scrape_timeout: 12s
follow_redirects: false
authorization:
type: Bearer
credentials_file: /etc/prometheus/secrets/core-dns-01.token
static_configs:
- targets: ["dns01.exemplo.net:443"]
# Para CA privada, instale a confiança e use:
# tls_config:
# ca_file: /etc/prometheus/ca-gerencia.pem
credentials_file contém somente a chave, sem a palavra Bearer.promtool check config /etc/prometheus/prometheus.yml.| Indicador | PromQL |
|---|---|
| Coletor consegue ler | up{job="core-dns-01"} |
| CPU | core_dns_cpu_usage_percent |
| Memória | core_dns_memory_usage_percent |
| Tráfego recebido | 8 * rate(core_dns_network_rx_bytes_total[5m]) |
| Tráfego enviado | 8 * rate(core_dns_network_tx_bytes_total[5m]) |
| Erros e descartes | rate(core_dns_network_rx_errors_total[5m]) e rate(core_dns_network_rx_dropped_total[5m]); use também as séries tx. |
| DNS Protect | core_dns_protect_events, core_dns_protect_category_events, core_dns_protect_max_score |
| Botnet / suspeitos | core_dns_suspicious_clients, core_dns_suspicious_max_score |
| Mitigação | core_dns_mitigation_active, core_dns_mitigation_min_score, core_dns_mitigation_min_qps, rate(core_dns_mitigation_packets_total[5m]) |
| Resolução IPv6/UDP com DNSSEC | core_dns_resolution_success{family="ipv6",transport="udp",test="valid"} |
| Latência da resolução | 1000 * core_dns_resolution_duration_seconds{test="valid"} |
| Fonte ausente ou atrasada | core_dns_collection_available == 0 e core_dns_collection_stale == 1 |
Zabbix
O item mestre realiza uma única requisição por minuto. Os itens dependentes extraem os valores do mesmo JSON e não geram novas chamadas ao appliance.
{$COREDNS.URL}{$COREDNS.TOKEN}coredns.snapshot{$COREDNS.URL}/api/v1/monitoring/snapshotAuthorization: Bearer {$COREDNS.TOKEN}Teste o item mestre e confirme schema_version: 1 e observed_at. Depois crie os itens dependentes:
| Indicador | JSONPath | Tipo final |
|---|---|---|
| CPU | $.cpu.usage_percent | Decimal, % |
| Memória disponível | $.memory.available_bytes | Sem sinal, B |
| Uso de memória | $.memory.usage_percent | Decimal, % |
| Interface de exemplo | $.interfaces.items[?(@.name == 'eth0')].rx_bytes_total.first() | Sem sinal, B |
| DNS Protect, eventos | $.dns_protect.event_count | Sem sinal |
| DNS Protect, ANY | $.dns_protect.categories.any | Sem sinal |
| Botnet / suspeitos | $.suspicious.client_count | Sem sinal |
| Mitigações ativas | $.mitigation.active_count | Sem sinal |
| Score mínimo | $.mitigation.min_score | Sem sinal |
| Mitigação automática | $.mitigation.auto_enabled | Boolean to decimal |
| Resolução IPv4/UDP | $.resolution.checks[?(@.family == 'ipv4' && @.transport == 'udp' && @.test == 'valid')].success.first() | Boolean to decimal |
| Latência IPv4/UDP | $.resolution.checks[?(@.family == 'ipv4' && @.transport == 'udp' && @.test == 'valid')].latency_ms.first() | Decimal, ms |
| DNS Protect atrasado | $.dns_protect.stale | Boolean to decimal |
| Suspeitos disponível | $.suspicious.available | Boolean to decimal |
Para números opcionais, valide com ^[0-9]+(\.[0-9]+)?([eE][+-]?[0-9]+)?$ e use Custom on fail > Discard value. Crie alertas separados para nodata, fonte atrasada e falha de resolução.
Coletores JSON restritos
Use coletores e chaves separados. Esses dados permanecem restritos ao NOC autorizado e nunca devem virar rótulos de métricas ou painéis públicos.
/api/v1/monitoring/dns-protect/events
available: true com total: 0 significa amostra válida sem eventos exportáveis.available: false, total: null e items: [].{
"schema_version": 1,
"generated_at": "2026-01-15T12:00:00+00:00",
"age_seconds": 8,
"available": true,
"stale": false,
"total": 1,
"truncated": false,
"items": [{
"source_ip": "192.0.2.80",
"destination_ip": "198.51.100.53",
"categories": ["any", "random_subdomain"],
"severity": "critical",
"score": 95,
"qps": 142.5,
"queries": 285,
"unique_names": 220,
"unique_percent": 77.2,
"qtypes": {"ANY": 270, "TXT": 15},
"transports": {"UDP": 285}
}]
}
/api/v1/monitoring/ip-details
total: null indica fonte indisponível ou amostra antiga, não zero.{
"schema_version": 1,
"collected_at": "2026-01-15T12:00:08+00:00",
"candidates": {
"available": true,
"total": 1,
"truncated": false,
"items": [{
"ip": "2001:db8::42",
"score": 70,
"qps": 2.5,
"reasons": ["volume_consultas"]
}],
"generated_at": "2026-01-15T12:00:00+00:00",
"stale": false
},
"mitigations": {
"available": true,
"total": 1,
"truncated": false,
"items": [{
"ip": "192.0.2.42",
"mode": "limit",
"added_at": "2026-01-15T11:55:00+00:00",
"expires_at": "2026-01-15T12:15:00+00:00"
}]
}
}
Zabbix restrito
Reutilize intervalo de 1 minuto, timeout de 12 segundos, resposta esperada 200, validação de certificado e nome do host e a opção de não seguir redirecionamentos.
{$COREDNS.EVENTS_TOKEN}coredns.dns_protect.events{$COREDNS.URL}/api/v1/monitoring/dns-protect/eventsAuthorization: Bearer {$COREDNS.EVENTS_TOKEN}Itens dependentes sugeridos
$.total — total exportável; descarte se for nulo.$.available — use Boolean to decimal.$.stale — use Boolean to decimal.{$COREDNS.IP_TOKEN}coredns.ip_details{$COREDNS.URL}/api/v1/monitoring/ip-detailsAuthorization: Bearer {$COREDNS.IP_TOKEN}Itens dependentes sugeridos
$.candidates.total — total recente; descarte se for nulo.$.mitigations.total — medidas registradas como vigentes.Se precisar de histórico, armazene cada amostra uma única vez por appliance e horário de geração, com retenção e acesso definidos pela sua política interna.
Crie um item mestre HTTP agent para cada endpoint, usando a macro secreta da chave correspondente. Não reutilize a chave agregada.
Eventos do DNS Protect são liberados somente em versões compatíveis. O cliente ainda precisa gerar a chave e configurar o próprio coletor.
Respostas HTTP
Leia o código antes de repetir a chamada. Tentativas rápidas em sequência não corrigem chave, rede ou versão e podem dificultar o diagnóstico.
200Leitura aceita. Ainda verifique available, stale e valores nulos. No estado da mitigação, confirme também ok: true.
400Requisição inválida, inclusive parâmetros não aceitos. Não envie a chave em query string.
401Chave ausente, incorreta, rotacionada ou revogada.
403Use HTTPS e confirme se a origem está na rede de gerência autorizada.
404Endpoint não disponível na versão instalada ou caminho incorreto.
405Método não permitido. Os endpoints deste guia usam somente GET.
503A amostra ainda não está pronta. Aguarde o próximo ciclo de coleta.
Checklist de segurança
O monitoramento deve ampliar a visibilidade sem transformar credenciais ou dados restritos em nova superfície de exposição.
URL HTTPS de gerência com certificado e nome do host validados.
Acesso limitado à rede autorizada e aos coletores necessários.
Uma chave por finalidade, armazenada em cofre ou macro secreta.
Coleta a cada 60 segundos, timeout de 12 segundos e sem redirecionamentos.
Rotação e revogação registradas, sem colocar a chave em URL, log ou chamado.
IPs restritos fora de rótulos de métricas, dashboards públicos e compartilhamentos entre clientes.
Suporte técnico
Informe a versão instalada, o endpoint consultado e o código HTTP, sem enviar a credencial.