Capítulo 41 — Observabilidade e Monitoramento

{
  "timestamp": "2026-07-16T10:30:45.123Z",
  "level": "ERROR",
  "logger": "com.platform.request.service.SubmitRequestUseCase",
  "message": "Falha ao validar documento exigido",
  "correlationId": "corr-a7f2-4b81-9c3d",
  "tenantId": "tenant-org-a",
  "userId": "user-uuid-123",
  "serviceId": "svc-habilitacao",
  "documentType": "RG",
  "error": "DOCUMENT_EXPIRED",
  "stackTrace": "..."
}

http_requests_total{method="POST", status="201", endpoint="/requests", tenant="org-a"} 1234
http_request_duration_seconds{method="GET", endpoint="/requests", tenant="org-a", quantile="0.95"} 0.150
database_connection_pool_active{service="request-service", pool="primary"} 42
cache_hit_rate{cache="catalog", tenant="org-a"} 0.87

Request entrada → API Gateway (span-1) 
  └─ autenticação (span-2, 10ms)
  └─ Request Service (span-3, 150ms)
    └─ Document Service (span-4, 80ms)
    └─ RabbitMQ publish (span-5, 5ms)
  └─ Response (total 155ms)

Aplicação (instrumentation)
    │
SDK OpenTelemetry
    ├─ LogRecordProcessor
    ├─ MetricReader
    └─ SpanProcessor
    │
Exportador (OTLP/gRPC ou HTTP)
    │
Backend observabilidade (Grafana Loki, Prometheus, Jaeger)

<!-- pom.xml -->
<dependency>
  <groupId>io.opentelemetry.instrumentation</groupId>
  <artifactId>opentelemetry-instrumentation-bom</artifactId>
  <version>1.32.0</version>
  <type>pom</type>
  <scope>import</scope>
</dependency>

<dependency>
  <groupId>io.opentelemetry.instrumentation</groupId>
  <artifactId>opentelemetry-spring-boot-starter</artifactId>
</dependency>

# application-prod.yml
otel:
  exporter:
    otlp:
      endpoint: http://otel-collector:4317
  metrics:
    export:
      interval: 60000
  traces:
    sample_rate: 0.1

MDC.put("tenantId", tenantId);
MDC.put("userId", userId);
MDC.put("correlationId", correlationId);
MDC.put("spanId", spanId);

logger.info("Request iniciada");
// Log incluirá automaticamente tenantId, userId, etc.

MDC.clear(); // No final da requisição

@Service
public class SubmitRequestService {
  private final MeterRegistry meterRegistry;
  private final Counter requestsSubmitted;
  private final Timer requestLatency;

  public SubmitRequestService(MeterRegistry meterRegistry) {
    this.meterRegistry = meterRegistry;
    this.requestsSubmitted = Counter.builder("requests.submitted")
      .tag("service", "request-service")
      .description("Total de solicitações submetidas")
      .register(meterRegistry);
    
    this.requestLatency = Timer.builder("request.latency.ms")
      .publishPercentiles(0.5, 0.95, 0.99)
      .register(meterRegistry);
  }

  public RequestResponse submitRequest(SubmitRequestCommand cmd) {
    return requestLatency.record(() -> {
      RequestResponse response = doSubmit(cmd);
      requestsSubmitted.increment(1, Tags.of("status", "success"));
      return response;
    });
  }
}

Rate (Taxa de requisições)
  http_requests_total{endpoint="/requests", method="POST", tenant="org-a"}

Errors (Taxa de erro)
  http_requests_total{endpoint="/requests", status="500"} / http_requests_total{endpoint="/requests"}

Duration (Latência)
  http_request_duration_seconds{endpoint="/requests", quantile="0.95"}

Solicitações por serviço
  requests_submitted_total{service_type="habilitacao", tenant="org-a"}

Taxa de complementação
  requests_complement_asked_total / requests_submitted_total

Tempo médio de atendimento
  request_resolution_time_seconds{service_type="habilitacao"}

@RestController
@RequestMapping("/requests")
public class RequestController {
  
  @PostMapping
  public ResponseEntity<RequestResponse> submitRequest(
      @RequestBody SubmitRequestRequest request,
      HttpServletRequest httpRequest) {
    
    // Extrair trace context de headers (W3C Trace Context)
    String traceId = httpRequest.getHeader("traceparent");
    String correlationId = httpRequest.getHeader("x-correlation-id");
    
    MDC.put("traceId", traceId);
    MDC.put("correlationId", correlationId);
    
    // Serviço consome correlationId
    RequestResponse response = submitRequestService.submit(request, correlationId);
    
    // Propagado em chamadas downstream
    // Exemplo: requisição ao Document Service inclui headers
    return ResponseEntity.status(HttpStatus.CREATED).body(response);
  }
}

POST /requests (200ms total)
  ├─ Authentication (10ms) — IAM Service
  ├─ Submit Request (150ms) — Request Service
  │   ├─ Validate (30ms) — validation logic
  │   ├─ Document Service call (50ms) — network
  │   └─ RabbitMQ publish (20ms)
  └─ Response serialization (5ms)

Mês com 30 dias = 43.200 segundos
Error budget (0.1%) = 43,2 segundos downtime permitido

Se já usou 40s em failover, só restam 3,2s para o mês

# Prometheus AlertManager
groups:
- name: platform
  rules:
  
  # Alert: Taxa de erro alta
  - alert: HighErrorRate
    expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.05
    for: 5m
    annotations:
      summary: "Taxa de erro > 5% no {{ $labels.service }}"
      description: "{{ $value }} errors/sec"
    labels:
      severity: critical
      team: platform
  
  # Alert: Latência degradada
  - alert: HighLatency
    expr: histogram_quantile(0.95, http_request_duration_seconds) > 1
    for: 10m
    annotations:
      summary: "P95 latência > 1s"
    labels:
      severity: warning
  
  # Alert: Cache miss rate
  - alert: CacheMissRateHigh
    expr: rate(cache_miss_total[5m]) / rate(cache_access_total[5m]) > 0.3
    annotations:
      summary: "Cache miss rate > 30%"
    labels:
      severity: warning

AlertManager dispara alerta crítico
    │
PagerDuty: notifica engineer on-call (SMS + app)
    │
Engineer acessa runbook
    │
Executa passos (kubectl, curl, rollback)
    │
Escalação automática se não responder em 5m

# Causa Provável
1. Falha em serviço downstream (Document Service)
2. Indisponibilidade de banco de dados
3. Fuga de memória causando OOM

# Diagnóstico

## Passo 1: Verificar pods
kubectl get pods -l app=api-solicitacoes -n production
# Se algum pod em CrashLoopBackOff: verificar logs

## Passo 2: Verificar logs
kubectl logs -l app=api-solicitacoes -n production --tail=100 | grep ERROR

## Passo 3: Verificar dependências
- Document Service: curl http://document-service/health
- PostgreSQL: pg_isready -h postgres.default.svc

# Remediação

## Se Document Service indisponível
kubectl rollout status deployment/document-service -n production
# Se deployment é novo, fazer rollback
kubectl rollout undo deployment/document-service -n production

## Se banco offline
# Verificar replicação: SELECT * FROM pg_stat_replication;
# Reiniciar: kubectl rollout restart statefulset/postgres-primary

## Se OOM
# Aumentar memory limit
kubectl set resources deployment/api-solicitacoes \
  --limits=memory=4Gi --requests=memory=2Gi