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 MDC	Valor
`sagaId`	UUID da saga em execução
`sagaName`	Nome da saga (`@Saga("pix-payment")`)
`stepName`	Nome do step atual
`attempt`	Nú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:

04:59 [pix-payment/validate-dict] [attempt=1] INFO  Validating DICT key abc-123
05:00 [pix-payment/block-balance] [attempt=1] INFO  Blocking balance R$ 150.00
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étrica	Tipo	Tags	Descrição
`sagaweaw.saga.started`	Counter	`saga`	Total de sagas iniciadas
`sagaweaw.saga.completed`	Counter	`saga`	Total de sagas concluídas
`sagaweaw.saga.failed`	Counter	`saga`	Total de sagas que falharam
`sagaweaw.saga.compensated`	Counter	`saga`	Total de sagas compensadas
`sagaweaw.saga.duration`	Timer	`saga`	Distribuição de duração por saga
`sagaweaw.step.duration`	Timer	`saga`, `step`	Distribuição de duração por step
`sagaweaw.step.attempts`	DistributionSummary	`saga`, `step`	Distribuição de tentativas
`sagaweaw.deadletter.created`	Counter	`saga`, `step`	Dead 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 Pronto para Usar

O Sagaweaw disponibiliza um dashboard Grafana pré-configurado com 8 painéis:

Painel	Tipo	O que mostra
Sagas Started	Stat	Total de sagas iniciadas no intervalo
Success Rate	Stat	Taxa de sucesso (último 5m), com thresholds verde/laranja/vermelho
Compensated	Stat	Sagas que ativaram compensação
Outbox Pending	Stat	Mensagens aguardando publicação no Kafka
Saga Volume	Time series	Rate de started/completed/failed/compensated por minuto
Saga Duration P50/P95	Time series	Latência mediana e percentil 95 em ms
Step Bottleneck P95	Bar gauge	Steps mais lentos (P95 de duração)
Step Failure Rate	Bar gauge	Steps que mais falham (falhas/segundo)

Importando

No Grafana: Dashboards → Import → Upload JSON file
Faça upload do arquivo grafana-dashboard.json do repositório
Selecione seu datasource Prometheus — pronto

O dashboard usa duas variáveis de template: $datasource (Prometheus) e $saga (filtra por saga específica ou exibe todas).

Dashboard embutido vs. Grafana

O Sagaweaw Dashboard (embutido, porta 8484) é uma lente de debug — inspecione sagas individuais, veja timelines de steps e gerencie dead letters em tempo real.

O Grafana é para observabilidade de produção em escala: alertas, retenção histórica e 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

OpenTelemetry — Rastreamento Distribuído

O Sagaweaw emite spans OTel automaticamente via Micrometer Observation API. Cada execução e compensação de step gera um span com os seguintes atributos:

Atributo	Valor
`saga.step.name`	Nome do step
`saga.step.type`	`COMPENSABLE`, `PIVOT` ou `RETRIABLE`
`saga.id`	UUID da saga
`saga.name`	Nome da saga
`saga.step.attempt`	Número da tentativa

Os spans funcionam com qualquer backend OTel: Jaeger, Zipkin, Grafana Tempo, Datadog, Elastic APM.

Ativando

Adicione o bridge OTel ao classpath — nenhuma outra configuração é necessária:

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing-bridge-otel</artifactId>
</dependency>
<dependency>
    <groupId>io.opentelemetry.instrumentation</groupId>
    <artifactId>opentelemetry-spring-boot-starter</artifactId>
</dependency>

Para desativar os spans sem remover as dependências:

sagaweaw.tracing.enabled=false

Dois tipos de span por saga

sagaweaw.step.invoke — executado no caminho feliz, via interceptor chain. sagaweaw.step.compensate — executado durante compensação em ordem inversa.

Kafka — Outbox Relay (Opcional)

O Sagaweaw funciona 100% sem Kafka. O padrão outbox está embutido — cada step completo escreve uma mensagem na tabela sagaweaw_outbox_messages. Kafka é apenas o mecanismo de entrega opcional.

Para ativar, adicione spring-kafka ao classpath e configure o broker:

<dependency>
    <groupId>org.springframework.kafka</groupId>
    <artifactId>spring-kafka</artifactId>
</dependency>

spring.kafka.bootstrap-servers=localhost:9092

O Sagaweaw detecta o KafkaTemplate automaticamente e inicia o relay. Os tópicos seguem o padrão sagaweaw.<saga-name>.<step-name>. Cada mensagem inclui o header idempotency-key para deduplicação no consumer.

Para desativar explicitamente mesmo com spring-kafka no classpath:

sagaweaw.kafka.enabled=false

Veja o guia completo de integração com Kafka →

MDC — Logging Contextualizado​

Exemplo de log enriquecido​

Micrometer — Métricas Automáticas​

Métricas disponíveis​

Nenhuma configuração necessária​

Prometheus​

Exemplos de PromQL​

Grafana — Dashboard Pronto para Usar​

Importando​

Configuração Completa​

OpenTelemetry — Rastreamento Distribuído​

Ativando​

Kafka — Outbox Relay (Opcional)​

Próximos Passos​