felvieira/observability-sre

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
• 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.