Observabilidade

Um sistema que você não consegue observar é um sistema que você não consegue operar. O monitoramento diz que algo está errado; a observabilidade diz por quê. A distinção importa em microsserviços: uma requisição que passa por oito serviços e três bancos de dados não pode ser diagnosticada a partir de uma única métrica em um único dashboard. Observabilidade é a propriedade de um sistema que permite inferir seu estado interno a partir de suas saídas externas.

Imagine um cliente reclamando que "o checkout está lento" na loja. A requisição passou pelo Nginx, pelo gateway, pela verificação de autenticação, pelo serviço de pedidos, pelo serviço de produtos e pelo Postgres, e talvez tenha publicado um evento no Kafka. Qual deles foi lento? Foi lento para todo mundo ou só para esse cliente? Sem telemetria projetada de antemão — números, registros e caminhos de requisição emitidos por cada serviço —, a única resposta é chutar.

Slides

Clique nos slides e use ← → para navegar; F abre em tela cheia e P abre a visão do apresentador, com as notas. Abrir os slides em uma nova aba

Os três pilares

A observabilidade se apoia em três tipos de dados complementares. Cada um responde a uma pergunta diferente sobre o comportamento do sistema.

Os três descrevem os mesmos eventos sob ângulos diferentes. Um POST /orders que falha produz: um incremento de um contador http_server_requests_seconds_count{status="500"} (métrica), uma linha JSON {"level":"ERROR","msg":"product not found",...} (log) e um trace com um span por salto, o último marcado como ERROR (trace). Métricas são baratas e dizem que algo mudou; logs e traces são mais caros e dizem o quê e onde.

Métricas

Modelo de dados do Prometheus

Toda série temporal tem um nome de métrica e um conjunto de labels chave-valor:

http_requests_total{method="GET", status="200", service="order"} 4823

Um label é uma dimensão da série: cada combinação distinta de valores de labels é uma série temporal separada armazenada pelo Prometheus.

Noções básicas de PromQL

PromQL é a linguagem de consulta do Prometheus. As consultas abaixo usam a métrica que o Spring Boot (Micrometer) exporta para cada endpoint HTTP, http_server_requests_seconds, com os labels application, uri, method e status:

Duas regras: aplique rate() ou increase() a um counter antes de somar (essas funções tratam os zeramentos do contador quando um pod reinicia) e mantenha o label le ao somar os buckets de um histogram (sum by (le)), porque o histogram_quantile precisa dele. As séries _bucket só existem se os histogramas estiverem habilitados: management.metrics.distribution.percentiles-histogram.http.server.requests=true.

RED, USE e os Golden Signals

Pipeline de métricas

flowchart LR
    app["Spring Boot\n(Actuator + Micrometer)"]
    prom["Prometheus"]
    grafana["Grafana\n(dashboards + alertas)"]
    prom -->|"coleta /actuator/prometheus (ex.: a cada 15 s)"| app
    prom -->|"consultas PromQL"| grafana

O Prometheus usa um modelo pull: a aplicação apenas expõe seus valores atuais em um endpoint HTTP, e o Prometheus os busca (faz o scrape) periodicamente e os armazena como séries temporais. É isso que o Hands-on 6 configura para a loja.

Configuração do Spring Boot Actuator para expor o endpoint do Prometheus (também é necessária a dependência io.micrometer:micrometer-registry-prometheus):

management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus
  metrics:
    tags:
      application: ${spring.application.name}

Alertas

Dashboards precisam de alguém olhando para eles; alertas notificam uma pessoa quando é preciso agir. O Prometheus avalia regras de alerta e envia os alertas disparados ao Alertmanager (ou ao Grafana Alerting), que os encaminha para e-mail, Slack ou um pager.

groups:
  - name: order-service
    rules:
      - alert: OrderHighErrorRatio
        expr: |
          sum(rate(http_server_requests_seconds_count{application="order", status=~"5.."}[5m]))
          /
          sum(rate(http_server_requests_seconds_count{application="order"}[5m])) > 0.05
        for: 5m                     # must hold for 5 minutes, avoids flapping
        labels:
          severity: page
        annotations:
          summary: "More than 5% of order requests are failing"

Logs

Estruturados vs não estruturados

Níveis de log

Correlation IDs e MDC

Quando uma requisição passa por vários serviços, um ID compartilhado em todas as linhas de log — um correlation ID — permite reconstruir a sequência completa de chamadas buscando por esse único valor. Com rastreamento distribuído, o correlation ID natural é o trace ID.

Em Java, o lugar para colocá-lo é o MDC (Mapped Diagnostic Context) do SLF4J/Logback: um mapa de pares chave-valor por thread que o framework de logging pode imprimir em todas as linhas com %X{key}. Quem preenche o MDC depende de como o serviço é instrumentado:

%d{ISO8601} [%thread] %-5level %logger{36} [trace_id=%X{trace_id} span_id=%X{span_id}] - %msg%n

public Order create(OrderIn in) {
    try (var ignored = MDC.putCloseable("customerId", in.customerId())) {  // removed at the end
        log.info("creating order");   // ... [trace_id=4bf9...] customerId=c-42 ... creating order
        return repository.save(...);
    }
}

%d{ISO8601} %-5level [trace_id=%X{trace_id}] customerId=%X{customerId} %logger{36} - %msg%n

Pipeline de agregação de logs

flowchart LR
    svc1["Serviço A\n(logs JSON → stdout)"]
    svc2["Serviço B\n(logs JSON → stdout)"]
    svc3["Serviço C\n(logs JSON → stdout)"]
    collector["Filebeat / Fluentd\n(coletor)"]
    elastic["Elasticsearch\n(indexação + armazenamento)"]
    kibana["Kibana\n(busca + dashboards)"]
    svc1 --> collector
    svc2 --> collector
    svc3 --> collector
    collector --> elastic
    elastic --> kibana

Traces distribuídos

Anatomia de um trace

Um trace representa uma única requisição de ponta a ponta. Ele é composto de spans — um por operação (chamada de serviço, consulta ao banco, acesso ao cache etc.).

Cabeçalho W3C traceparent

O cabeçalho traceparent propaga o contexto de rastreamento entre fronteiras de serviço usando o formato version-traceId-parentSpanId-flags:

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

Em cada chamada downstream, um serviço mantém version, traceId e (normalmente) flags exatamente como recebidos, e substitui o campo parentSpanId pelo ID do seu próprio span corrente. É assim que o contexto de rastreamento atravessa as fronteiras de serviço sem que nenhum serviço precise entender o trace completo. O cabeçalho é definido pela recomendação W3C Trace Context⁵; o OpenTelemetry o usa por padrão.

Fluxo de uma requisição com spans

sequenceDiagram
    autonumber
    actor User as Usuário
    participant GW as Gateway [span: raiz, 120ms]
    participant OS as OrderService [span: filho, 95ms]
    participant DB as PostgreSQL [span: folha, 40ms]

    User->>+GW: GET /orders/42<br/>traceparent: 00-abc...-root-01
    GW->>+OS: GET /orders/42<br/>traceparent: 00-abc...-gw_span-01
    OS->>+DB: SELECT * FROM orders WHERE id=42
    DB-->>-OS: dados da linha
    OS-->>-GW: 200 OK (95ms)
    GW-->>-User: 200 OK (120ms)

Estratégias de amostragem

Registrar todos os spans de todas as requisições é caro em escala, então os sistemas de rastreamento guardam apenas uma amostra dos traces.

OpenTelemetry (OTel)

O OpenTelemetry é o padrão da CNCF para gerar, coletar e exportar telemetria³. Ele substitui SDKs específicos de fornecedores (cliente Zipkin, cliente Jaeger etc.) por uma única API neutra, de modo que trocar de backend exige apenas uma mudança de configuração, não de código.

flowchart LR
    app["Aplicação\n(OTel SDK)"]
    collector["OTel Collector"]
    prom["Prometheus\n(métricas)"]
    jaeger["Jaeger\n(traces)"]
    loki["Loki\n(logs)"]
    app -->|"OTLP (gRPC/HTTP)"| collector
    collector --> prom
    collector --> jaeger
    collector --> loki

Instrumentação Java sem código

O agente Java do OTel instrumenta o Spring Boot automaticamente por injeção de bytecode — sem nenhuma alteração de código.

# pin a version: "latest" makes builds unreproducible
ADD https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v2.4.0/opentelemetry-javaagent.jar /app/opentelemetry-javaagent.jar

ENTRYPOINT ["java", \
  "-javaagent:/app/opentelemetry-javaagent.jar", \
  "-jar", "/app/app.jar"]

Configure o agente por variáveis de ambiente no Docker Compose:

environment:
  OTEL_SERVICE_NAME: order-service
  OTEL_EXPORTER_OTLP_PROTOCOL: grpc            # agent 2.x defaults to http/protobuf (port 4318)
  OTEL_EXPORTER_OTLP_ENDPOINT: http://jaeger:4317
  OTEL_METRICS_EXPORTER: none
  OTEL_LOGS_EXPORTER: none

Spans manuais

Quando a instrumentação automática não tem granularidade suficiente — você quer ver quanto tempo levou o seu cálculo de preço, e não apenas as chamadas HTTP e SQL ao redor dele —, adicione spans personalizados. Adicione a dependência da API do OTel (sua versão é gerenciada pelo opentelemetry-bom, ou defina-a explicitamente):

<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-api</artifactId>
</dependency>

A forma mais simples, com o agente anexado, é uma anotação (dependência io.opentelemetry.instrumentation:opentelemetry-instrumentation-annotations):

@WithSpan("calculateTotal")
public BigDecimal calculateTotal(@SpanAttribute("order.items") int items, ...) { ... }

Para ter controle total, crie o span você mesmo. O agente registra a instância global de OpenTelemetry, então obtenha o tracer a partir dela (ele não é um bean do Spring, a menos que você declare um):

private static final Tracer tracer =
    GlobalOpenTelemetry.getTracer("store.order");

public Order processOrder(OrderRequest request) {
    Span span = tracer.spanBuilder("processOrder").startSpan();
    try (Scope scope = span.makeCurrent()) {
        span.setAttribute("order.customerId", request.customerId());
        // ... business logic
        return order;
    } catch (Exception e) {
        span.recordException(e);
        span.setStatus(StatusCode.ERROR, e.getMessage());
        throw e;
    } finally {
        span.end();
    }
}

Stack unificada do Grafana (LGTM)

Loki + Grafana + Tempo + Mimir/Prometheus — a stack LGTM — reúne os três sinais de observabilidade em uma única interface. A grande vantagem é a correlação de sinais: você pode saltar de um pico em uma métrica para os traces que o causaram e daí para as linhas de log que o explicam, tudo sem sair do Grafana.

flowchart LR
    app["Aplicação"]
    prom["Prometheus\n(métricas)"]
    loki["Loki\n(logs)"]
    tempo["Tempo\n(traces)"]
    grafana["Grafana"]
    app --> prom
    app --> loki
    app --> tempo
    prom --> grafana
    loki --> grafana
    tempo --> grafana

Um fluxo típico de investigação: um alerta de métrica dispara no Grafana → clique em "View Traces" para abrir o trace correlacionado no Tempo → clique em um span para ver as linhas de log correlacionadas no Loki. Essa navegação entre sinais é o que separa uma plataforma de observabilidade de três ferramentas de monitoramento isoladas.

Métricas DORA

O DORA (DevOps Research and Assessment) identificou quatro métricas que predizem o desempenho na entrega de software e o desempenho organizacional⁴. Duas medem vazão (com que rapidez as mudanças fluem) e duas medem estabilidade (com que frequência as mudanças quebram algo e com que rapidez você se recupera). Equipes de desempenho elite pontuam bem nas quatro ao mesmo tempo — velocidade e estabilidade não são um trade-off.

Retrato da observabilidade: simulação de um pico

O gráfico abaixo simula como os três pilares da observabilidade aparecem durante um pico de tráfego. O painel 1 mostra a taxa de requisições subindo bruscamente nos passos 10–12; o painel 2 mostra os eventos de erro concentrados na mesma janela; o painel 3 mostra as durações dos spans dos traces se alongando sob carga.

Os três painéis compartilham a mesma linha do tempo: o pico visível no painel 1 explica diretamente o agrupamento de erros no painel 2, e os dois explicam o alongamento das durações dos spans no painel 3. Sem os três pilares, você veria apenas uma parte do quadro.

Conexões

• Hands-on 6 — Prometheus e Grafana para as métricas da loja.
• Hands-on 10 — agente Java do OpenTelemetry, Jaeger e trace_id nos logs.
• Confiabilidade e SLI / SLO / SLA — SLIs são consultas PromQL sobre essas métricas; os alertas de burn rate as usam.
• Arquitetura Orientada a Eventos — rastreamento através de tópicos do Kafka e monitoramento do consumer lag.
• Exercício: Gargalos — usar a observabilidade para descobrir onde a plataforma está lenta.

Pontos-chave

• O monitoramento responde a perguntas conhecidas; a observabilidade permite investigar perguntas novas a partir de métricas (que algo mudou), logs (o quê) e traces (onde).
• O Prometheus coleta /actuator/prometheus; use rate() em counters, histogram_quantile com sum by (le) para percentis, e mantenha os labels com baixa cardinalidade.
• Monte dashboards com RED (serviços) e USE (recursos); alerte sobre sintomas que os usuários sentem.
• Os logs devem ser estruturados e carregar o trace_id — preenchido automaticamente pelo agente do OTel; use MDC.put só para suas próprias chaves de negócio.
• Um trace é uma árvore de spans ligados pelo traceparent; o head sampling é barato, mas cego, e o tail sampling mantém os traces interessantes.
• O OpenTelemetry é o padrão neutro em relação a fornecedores; meça o desempenho de entrega com as quatro métricas DORA.