docs
Configuração

Métricas

Monitore performance, recursos e banco de dados com métricas em tempo real.

Monitore a performance dos seus serviços e bancos de dados diretamente pelo terminal.

Métricas instantâneas

veloz metrics show

Exibe um snapshot com métricas de tráfego, recursos e banco de dados:

  Métricas de Tráfego

  Requisições/min        42.5
  Erros/min              0
  Latência P95           0.12s

  Status HTTP:
    200  2.4K
    304  180

  Recursos

  Restarts               0
  Uptime                 3d
  OOM Events             0
  CPU Throttle            0.0%

Sparklines ao longo do tempo

veloz metrics range

Exibe séries temporais com sparklines Unicode para visualização rápida.

veloz metrics range                    # última hora (padrão)
veloz metrics range --range 6h         # últimas 6 horas
veloz metrics range --range 24h        # últimas 24 horas
veloz metrics range --range 7d         # últimos 7 dias
  Métricas (últimas 1h)

  Req/min              ▁▂▃▅▇█▇▅▃▂  42.5
  Latência P95         ▁▁▂▂▁▁▂▃▂▁  0.12s
  CPU (api-0)          ▂▃▃▄▅▄▃▃▂▂  85m
  Memória (api-0)      ▅▅▅▅▆▆▅▅▅▅  128Mi
  Rede ↓               ▁▂▃▂▂▃▂▂▁▁  4.2KB/s
  Rede ↑               ▁▁▂▂▁▂▂▁▁▁  1.8KB/s

Métricas de banco de dados

Serviços de banco de dados mostram métricas específicas quando insights está ativado:

veloz metrics show --service postgres
veloz metrics range --service postgres

Campos disponíveis:

Métrica Descrição
Conexões Ativas Conexões executando queries
Conexões Total Total de conexões abertas
Conexões Idle Conexões ociosas
Queries/s Consultas por segundo
Cache Hit Ratio Taxa de acerto do buffer cache (ideal: >90%)
Tamanho Tamanho total do banco em disco

Para ativar insights:

veloz db update postgres --insights

Após ativar, as métricas ficam disponíveis em ~2 minutos.

Consultas personalizadas

Use veloz metrics query para executar consultas MetricsQL diretamente:

# Consulta instantânea (valor atual)
veloz metrics query "up"
veloz metrics query 'sum(rate(traefik_service_requests_total[5m]))'
 
# Consulta com intervalo (range query com sparklines)
veloz metrics query "rate(traefik_service_requests_total[5m])" --start 1h
veloz metrics query "container_memory_working_set_bytes" --start 6h --step 5m

Intervalos relativos suportados: 1h, 6h, 24h, 7d. O step é calculado automaticamente.

Exemplos práticos

Tráfego:

# Requisições por minuto ao longo do tempo
veloz metrics query 'sum(rate(traefik_service_requests_total[5m])) * 60' --start 1h
 
# Latência P95 do serviço
veloz metrics query 'histogram_quantile(0.95, sum(rate(traefik_service_request_duration_seconds_bucket[5m])) by (le))' --start 1h
 
# Requisições por código HTTP
veloz metrics query 'sum(rate(traefik_service_requests_total[5m])) by (code) * 60'

Recursos:

# CPU por instância (millicores)
veloz metrics query 'sum by (pod) (rate(container_cpu_usage_seconds_total[5m])) * 1000' --start 1h
 
# Memória por instância (MiB)
veloz metrics query 'sum by (pod) (container_memory_working_set_bytes) / 1024 / 1024' --start 1h
 
# Eventos OOM nas últimas 24h
veloz metrics query 'sum(container_oom_events_total) by (pod)' --start 24h

Banco de dados:

# Conexões ativas ao longo do tempo
veloz metrics query 'pg_stat_activity_count{state="active"}' --start 1h
 
# Queries por segundo
veloz metrics query 'rate(pg_stat_database_xact_commit[5m]) + rate(pg_stat_database_xact_rollback[5m])' --start 6h
 
# Tamanho do banco ao longo da semana
veloz metrics query 'pg_database_size_bytes' --start 7d

Descoberta de métricas

Descubra métricas, labels e séries disponíveis na sua organização:

# Listar todas as métricas disponíveis
veloz metrics list
veloz metrics list --match '{job="node"}'
 
# Listar labels disponíveis
veloz metrics labels
veloz metrics labels --match "container_cpu_usage_seconds_total"
 
# Listar valores de um label específico
veloz metrics labels --label pod
veloz metrics labels --label state --match "pg_stat_activity_count"
 
# Encontrar séries por seletor
veloz metrics series "traefik_service_requests_total"
veloz metrics series '{__name__=~"pg_.*"}'

Métricas disponíveis

Tráfego (serviços web)

Métrica Tipo Descrição
traefik_service_requests_total counter Requisições HTTP totais
traefik_service_request_duration_seconds_bucket histogram Latência HTTP

Recursos (todos os serviços)

Métrica Tipo Descrição
container_cpu_usage_seconds_total counter CPU usado
container_memory_working_set_bytes gauge Memória em uso
container_network_receive_bytes_total counter Rede entrada
container_network_transmit_bytes_total counter Rede saída
container_cpu_cfs_throttled_periods_total counter Períodos com throttle
container_threads gauge Threads por container
container_file_descriptors gauge File descriptors abertos
container_oom_events_total counter Eventos OOM
kube_pod_container_status_restarts_total counter Restarts

Banco de dados (PostgreSQL — requer insights)

Métrica Tipo Descrição
pg_stat_activity_count gauge Conexões por estado
pg_stat_database_xact_commit counter Transactions commit
pg_stat_database_xact_rollback counter Transactions rollback
pg_stat_database_blks_hit counter Blocos do buffer cache
pg_stat_database_blks_read counter Blocos lidos do disco
pg_database_size_bytes gauge Tamanho do banco

Referência MetricsQL

Para a referência completa de sintaxe MetricsQL:

veloz metrics query-help

Inclui: seletores, funções de taxa, agregação, rollup, histogramas, operadores, extensões MetricsQL sobre PromQL, e exemplos práticos.

Filtrar por serviço

Em monorepos com múltiplos serviços, filtre métricas de um serviço específico:

veloz metrics show --service api
veloz metrics range --service postgres
veloz metrics query "container_cpu_usage_seconds_total" --start 1h

Use veloz use para definir o serviço padrão:

veloz use api
veloz metrics show     # agora mostra métricas do api

Próximos passos