Observabilidade

A Veloz já coleta métricas de tráfego, recursos e banco de dados de todos os serviços. A observabilidade de aplicativo vai um passo além: ela leva para dentro da plataforma os dados que só o seu código conhece.

São três sinais, todos declarados no veloz.json:

Nenhum dos três exige configurar infraestrutura. Você declara a intenção no veloz.json, a Veloz cuida do endereço de envio, das credenciais e do isolamento entre organizações.

Ativando

Métricas e rastreamento são configurados por serviço. Painéis são configurados uma vez por projeto.

{
  "version": "1.0",
  "project": {
    "id": "proj_abc123",
    "name": "loja"
  },
  "observability": {
    "dashboards": "./dashboards"
  },
  "services": {
    "apps/api": {
      "id": "svc_api456",
      "name": "loja-api",
      "type": "web",
      "root": "apps/api",
      "runtime": {
        "command": "node dist/index.js",
        "port": 3000
      },
      "observability": {
        "metrics": { "port": 9090, "path": "/metrics" },
        "traces": { "sampleRate": 1 }
      }
    }
  }
}

Declarar o bloco já liga o sinal. Todos os campos são opcionais:

A forma mínima usa só os padrões:

{
  "observability": {
    "metrics": {},
    "traces": {}
  }
}

Com isso, a Veloz lê /metrics na porta declarada em runtime.port e mantém 100% dos rastreamentos.

Importante: metrics e traces são objetos, não booleanos. "traces": true é recusado na validação do veloz.json. Para ligar sem ajustar nada, use "traces": {}.

Depois de editar o arquivo, rode veloz deploy. A configuração vale a partir desse deploy.

Como saber se está funcionando

Esta é a primeira coisa a fazer depois do primeiro deploy com observabilidade.

No painel, a aba Métricas de cada serviço mostra um cartão de estado com os três sinais, a frescura da última coleta e, quando algo falha, o diagnóstico e a correção.

Pelo terminal:

veloz obs status --service loja-api

  Observabilidade

  ✓ Métricas       1.204 série(s) · última coleta há 14s
  ✓ Rastreamento   37 rastreamento(s) na última hora
  ✓ Painéis        3 de 20 publicado(s) · há 2min

  Dicas:
    veloz traces list                 Rastreamentos recentes
    veloz obs dashboards              Painéis publicados
    veloz obs validate                Validar arquivos de painel

Quando algo falha, a linha do sinal traz o motivo e a correção logo abaixo:

  Observabilidade

  ✗ Métricas       coleta falhando em 2 de 2 instância(s)
                   a porta configurada não aceitou a conexão.
                   Confirme que o serviço escuta na porta declarada em observability.metrics.port.
  ○ Rastreamento   não configurado
  ○ Painéis        não configurado

A primeira coleta acontece em até 30 segundos depois de o serviço ficar pronto. Antes disso o estado é "aguardando a primeira coleta", que é normal e se resolve sozinho.

Limites

Um painel fora do limite nunca derruba o deploy. O arquivo é pulado, os outros continuam.

A regra que evita chegar ao limite de séries é uma só: nunca use rótulos de alta variação, como identificador de usuário, URL completa ou identificador de requisição. Veja boas práticas de cardinalidade.

Problemas comuns

Quando a coleta de métricas falha, a Veloz classifica o motivo e mostra a correção no cartão de estado e em veloz obs status. Abaixo, cada diagnóstico e o que fazer.

Conexão recusada

Você vê: "Conexão recusada na porta 9090."

Nada está escutando na porta configurada. Causas em ordem de frequência:

1. O aplicativo serve as métricas na mesma porta HTTP do serviço, mas o veloz.json declara outra porta. Remova metrics.port para usar a porta do runtime.port.
2. O endpoint de métricas sobe depois do resto do aplicativo. Registre a rota junto com as demais.
3. O servidor de métricas escuta apenas em 127.0.0.1. Escute em todas as interfaces (0.0.0.0).

O caminho respondeu 404

Você vê: "O caminho /metrics respondeu 404."

O aplicativo respondeu, então a porta está certa, mas não existe rota nesse caminho. Confirme o caminho real do endpoint e ajuste observability.metrics.path, ou registre a rota no aplicativo. Lembre que o padrão é /metrics e que o caminho precisa começar com /.

Um caso comum: frameworks que servem tudo sob um prefixo (/api/metrics, /internal/metrics) sem que isso apareça no código da rota.

A coleta expirou

Você vê: "A coleta expirou."

O endpoint aceitou a conexão e não respondeu a tempo. Isso quase sempre significa que a geração das métricas faz trabalho pesado, por exemplo uma consulta ao banco a cada chamada. O endpoint precisa apenas ler contadores em memória. Mova qualquer coleta cara para uma tarefa em segundo plano que atualiza um gauge.

Resposta fora do formato Prometheus

Você vê: "Resposta fora do formato Prometheus."

O endpoint respondeu com um corpo que não é exposição Prometheus, geralmente JSON. A coleta espera o formato texto:

# HELP pedidos_criados_total Total de pedidos criados
# TYPE pedidos_criados_total counter
pedidos_criados_total 42

Use uma biblioteca oficial em vez de montar o corpo à mão: prom-client (Node), prometheus_client (Python), client_golang (Go). Veja os quickstarts.

Autenticação exigida

Você vê: "O endpoint exigiu autenticação."

O caminho de métricas respondeu 401 ou 403. A coleta acontece pela rede interna da Veloz, que não é alcançável de fora do seu projeto, então o endpoint não precisa de autenticação própria. Isente esse caminho do seu middleware de autenticação.

Resposta muito grande

Você vê: "Resposta de métricas muito grande."

A resposta ultrapassou o tamanho máximo aceito pela coleta. Isso é sempre cardinalidade: alguma métrica tem um rótulo com valores demais. Liste os candidatos com veloz metrics list e remova rótulos de alta variação. Veja boas práticas de cardinalidade.

Nenhuma instância disponível

Você vê: "Nenhuma instância disponível para coleta."

Nenhuma instância do serviço está pronta para receber tráfego, então não há de onde coletar. Isso não é um problema de observabilidade: verifique a verificação de saúde e o último deploy em veloz builds list e veloz logs show.

Nenhum rastreamento recebido

Você vê: "Nenhum rastreamento na última hora."

Em ordem de frequência:

1. sampleRate igual a 0. Com zero, nada é enviado. Suba para 0.1 ou mais.
2. A biblioteca do OpenTelemetry não é carregada antes do aplicativo. Em Node isso significa node --import ./instrumentation.mjs, nunca um import dentro do próprio código.
3. O protocolo foi trocado para gRPC. A Veloz recebe rastreamentos por OTLP sobre HTTP. Um exportador gRPC não conecta e falha em silêncio. Veja Rastreamento.
4. O serviço não recebeu tráfego. Sem requisição não há rastreamento. Chame uma rota e recarregue.

Um painel não aparece

O deploy nunca falha por causa de um painel. O arquivo com problema é pulado e o motivo vai para o log do deploy (veloz builds logs <id>). As causas: JSON inválido, arquivo sem title, arquivo acima de 256 KB, mais de 100 visualizações, ou pasta apontando para fora do repositório.

Valide antes de fazer deploy:

veloz obs validate

Veja Painéis para o formato aceito e as regras completas.

Próximos passos

• Métricas customizadas: exponha as métricas do seu aplicativo
• Rastreamento: instrumente com OpenTelemetry
• Painéis: painéis do Grafana versionados no repositório
• veloz.json: referência completa da configuração