observability-sre git:20260520.a6788a6A

Immutable. This exact content is served forever at /api/v1/blob/c888849d619a645e.

---
name: observability-sre
description: |
  Skill de observabilidade e confiabilidade operacional. Use quando precisar definir logs, metricas, tracing,
  alertas, health checks, readiness, error budgets, rollback e operacao segura de servicos.
---

# Observability SRE

O Observability SRE garante que o sistema seja operavel, monitoravel e recuperavel em producao.

## Runtime Feedback Sensors (v2.7.0+)

> **Inspiração:** Birgitta Böckeler (Thoughtworks) — _"What runtime feedback could agents be monitoring? (e.g. having them look for degrading SLOs to make suggestions, or AI judges continuously sampling response quality and flagging log anomalies)"_. Ver `docs/inspiration/harness-engineering.md` + `policies/harness-categories.md`.

Esta skill agora também trata **runtime feedback como categoria de sensor** — não só configuração de monitoring, mas **uso ativo dessa telemetria pelo agente** durante feature work.

### O gap fechado

Antes do v2.7.0, o kit tinha **apenas sensores estáticos** (arquivos, hook de tool call). Não usava sinais de produção.

Birgitta lista 2 classes de runtime sensors valiosos:
1. **SLO degradation suggestions** — agente vê P95 latency degradando e sugere otimizações
2. **AI judges continuamente** — sampling de logs/responses pra flag anomalias

### Quando incorporar runtime feedback

| Situação | Recomendação |
|---|---|
| Feature de performance crítica | ✅ Forte — incluir P95 atual como input |
| Bug de produção sendo investigado | ✅ Forte — logs recentes são source-of-truth |
| Refactor de código quente (alto traffic) | ✅ Médio — verificar SLO antes/depois |
| Feature greenfield | 🟡 Skip — não tem telemetria ainda |
| Spike/POC | 🟡 Skip — overhead |
| Sem ferramenta de observability instalada | 🔴 Skip — pré-requisito ausente |

### Workflow: SLO-driven feature work

```
1. Antes de implementar: puxar SLO atual do endpoint/feature alvo
   Datadog:    via API com DD_API_KEY + DD_APP_KEY
   Grafana:    via Grafana HTTP API
   CloudWatch: aws cloudwatch get-metric-statistics
   New Relic:  via NerdGraph API
   Honeycomb:  via Query API

2. Anotar baseline em docs/specs/<feature>.md:
   "Baseline P95: 320ms, error rate: 0.4%, throughput: 1200 rpm"

3. Implementar feature com policies/source-driven.md aplicado

4. Após deploy (canary): re-puxar SLO em 5min/30min/2h
   "Atual P95: 340ms (+6%) — dentro do budget de 10%"
   ou
   "Atual P95: 420ms (+31%) — VIOLATED budget, rollback considerado"

5. Documentar mudança no postmortem se houve impacto não previsto
```

### Workflow: Log anomaly detection

Para apps com alto volume de logs estruturados:

```
1. Definir baseline de error rate por endpoint (skill 21 data-analytics ajuda)
2. Configurar log sampling pra LLM (não enviar tudo — caro):
   - 100% de errors
   - 1% de info logs
   - 10% de warnings
3. Agente periodicamente (ou via /loop --schedule daily):
   - Pull samples da última hora
   - Procura anomalias (padrões novos, spikes em error class específica)
   - Sugere investigação ou hotfix
4. Output: thread no GitHub Issues / Linear com contexto
```

**Custo realista:** LLM judge custa ~$5-20/mês pra app médio. Compare com tempo de SRE pra identificar same issues manualmente.

### Workflow: Response quality sampling (apps com IA)

Para apps onde output é AI-generated (chatbots, content gen, code suggestion):

```
1. Sample 1% das responses (mais alto = mais caro)
2. AI judge avalia: relevância, factualidade, tom, safety
3. Se score < threshold → flagga pra revisão humana
4. Agregação semanal: "92% passaram. Top 3 padrões de falha: ..."
```

### Anti-padrões específicos

- ❌ **Logar payload inteiro** — vaza PII, ocupa espaço, vira lixo no LLM context
- ❌ **Polling sem cache** — bate API toda invocação, viola rate limits
- ❌ **Threshold absoluto** (`< 300ms`) sem contexto — endpoint pesado pode ser 800ms legitimamente
- ❌ **AI judge sem feedback humano** — vira eco chamber, não calibra
- ❌ **Sample biased** (só errors) — não vê o baseline normal

### Integração com outras skills

| Skill | Como integra |
|---|---|
| 03 (backend) | Backend implementations devem expor metrics conforme convenção desta skill |
| 07 (deploy) | Deploy pipelines devem rodar smoke test pull dos SLOs pós-deploy |
| 21 (data-analytics) | Eventos de produto complementam SLOs técnicos |
| 24 (release-manager) | Release notes incluem snapshot de SLOs (antes/depois) |
| 30 (cost-tracker) | LLM judge cost contabilizado aqui |

### Roadmap derivado

- v2.7.1 — `scripts/pull-slo.mjs` helper genérico (Datadog/Grafana/CloudWatch)
- v2.7.2 — `commands/check-slo.md` slash command
- v2.8.0 — Integração com `/savings`: mostrar quantas decisões foram informadas por runtime data
- v2.8.0 — `programs/slo-driven-feature.yml` program que enforce o workflow acima

### Referências

- Google SRE Book (capítulos 4-5: SLOs, SLIs)
- Honeycomb's [Observability Engineering](https://www.oreilly.com/library/view/observability-engineering/9781492076438/)
- `policies/harness-categories.md` — runtime feedback é categoria nova de sensor
- `policies/quality-gates.md` "Keep quality left" — runtime sensors ficam mais à direita

## Governanca Global

Esta skill segue `GLOBAL.md`, `policies/execution.md`, `policies/handoffs.md`, `policies/quality-gates.md`, `policies/token-efficiency.md`, `policies/tool-safety.md`, `policies/stack-flexibility.md` e `policies/evals.md`.

Para playbooks e exemplos operacionais mais detalhados, consultar `docs/skill-guides/observability-sre.md` apenas quando necessario.

## Quando Usar

- definir logs, metricas, tracing e alertas
- criar health checks, readiness e estrategia de rollback
- melhorar operacao de deploy, incidentes e diagnostico

## Quando Nao Usar

- para substituir Security, Deploy ou Backend em mudancas de dominio
- para adicionar telemetria sem criterio de produto ou operacao

## Entradas Esperadas

- stack real do servico ou app
- pontos criticos do fluxo de negocio
- sinais atuais de deploy, erro, performance e operacao

## Saidas Esperadas

- plano de observabilidade e confiabilidade
- eventos e sinais operacionais priorizados
- handoff claro para Backend, Frontend, Deploy ou Documenter

## Responsabilidades

1. Definir sinais essenciais: logs, metricas, traces e alertas
2. Garantir health checks, readiness e rollback praticaveis
3. Identificar lacunas de monitoramento e diagnostico
4. Reduzir ruido de telemetria e focar no que ajuda operacao real
5. Registrar runbooks e riscos operacionais quando necessario

## Checklist Base

- logs estruturados sem dados sensiveis
- metricas de latencia, erro e throughput nas rotas criticas
- tracing ou correlacao minima para debug entre camadas
- health check e readiness separados quando fizer sentido
- alertas acionaveis e sem excesso de ruido
- rollback e runbook claros para incidentes principais

## Evidencia de Conclusao

- sinais operacionais principais definidos
- lacunas e riscos priorizados
- pontos de integracao com deploy e docs registrados

## Handoff

Seguir `policies/handoffs.md` e, quando util, `templates/observability-check.md`, `templates/risk-note.md` e `templates/doc-update.md`.