observability-correlation

Especialista em Observabilidade, Correlação de Telemetria (Métricas, Logs, Traces) e Dashboards de Dependência utilizando Grafana, Prometheus, Loki, OpenSearch, Elastic Stack (ELK) e VictoriaMetrics.

SKILL.md

GitHub

📈 Observabilidade, Correlação de Telemetria e Dashboards de Dependência

Esta skill orienta a inteligência artificial a atuar como Especialista em Observabilidade e Correlação de Dados de Telemetria, conectando métricas de séries temporais (Prometheus/VictoriaMetrics), logs estruturados (Loki/Elastic/OpenSearch) e traces distribuídos para construir dashboards unificados de saúde e dependências de sistemas.


🔗 1. A Tríade da Observabilidade e Correlação Multidimensional

A correlação efetiva entre sinais de observabilidade permite que o engenheiro navegue fluidamente de um alerta de métrica para os logs correspondentes e o trace exato da requisição com erro:

flowchart LR
    subgraph Sinais["Sinais Fundamentais"]
        METRICS["Métricas (Prometheus / VictoriaMetrics)"]
        LOGS["Logs (Grafana Loki / Elastic / OpenSearch)"]
        TRACES["Traces (Tempo / Jaeger / OTel)"]
    end

    subgraph Correlacao["Mecanismos de Correlação"]
        TRACE_ID["TraceID & SpanID"]
        LABELS["Labels Padronizados (app, env, version, pod)"]
        EXEMPLARS["Exemplars de Métricas"]
    end

    subgraph Interface["Camada de Visualização & Alerta"]
        GRAFANA["Grafana Dashboards & Node Graph Panel"]
        ALERTMANAGER["Alertmanager / PagerDuty"]
    end

    METRICS -->|"Exemplars vinculam TraceID"| TRACES
    LOGS -->|"Filtro por TraceID"| TRACES
    TRACES -->|"Logs associados ao Span"| LOGS
    
    METRICS & LOGS & TRACES --> GRAFANA
    GRAFANA --> ALERTMANAGER

🛠️ 2. Ferramentas Especialistas e Linguagens de Consulta

1. Grafana & Node Graph Panel

  • Conceito: Plataforma de visualização e dashboards analíticos. Oferece o painel Node Graph Panel, capaz de renderizar grafos de nós e arestas direcionadas representando a topologia de microsserviços, com métricas de taxa de requisições (Requests per second), taxa de erro (%) e latência média em cada nó.
  • Configuração de Datasources Correlacionados: Permite configurar Data links para que ao clicar em uma barra de erro em um gráfico Prometheus, o usuário seja redirecionado automaticamente para o Loki filtrando pelo mesmo intervalo temporal e service_name.

2. Prometheus & PromQL

  • Conceito: Banco de dados de séries temporais pull-based e padrão de fato na Cloud Native Computing Foundation (CNCF).
  • Consultas PromQL para Mapeamento de Dependências e Latência:
# Taxa de requisições HTTP entre serviços nos últimos 5 minutos
sum by (service, endpoint, status_code) (rate(http_requests_total[5m]))

# Latência p99 de comunicação inter-serviços
histogram_quantile(0.99, sum by (le, service) (rate(http_request_duration_seconds_bucket[5m])))

# Taxa de erros 5xx que afetam SLAs
sum(rate(http_requests_total{status_code=~"5.."}[5m])) 
  / 
sum(rate(http_requests_total[5m])) * 100

3. VictoriaMetrics (High-Performance Time Series Database)

  • Conceito: Banco de dados de séries temporais rápido, com alta eficiência de compressão de RAM/disco e compatibilidade total com PromQL e a API do Prometheus (MetricsQL). Ideal para retenção de métricas de longo prazo em ambientes corporativos.

4. Grafana Loki & LogQL

  • Conceito: Sistema de agregação de logs inspirado no Prometheus, indexando apenas metadados (labels) em vez de todo o texto, resultando em menor consumo de armazenamento e suporte nativo a correlação com métricas.
  • Exemplo de Consulta LogQL correlacionando TraceID:
{app="payment-service", env="production"} 
  |= "error" 
  | json 
  | trace_id != "" 
  | line_format "{{.timestamp}} [TraceID: {{.trace_id}}] - {{.message}}"

5. Elastic Stack (ELK: Elasticsearch, Logstash, Kibana) & OpenSearch

  • Conceito: Mecanismos de busca e análise distribuída orientados a documentos JSON em escala de petabytes.
  • Mapeamento ECS (Elastic Common Schema): Padronização de nomes de campos (service.name, client.ip, http.response.status_code, trace.id) para permitir correlações universais entre logs de infraestrutura, proxies, firewalls e aplicações.
  • OpenSearch Dashboards & Trace Analytics: Módulo integrado para geração de gráficos de serviço baseados em dados OpenTelemetry.

📊 3. Padrão de Labels para Correlação Universal

Para permitir o cruzamento transparente de dados entre métricas, logs e traces no Grafana, todas as aplicações e coletores devem emitir as seguintes tags/labels unificadas:

Label Descrição Exemplo
service.name ou app Nome canônico do serviço order-service
service.version Versão do commit ou tag de release v2.4.1
deployment.environment Ambiente de execução production, staging
k8s.namespace.name Namespace do Kubernetes ecommerce-backend
k8s.pod.name Nome da instância do pod order-service-7f8d9b-x2k9l
trace.id Identificador único de trace W3C 4bf92f3577b34da6a3ce929d0e0e4736

🎯 4. Boas Práticas de Observabilidade

  • Alinhe os 4 Sinais Dourados (Four Golden Signals do Google SRE): Garanta que todos os mapas de dependência exibam Latência, Tráfego, Erros e Saturação (CPU/RAM/Conexões).
  • Habilite Exemplars no Prometheus/Grafana: Permite que pontos isolados de alta latência nos gráficos de métricas contenham o traceID direto para depuração instantânea no Tempo/Jaeger.
  • Estruturação JSON em Logs: Abandone prints de texto puro em logs; utilize sempre formato JSON estruturado com chave trace_id injetada pelo contexto da thread.