Pular para o conteúdo principal

Integrações de Observabilidade

O Sagaweaw se integra automaticamente com o stack de observabilidade que você já usa — sem configuração extra além do starter.

MDC — Logging Contextualizado​

Ao executar qualquer step, o Sagaweaw enriquece o MDC (Mapped Diagnostic Context) com os seguintes campos:

Campo MDCValor
sagaIdUUID da saga em execução
sagaNameNome da saga (@Saga("pix-payment"))
stepNameNome do step atual
attemptNúmero da tentativa atual (começa em 1)

Exemplo de log enriquecido​

Com Logback (padrão Spring Boot), adicione %X{sagaId} ao seu pattern para incluir o contexto automaticamente:

<!-- logback-spring.xml -->
<pattern>%d{HH:mm:ss} [%X{sagaName}/%X{stepName}] [attempt=%X{attempt}] %-5level %msg%n</pattern>

Saída:

10:04:59 [pix-payment/validate-dict] [attempt=1] INFO  Validating DICT key abc-123
10:05:00 [pix-payment/block-balance] [attempt=1] INFO  Blocking balance R$ 150.00
10:05:01 [pix-payment/transmit-to-bacen] [attempt=3] WARN  Timeout — retrying in 4s

Quando a saga termina (com sucesso ou falha), os campos MDC são removidos automaticamente — sem vazamento entre threads no pool.

Correlação com outras ferramentas

O campo sagaId pode ser propagado via OpenTelemetry, Datadog trace ID ou Elastic APM para correlacionar a saga com spans de rastreamento distribuído.

Micrometer — Métricas Automáticas​

O Sagaweaw publica métricas via Micrometer automaticamente quando o micrometer-core está no classpath (incluído por padrão no Spring Boot Actuator).

Métricas disponíveis​

MétricaTipoTagsDescrição
sagaweaw.saga.startedCountersagaTotal de sagas iniciadas
sagaweaw.saga.completedCountersagaTotal de sagas concluídas
sagaweaw.saga.failedCountersagaTotal de sagas que falharam
sagaweaw.saga.compensatedCountersagaTotal de sagas compensadas
sagaweaw.saga.durationTimersagaDistribuição de duração por saga
sagaweaw.step.durationTimersaga, stepDistribuição de duração por step
sagaweaw.step.attemptsDistributionSummarysaga, stepDistribuição de tentativas
sagaweaw.deadletter.createdCountersaga, stepDead letters criadas

Nenhuma configuração necessária​

Se o spring-boot-starter-actuator estiver no classpath, as métricas são publicadas automaticamente. Não há bean para declarar nem @EnableSagaMetrics.

<!-- Apenas isso é suficiente -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Prometheus​

Com micrometer-registry-prometheus no classpath, as métricas são expostas em /actuator/prometheus no formato Prometheus.

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

Exemplos de PromQL​

# Taxa de sagas com falha por minuto, por nome de saga
rate(sagaweaw_saga_failed_total[1m])

# Percentil 95 de duração da saga "pix-payment"
histogram_quantile(0.95,
  rate(sagaweaw_saga_duration_seconds_bucket{saga="pix-payment"}[5m])
)

# Percentil 99 de duração do step "transmit-to-bacen"
histogram_quantile(0.99,
  rate(sagaweaw_step_duration_seconds_bucket{step="transmit-to-bacen"}[5m])
)

# Dead letters criadas na última hora
increase(sagaweaw_deadletter_created_total[1h])

# Taxa de sucesso (últimos 5 minutos)
rate(sagaweaw_saga_completed_total[5m]) /
(rate(sagaweaw_saga_completed_total[5m]) + rate(sagaweaw_saga_failed_total[5m]))

Grafana — Dashboard Recomendado​

Configure o Prometheus como datasource e importe um dashboard com os seguintes painéis sugeridos:

┌─────────────────────┬─────────────────────┬─────────────────────┐
│  Taxa de Sucesso     │  Sagas/min          │  Dead Letters        │
│  (gauge, %)         │  (time series)      │  (stat, vermelho)   │
├─────────────────────┴─────────────────────┴─────────────────────┤
│  Duração p50/p95/p99 por saga type (time series por saga)       │
├─────────────────────┬─────────────────────────────────────────┤
│  Steps mais lentos   │  Tentativas médias por step              │
│  (table, p95)       │  (bar chart)                            │
└─────────────────────┴─────────────────────────────────────────┘
Dashboard vs. Sagaweaw Dashboard

O Sagaweaw Dashboard (embutido) é uma lente de debug — ideal para inspecionar sagas individuais, ver timelines de steps e gerenciar dead letters em tempo real.

O Grafana é para observabilidade de produção em larga escala: alertas, retenção histórica, correlação com outras métricas do sistema.

Use os dois.

Configuração Completa​

Configuração mínima para ativar tudo:

# application.yml
sagaweaw:
  enabled: true
  observability:
    enabled: true
    token: ${SAGAWEAW_TOKEN}

management:
  endpoints:
    web:
      exposure:
        include: health, prometheus, metrics
  metrics:
    tags:
      application: ${spring.application.name}
      env: ${spring.profiles.active:local}

Com isso você tem, automaticamente:

  • MDC enriquecido em todos os logs de steps
  • Métricas Micrometer para todos os eventos de saga
  • Endpoint /actuator/prometheus para scraping pelo Prometheus
  • Dashboard embutido via sagaweaw.observability.token

Próximos Passos​