Observabilidade em Comunicação Distribuída

Em um monólito, um bug tem um stack trace. Em um sistema distribuído, a mesma operação atravessa dez serviços, três filas de mensagem, dois bancos de dados e um cache. O stack trace de cada serviço individual conta apenas um capítulo da história. Observabilidade em sistemas distribuídos é a capacidade de responder "o que aconteceu com a requisição X?" olhando os dados coletados — sem precisar reproduzir o bug ou adicionar instrumentação depois do fato.

Os três pilares clássicos de observabilidade são logs, métricas e traces. Em comunicação distribuída, os três precisam estar correlacionados: um trace ID que conecta o log do Order Service ao log do Payment Service ao trace do Kafka consumer. Sem correlação, você tem três conjuntos de dados independentes que não contam a mesma história.

Distributed Tracing — conceitos fundamentais

Um trace representa a jornada completa de uma operação pelo sistema distribuído. Um trace é composto de spans — unidades de trabalho com início, fim, nome e atributos. Spans têm relações pai-filho que formam uma árvore (ou DAG, em casos de fan-out paralelo).

Trace ID: 4bf92f3577b34da6

Span: api-gateway (root)                    [0ms ─────────────────── 245ms]
  Span: auth-service                        [2ms ── 15ms]
  Span: order-service                       [18ms ───────────────── 243ms]
    Span: postgres query (SELECT)           [20ms ─ 28ms]
    Span: kafka produce (OrderPlaced)       [30ms ─ 35ms]
    Span: inventory-service (async)         [35ms ──────── 180ms]
      Span: postgres query (UPDATE)         [40ms ─ 55ms]
      Span: redis set (cache)               [57ms ─ 60ms]
    Span: payment-service (async)           [35ms ────────────── 240ms]
      Span: external payment API            [40ms ──────────── 235ms]

Cada span carrega: trace_id (identifica o trace completo), span_id (identifica o span), parent_span_id (relaciona ao span pai), timestamps de início e fim, nome da operação, status (OK/ERROR), e atributos (chave-valor: http.method, db.statement, messaging.destination).

W3C TraceContext — o padrão de propagação

Para que um trace atravesse serviços, o contexto precisa ser propagado junto com cada chamada. O W3C TraceContext (RFC publicado em 2021) padroniza os headers HTTP de propagação:

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
             ^^  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^ ^^
             version   trace-id (128 bits hex)    parent-span-id   flags
                                                  (64 bits hex)    (sampled=1)

tracestate: vendor1=value1,vendor2=value2
            (extensões proprietárias opcionais)

Todo instrumentado correto deve: ao receber uma requisição, extrair o contexto do header traceparent; ao fazer uma requisição downstream, injetar o contexto como header. O OpenTelemetry SDK faz isso automaticamente para HTTP, gRPC, e muitos clientes de banco de dados.

Propagação em mensageria assíncrona

Mensageria quebra o modelo de propagação de contexto por headers HTTP — a mensagem viaja assincronamente, possivelmente horas depois da publicação. A solução: injetar o contexto de trace como metadado/header da mensagem, e o consumidor extrai e cria um novo span filho (ou, mais corretamente, um span com link para o span original).

// Produtor: injeta o trace context como header da mensagem Kafka
var propagator = new TraceContextPropagator();
var headers = new Dictionary<string, string>();
propagator.Inject(
    new PropagationContext(Activity.Current?.Context ?? default, Baggage.Current),
    headers,
    (carrier, key, value) => carrier[key] = value
);

// Headers viajam com a mensagem:
// "traceparent": "00-4bf92f3577b34da6...-01"

// Consumidor: extrai e cria span filho
var parentContext = propagator.Extract(
    default,
    messageHeaders,
    (carrier, key) => carrier.TryGetValue(key, out var v) ? [v] : []
);

using var activity = ActivitySource.StartActivity(
    "process OrderPlaced",
    ActivityKind.Consumer,
    parentContext.ActivityContext  // span filho do produtor
);

OpenTelemetry — a camada de abstração universal

OpenTelemetry (OTel) é o padrão aberto para instrumentação de observabilidade — uma API, SDK, e protocolo de exportação (OTLP) que funciona independentemente do backend (Jaeger, Zipkin, Tempo, Datadog, Honeycomb). Instrumentar uma vez com OTel permite mudar de backend sem mudar o código.

A arquitetura OTel tem três camadas: API (interfaces estáveis que o código da aplicação usa — nada muda se você mudar de SDK), SDK (implementação: sampling, batching, exportação), e Collector (processo separado que recebe dados via OTLP, processa e exporta para backends).

┌──────────────────────────────────────────────────────┐
│  Aplicação                                           │
│  ┌─────────────────┐  ┌────────────────────────────┐ │
│  │  Código próprio │  │  Instrumentação automática │ │
│  │  (manual spans) │  │  (HTTP, DB, gRPC, etc.)    │ │
│  └────────┬────────┘  └────────────┬───────────────┘ │
│           └──────────────┬─────────┘                 │
│                    OTel SDK                           │
│                    (sampling, batching)               │
└──────────────────────┬───────────────────────────────┘
                       │ OTLP (gRPC ou HTTP)
                  OTel Collector
                  (recebe, processa, exporta)
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
        Jaeger      Prometheus    Datadog
       (traces)     (metrics)    (all-in-one)

Auto-instrumentação: o OTel SDK intercepta chamadas HTTP, consultas de banco, operações de fila e adiciona spans automaticamente sem mudança no código de aplicação. Em .NET, registra-se com AddAspNetCoreInstrumentation(), AddEntityFrameworkCoreInstrumentation(), etc. Em Python, opentelemetry-instrument python app.py injeta instrumentação via monkey-patching. Em Go, bibliotecas precisam de instrumentação explícita ou wrappers.

Métricas de comunicação — RED method

Para APIs e serviços, o método RED define as três métricas essenciais por serviço:

Rate: requisições por segundo. É o sinal de volume — quantas coisas estão acontecendo.

Errors: taxa de erros (% de requisições que falharam). É o sinal de qualidade — quantas coisas estão falhando.

Duration: distribuição de latência (P50, P95, P99). É o sinal de velocidade — quão rápido as coisas estão acontecendo para os usuários na cauda da distribuição.

# Prometheus — métricas RED para um serviço HTTP
# Rate: requisições por segundo
rate(http_requests_total[5m])

# Errors: taxa de erro nos últimos 5 minutos
rate(http_requests_total{status=~"5.."}[5m])
  /
rate(http_requests_total[5m])

# Duration: P99 de latência
histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m]))

# Exemplo de instrumentação manual (Go + Prometheus)
var (
    requestsTotal = prometheus.NewCounterVec(
        prometheus.CounterOpts{Name: "http_requests_total"},
        []string{"method", "path", "status"},
    )
    requestDuration = prometheus.NewHistogramVec(
        prometheus.HistogramOpts{
            Name:    "http_request_duration_seconds",
            Buckets: []float64{0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5},
        },
        []string{"method", "path"},
    )
)

Para mensageria, as métricas equivalentes: Rate = mensagens processadas/segundo, Errors = taxa de mensagens para DLQ, Duration = lag do consumer (diferença entre quando a mensagem foi produzida e quando foi processada — o P99 do lag é crítico em sistemas event-driven).

Correlação de logs com traces

Logs sem contexto de trace são uma coleção de strings. Logs com trace_id e span_id permitem navegar de um log para o trace completo — ou de uma linha de trace para todos os logs gerados por aquele span. A correlação requer injetar o contexto atual nos campos estruturados do log.

// C# — injeção automática de trace context nos logs via ILogger + OTel
// Adicionar o OTel Log Bridge no Program.cs:
builder.Logging.AddOpenTelemetry(o => {
    o.IncludeScopes = true;
    o.ParseStateValues = true;
    // OTel automaticamente adiciona trace_id e span_id aos registros
});

// Log com contexto automático:
// {"timestamp":"...","level":"INFO","message":"Pedido criado",
//  "trace_id":"4bf92f3577b34da6...","span_id":"00f067aa0ba902b7",
//  "order_id":"ord-123"}

// Python — injeção manual com structlog
import structlog
from opentelemetry import trace

def add_trace_context(logger, method, event_dict):
    span = trace.get_current_span()
    if span.is_recording():
        ctx = span.get_span_context()
        event_dict["trace_id"] = format(ctx.trace_id, "032x")
        event_dict["span_id"] = format(ctx.span_id, "016x")
    return event_dict

structlog.configure(
    processors=[
        add_trace_context,
        structlog.processors.JSONRenderer(),
    ]
)

Debugging de sistemas assíncronos

Sistemas assíncronos introduzem desafios únicos de debugging: a causa e o efeito são separados no tempo, a ordem de eventos varia entre execuções, e um único evento pode disparar múltiplos consumidores em paralelo.

Estratégias específicas para sistemas baseados em eventos:

Correlation ID persistido na mensagem: além do trace context, inclua um correlation_id estável que identifica a operação de negócio original (ex: o ID do pedido que disparou toda a cadeia). Diferente do trace_id que muda a cada trace, o correlation_id permite conectar logs de dias diferentes que fazem parte do mesmo fluxo de negócio.

Event timeline reconstruction: para debugar um fluxo assíncrono, colete todos os eventos com o mesmo correlation_id e ordene por timestamp. Isso reconstrói a sequência real de acontecimentos, mesmo que tenham acontecido em serviços diferentes com clocks ligeiramente diferentes.

Dead letter queue como diagnóstico: toda mensagem na DLQ tem uma história. Os headers de retry e erro são dados de observabilidade — colete-os em um sistema de análise (Elasticsearch, Loki) para identificar padrões: qual tipo de mensagem falha mais? Em qual serviço? Com qual erro?

Kafka consumer lag monitoring: o lag do consumer (diferença entre o offset mais recente e o offset commitado pelo consumer) é a métrica mais importante de saúde de um sistema baseado em Kafka. Lag crescente indica que o consumer não está acompanhando a produção — pode ser lentidão de processamento, instâncias mortas, ou rebalancing excessivo.

# Kafka consumer lag via CLI
kafka-consumer-groups.sh --bootstrap-server kafka:9092 \
  --describe --group order-processing-group

# Output:
# GROUP                  TOPIC      PARTITION  CURRENT-OFFSET  LOG-END-OFFSET  LAG
# order-processing-group orders     0          1000            1000            0
# order-processing-group orders     1          850             1200            350  ← lag!
# order-processing-group orders     2          1100            1100            0

# Prometheus com kafka-exporter:
# kafka_consumergroup_lag{consumergroup="order-processing-group",topic="orders"}

SLOs em comunicação distribuída

Service Level Objectives (SLOs) em sistemas de comunicação precisam capturar tanto o componente síncrono quanto o assíncrono:

# SLO para API síncrona
# Disponibilidade: 99.9% das requisições retornam 2xx em 30 dias
# Latência: 95% das requisições respondem em <200ms

# SLO para pipeline assíncrona
# Disponibilidade: 99.9% das mensagens são processadas com sucesso
# Freshness: 99% das mensagens são processadas em <30 segundos após publicação
# (P99 de lag < 30s)

# Error budget: 0.1% de 30 dias = 43 minutos de downtime aceitável
# Ou: 0.1% de 1M mensagens/dia = 1000 mensagens com falha aceitável por dia

Comparativo entre linguagens — instrumentação OTel

// C# — OpenTelemetry completo: traces + métricas + logs

// Program.cs
var serviceName = "order-service";
var serviceVersion = "1.0.0";

builder.Services.AddOpenTelemetry()
    .ConfigureResource(r => r
        .AddService(serviceName, serviceVersion: serviceVersion)
        .AddAttributes([
            new("deployment.environment", "production"),
            new("host.name", Environment.MachineName),
        ])
    )
    .WithTracing(t => t
        .AddAspNetCoreInstrumentation(o => {
            o.RecordException = true;
            o.Filter = ctx => !ctx.Request.Path.StartsWithSegments("/health");
        })
        .AddEntityFrameworkCoreInstrumentation(o => o.SetDbStatementForText = true)
        .AddHttpClientInstrumentation()
        .AddSource("order-service")        // ActivitySource próprio
        .AddOtlpExporter(o => o.Endpoint = new Uri("http://otel-collector:4317"))
    )
    .WithMetrics(m => m
        .AddAspNetCoreInstrumentation()
        .AddRuntimeInstrumentation()       // GC, ThreadPool, etc.
        .AddMeter("order-service")
        .AddOtlpExporter()
    );

builder.Logging.AddOpenTelemetry(o => {
    o.IncludeScopes = true;
    o.AddOtlpExporter();
});

// Uso: spans manuais para lógica de negócio
public class OrderService(ILogger<OrderService> log) {
    private static readonly ActivitySource _source = new("order-service");
    private static readonly Meter _meter = new("order-service");
    private static readonly Counter<long> _ordersCreated =
        _meter.CreateCounter<long>("orders.created.total");

    public async Task<Order> PlaceOrderAsync(PlaceOrderCommand cmd) {
        using var activity = _source.StartActivity("PlaceOrder");
        activity?.SetTag("order.customer_id", cmd.CustomerId);
        activity?.SetTag("order.item_count", cmd.Items.Count);

        try {
            var order = await CreateOrderAsync(cmd);
            _ordersCreated.Add(1, new TagList {
                { "payment.method", cmd.PaymentMethod },
            });
            activity?.SetTag("order.id", order.Id);
            return order;
        } catch (Exception ex) {
            activity?.SetStatus(ActivityStatusCode.Error, ex.Message);
            activity?.RecordException(ex);
            log.LogError(ex, "Falha ao criar pedido para cliente {CustomerId}", cmd.CustomerId);
            throw;
        }
    }
}

# Python — OpenTelemetry com FastAPI, auto-instrumentação e spans manuais

from opentelemetry import trace, metrics
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
from opentelemetry.sdk.resources import SERVICE_NAME, Resource

# Setup do provider
resource = Resource(attributes={
    SERVICE_NAME: "order-service",
    "service.version": "1.0.0",
    "deployment.environment": "production",
})

tracer_provider = TracerProvider(resource=resource)
tracer_provider.add_span_processor(
    BatchSpanProcessor(OTLPSpanExporter(endpoint="http://otel-collector:4317"))
)
trace.set_tracer_provider(tracer_provider)

meter_provider = MeterProvider(resource=resource)
metrics.set_meter_provider(meter_provider)

# Instrumentação automática
FastAPIInstrumentor.instrument_app(app)
SQLAlchemyInstrumentor().instrument(engine=engine)
HTTPXClientInstrumentor().instrument()

# Uso manual
tracer = trace.get_tracer("order-service")
meter = metrics.get_meter("order-service")
orders_counter = meter.create_counter("orders.created.total")

async def place_order(cmd: PlaceOrderCommand) -> Order:
    with tracer.start_as_current_span("PlaceOrder") as span:
        span.set_attribute("order.customer_id", cmd.customer_id)
        span.set_attribute("order.item_count", len(cmd.items))

        try:
            order = await create_order_in_db(cmd)
            orders_counter.add(1, {"payment.method": cmd.payment_method})
            span.set_attribute("order.id", order.id)
            return order
        except Exception as e:
            span.set_status(trace.StatusCode.ERROR, str(e))
            span.record_exception(e)
            raise


# Propagação em Kafka consumer
from opentelemetry.propagate import extract

async def consume_message(msg: aio_pika.IncomingMessage) -> None:
    # Extrai trace context dos headers da mensagem
    headers = {k: v.decode() if isinstance(v, bytes) else v
               for k, v in (msg.headers or {}).items()}
    ctx = extract(headers)

    with tracer.start_as_current_span(
        "process OrderPlaced",
        context=ctx,
        kind=trace.SpanKind.CONSUMER,
    ) as span:
        span.set_attribute("messaging.system", "rabbitmq")
        span.set_attribute("messaging.destination", msg.routing_key)
        span.set_attribute("messaging.message_id", msg.message_id)
        await handle_order_placed(msg)

// Go — OpenTelemetry com net/http, spans manuais e propagação Kafka

package main

import (
    "context"
    "log/slog"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/attribute"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
    "go.opentelemetry.io/otel/propagation"
    "go.opentelemetry.io/otel/sdk/resource"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    semconv "go.opentelemetry.io/otel/semconv/v1.26.0"
    "go.opentelemetry.io/otel/trace"
    "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
)

var tracer trace.Tracer

func initOTel(ctx context.Context) func() {
    exp, _ := otlptracegrpc.New(ctx,
        otlptracegrpc.WithEndpoint("otel-collector:4317"),
        otlptracegrpc.WithInsecure(),
    )

    res, _ := resource.New(ctx,
        resource.WithAttributes(
            semconv.ServiceName("order-service"),
            semconv.ServiceVersion("1.0.0"),
            attribute.String("deployment.environment", "production"),
        ),
    )

    tp := sdktrace.NewTracerProvider(
        sdktrace.WithBatcher(exp),
        sdktrace.WithResource(res),
        sdktrace.WithSampler(sdktrace.ParentBased(sdktrace.TraceIDRatioBased(0.1))),
    )
    otel.SetTracerProvider(tp)
    otel.SetTextMapPropagator(propagation.TraceContext{})

    tracer = otel.Tracer("order-service")
    return func() { tp.Shutdown(ctx) }
}

// HTTP handler auto-instrumentado com otelhttp
func main() {
    shutdown := initOTel(context.Background())
    defer shutdown()

    mux := http.NewServeMux()
    mux.Handle("/api/orders", otelhttp.NewHandler(
        http.HandlerFunc(PlaceOrderHandler),
        "PlaceOrder",
    ))
    http.ListenAndServe(":8080", mux)
}

// Span manual de negócio
func PlaceOrderHandler(w http.ResponseWriter, r *http.Request) {
    ctx, span := tracer.Start(r.Context(), "PlaceOrder",
        trace.WithAttributes(
            attribute.String("order.customer_id", r.Header.Get("X-Customer-Id")),
        ),
    )
    defer span.End()

    order, err := placeOrder(ctx, parseRequest(r))
    if err != nil {
        span.RecordError(err)
        span.SetStatus(codes.Error, err.Error())
        http.Error(w, err.Error(), 500)
        return
    }
    span.SetAttributes(attribute.String("order.id", order.ID))
    writeJSON(w, order)
}

// Propagação em Kafka com franz-go
type kafkaHeaderCarrier []kgo.RecordHeader

func (c *kafkaHeaderCarrier) Get(key string) string {
    for _, h := range *c {
        if h.Key == key {
            return string(h.Value)
        }
    }
    return ""
}
func (c *kafkaHeaderCarrier) Set(key, val string) {
    *c = append(*c, kgo.RecordHeader{Key: key, Value: []byte(val)})
}
func (c kafkaHeaderCarrier) Keys() []string {
    keys := make([]string, len(c))
    for i, h := range c {
        keys[i] = h.Key
    }
    return keys
}

func processKafkaRecord(ctx context.Context, record *kgo.Record) {
    carrier := kafkaHeaderCarrier(record.Headers)
    parentCtx := otel.GetTextMapPropagator().Extract(ctx, carrier)

    ctx, span := tracer.Start(parentCtx, "process "+record.Topic,
        trace.WithSpanKind(trace.SpanKindConsumer),
        trace.WithAttributes(
            semconv.MessagingSystemKafka,
            semconv.MessagingDestinationName(record.Topic),
            attribute.Int64("messaging.kafka.partition", int64(record.Partition)),
            attribute.Int64("messaging.kafka.offset", record.Offset),
        ),
    )
    defer span.End()

    slog.InfoContext(ctx, "processando mensagem",
        "topic", record.Topic,
        "partition", record.Partition,
        "offset", record.Offset,
    )
    // slog com OTel bridge injeta trace_id/span_id no structured log automaticamente
}

Checklist de observabilidade para comunicação distribuída

Antes de colocar um serviço em produção, verifique:

Traces: toda requisição HTTP de entrada gera um trace. Spans são criados para chamadas externas (HTTP downstream, banco de dados, cache, fila). O trace context é propagado em headers HTTP e metadados de mensagens. Erros são registrados no span com RecordError.

Métricas: métricas RED estão disponíveis por endpoint (rate, errors, duration). Consumer lag está sendo exportado para o Prometheus. Métricas de negócio relevantes (pedidos criados, pagamentos processados) estão sendo coletadas com atributos de dimensão.

Logs: logs são estruturados (JSON). Todo log emitido dentro de um span ativo inclui trace_id e span_id. Mensagens de log incluem correlation_id de negócio. Logs de erro incluem o stack trace completo.

Alertas: alerta de consumer lag crescente. Alerta de taxa de erro acima do SLO. Alerta de mensagens na DLQ. Alerta de P99 de latência acima do threshold.

1. Instrumente um serviço simples com OpenTelemetry (na linguagem de sua preferência), exporte para Jaeger local (Docker), e visualize um trace completo incluindo um span de banco de dados e um span de chamada HTTP externa. Adicione o atributo de negócio order.id ao span raiz e encontre o trace no Jaeger filtrando por esse atributo.
   Critério: trace visível no Jaeger com pelo menos 3 spans (http.server, db.query, http.client); atributo order.id aparece no span raiz e é pesquisável; erro simulado em um span aparece com vermelho e mensagem de erro no trace.
2. Implemente propagação de trace através de uma fila RabbitMQ: o produtor injeta o traceparent nos headers da mensagem usando o propagador W3C TraceContext, e o consumidor extrai e cria um span filho com CONSUMER kind. Visualize no Jaeger que o trace é contínuo — o span do consumidor aparece como filho do span de publicação.
   Critério: um único trace no Jaeger mostrando produtor → publicação na fila → consumo, com o span de consumo sendo filho do span de publicação; o gap de tempo entre publicação e consumo aparece claramente no trace como tempo de enfileiramento.
3. Configure métricas RED com Prometheus e crie um dashboard no Grafana com: request rate (req/s), taxa de erros (%), e heatmap de latência (p50/p95/p99). Crie um alerta que dispara quando o P99 ultrapassa 500ms por mais de 2 minutos consecutivos.
   Critério: dashboard com os 3 painéis funcionando com dados reais; alerta dispara corretamente ao simular latência alta (sleep no handler); alerta resolve automaticamente quando a latência volta ao normal.
4. Configure consumer lag monitoring para um consumer Kafka: use o kafka-exporter ou burrow para expor o lag por partição no Prometheus. Crie um alerta que dispara quando o lag de qualquer partição excede 1000 mensagens por mais de 5 minutos. Demonstre o alerta parando o consumer e produzindo mensagens.
   Critério: lag por partição visível no Grafana em tempo real; alerta dispara em menos de 6 minutos após lag exceder 1000; ao reiniciar o consumer, lag diminui e alerta resolve.
5. Debugging exercise: em um sistema com 3 serviços e uma fila RabbitMQ, introduza um bug de falha intermitente (10% das mensagens falham com erro aleatório de negócio). Usando traces (Jaeger), logs estruturados (com trace_id) e métricas (taxa de erro por fila), identifique: qual serviço falha, com qual erro, e qual atributo das mensagens causa a falha.
   Critério: causa raiz identificada usando os três sinais; processo documentado — qual sinal revelou o problema, em que ordem, e o que cada sinal contribuiu; tempo de diagnóstico medido (do alerta à causa raiz).