@luanpdd/kit-mcp 1.8.1 → 1.10.0

package/kit/skills/event-based-slos/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: event-based-slos
+description: Use ao definir SLO — SLI event-based (não time-based), sliding window 30d, decouple what/why. SLO-based alerts substituem thresholds brutos como CPU/memória.
+---
+
+# Observabilidade — Event-Based SLOs
+
+## Quando usar
+
+LLM carrega esta skill ao definir/avaliar SLOs ou substituir alertas threshold por SLO-based. Trigger phrases:
+
+- "definir SLO", "criar SLI"
+- "alertas confiáveis", "alert fatigue"
+- "error budget", "sliding window"
+- "como medir saúde do serviço"
+- "decouple what from why"
+
+## Regras absolutas
+
+- **SLI sempre event-based, nunca time-based** — "% de eventos com `result.success=true` em 30d" > "% de janelas de 5min com p99 < 300ms"
+- **Sliding window 30d por default** — fixed window (calendário) gera comportamento perverso (cliente não esquece bug por causa de reset).
+- **Target ≤ 99.95%** — para SLO 99.99%+ você não tem tempo de reagir antes do budget acabar; use métricas/dashboards informativos em vez de SLO.
+- **Decouple "what" do "why"** — SLO alert diz que tem dor (sintoma); investigation descobre porquê (use [`core-analysis-loop`](../skills/core-analysis-loop/SKILL.md)). NUNCA misturar (anti-pattern: "alert se memória > 80% AND p99 > 300ms").
+- **Customer-facing journey, não system metric** — SLI mede o que o cliente sente ("login funcionou em < 800ms"), não estado interno ("threads ativas").
+- **Granular por endpoint/feature** — 1 SLO por jornada crítica do user. Não SLO global "site availability" — específico demais para ser ignorável.
+- **Owner explícito** — cada SLO tem dono nomeado. Sem owner = sem ação = sem valor.
+- **Substituir alertas threshold gradualmente** — após SLO comprovar valor (1+ incident detectado por SLO antes de threshold), DELETAR threshold antigo.
+
+## Risk continuum — SLO target é decisão explícita
+
+> Cross-ref canônico: [sre-risk-management](../sre-risk-management/SKILL.md) (cap 3 do livro Google SRE — Embracing Risk).
+
+SLO target NÃO é meta arbitrária ("queremos 99.99% porque soa bom"). É uma escolha consciente no **continuum risk × innovation**: cada nove adicional **multiplica custo** mas **divide benefício marginal** percebido pelo cliente.
+
+| Target | Tolerância 30d | User-perceptible? | Quando faz sentido |
+|---|---|---|---|
+| 99% | 7.2 h | Sim, notável | Tier free, beta features, internal tools |
+| 99.5% | 3.6 h | Notável em paths críticos | Tier free de produção |
+| 99.9% | 43.2 min | Aceitável para maior parte de UX | Tier paid default |
+| 99.95% | 21.6 min | Quase imperceptível | Tier enterprise / mission-critical |
+| 99.99% | 4.3 min | Imperceptível em smartphone (~99% no canal do user) | Apenas se justificado por user perception (raro) |
+
+**Sabedoria 99.99%** — cliente final acessa via smartphone (~99% disponibilidade) com ISP residencial (~99%). Serviço 99.99% **não é distinguível** de 99.999% nesse contexto: ambos parecem "sempre funcionando". Esforço além de 99.95% para serviço user-facing é tipicamente desperdício.
+
+**Error budget é o instrumento contábil dessa decisão.** Para SLO 99.9% em 30d com 10M eventos: budget = `0.001 × 10M = 10k bad events`. Esse 10k é orçamento explícito para gastar em deploys arriscados, experimentos, refactors. Quando esgota, releases freezam até regenerar — não como punição, mas como **balanço explícito risk × innovation**.
+
+**Diferentes tiers, diferentes targets** — `customer.tier='enterprise'` pode justificar 99.95%; `tier='free'` pode operar em 99.5%. Tratar todos como tier-1 desperdiça budget; tratar todos como tier-3 frustra clientes pagantes. A skill `sre-risk-management` documenta o framework completo de decisão.
+
+> Em resumo: a regra `Target ≤ 99.95%` desta skill (acima) é **consequência** do risk continuum, não restrição arbitrária. Para 99.99%+ trate como métrica informativa (dashboard), NÃO como SLO acionável (alerts).
+
+## Patterns canônicos
+
+### Pattern: SLI event-based vs time-based
+
+```sql
+-- PT-BR: BAD — SLI time-based (anti-pattern)
+-- "99% das janelas de 5 min têm p99 < 300ms"
+-- Problema: pre-aggregation perde fidelidade; janela com 1 outlier puxa p99.
+
+-- PT-BR: GOOD — SLI event-based
+-- "99.9% dos eventos individuais têm duration < 300ms e result_success = true"
+select 
+  count(*) filter (where duration_ms < 300 and result_success = true) as good,
+  count(*) as total,
+  count(*) filter (where duration_ms < 300 and result_success = true)::float / count(*) as compliance
+from observability.events
+where 
+  event_name = 'http_request' 
+  and endpoint = '/api/v1/orders'
+  and timestamp > now() - interval '30 days';
+```
+
+### Pattern: SLO definition canônico
+
+```yaml
+# PT-BR: SLO documentado em formato YAML — alimenta agent slo-engineer
+slo:
+  name: checkout_success
+  description: "Checkout completes successfully within 800ms (customer perception)"
+  owner: orders-team@company.com   # PT-BR: dono nomeado
+  
+  sli:
+    type: event_based              # PT-BR: NUNCA time-based
+    event_filter:
+      service: orders-api
+      endpoint: /api/v1/checkout
+      http_method: POST
+    good_event:                    # PT-BR: predicate booleano
+      result_success: true
+      duration_ms: { lt: 800 }
+    bad_event:                     # PT-BR: complemento
+      operator: not_good           # qualquer evento que não é "good"
+  
+  target: 0.999                    # PT-BR: 99.9% — não 99.99%+ por design
+  window: 30d_sliding              # PT-BR: nunca fixed/calendar
+  
+  alerts:                          # PT-BR: ver skill burn-rate-alerting
+    - name: page_short_term
+      lookahead: 4h
+      baseline: 1h
+      severity: page
+    - name: ticket_long_term
+      lookahead: 3d
+      baseline: 18h
+      severity: ticket
+```
+
+### Pattern: SLI materialized view (Postgres)
+
+```sql
+-- PT-BR: view materializa SLI events para queries baratas
+-- Refresh agendado (pg_cron) ou em tempo real (trigger)
+create materialized view obs.sli_checkout_success as
+select
+  date_trunc('minute', timestamp) as bucket,
+  count(*) filter (where result_success = true and duration_ms < 800) as good,
+  count(*) filter (where not (result_success = true and duration_ms < 800)) as bad,
+  count(*) as total
+from observability.events
+where 
+  service = 'orders-api'
+  and endpoint = '/api/v1/checkout'
+  and http_method = 'POST'
+  and timestamp > now() - interval '35 days'  -- 30d + buffer
+group by 1
+with no data;
+
+-- PT-BR: índice para queries de burn rate
+create index on obs.sli_checkout_success (bucket);
+
+-- PT-BR: refresh schedule via pg_cron — a cada 30s
+select cron.schedule(
+  'refresh_sli_checkout_success',
+  '*/30 * * * * *',
+  $$ refresh materialized view concurrently obs.sli_checkout_success $$
+);
+```
+
+### Pattern: SLO compliance query (atual e histórico)
+
+```sql
+-- PT-BR: compliance atual — % good no último 30d
+select 
+  sum(good)::float / nullif(sum(total), 0) as compliance_30d,
+  0.999 as target,
+  case 
+    when sum(good)::float / nullif(sum(total), 0) >= 0.999 then 'IN_BUDGET'
+    else 'OUT_OF_BUDGET'
+  end as status
+from obs.sli_checkout_success
+where bucket > now() - interval '30 days';
+
+-- PT-BR: error budget remaining
+-- Budget = (1 - target) × total_events
+-- Remaining = budget - bad_events_so_far
+select
+  (1 - 0.999) * sum(total) as budget,
+  sum(bad) as burned,
+  (1 - 0.999) * sum(total) - sum(bad) as remaining,
+  100.0 * (1 - sum(bad) / nullif((1 - 0.999) * sum(total), 0)) as remaining_pct
+from obs.sli_checkout_success
+where bucket > now() - interval '30 days';
+```
+
+### Pattern: SLO replacing thresholds (case study Honeycomb)
+
+```text
+ANTES (cap 12 do livro):
+  - Alert: CPU > 80% (false positive: garbage collector)
+  - Alert: memory > 90% (false positive: cache warming)
+  - Alert: 5xx > 1% in 5min (false negative: 0.5% por 1h burns 60% do budget)
+  - Alert: p99 latency > 500ms in 5min (false positive: 1 spike isolado)
+
+DEPOIS:
+  - 1 SLO: checkout_success em 30d sliding
+  - 1 alert preditivo: burn rate sustained 4h+
+  - 1 alert ticket: burn rate sustained 3d+
+  
+RESULTADO: 60% menos paginations, 100% dos incidents reais detectados.
+```
+
+### Pattern: customer-facing SLI dimensions
+
+| Dimensão | Valor | Por quê SLI deve incluir |
+|---|---|---|
+| `endpoint` | `/api/v1/checkout` | Granular — não SLO global |
+| `customer.tier` | `'enterprise'` | Diferentes targets por tier (Pro = 99.95% vs Free = 99.5%) |
+| `region` | `us-east-1` | Identificar problema regional vs global |
+| `feature_flag.<name>` | `true`/`false` | SLO durante rollout incremental |
+| `tenant_id` | `'acme'` | Big customers podem ter SLOs próprios |
+
+## Anti-patterns
+
+### ANTI: SLO 99.99% ou 99.999%
+
+```text
+ANTI: target 99.99% em SLO de 30d sliding
+  - 30d × 24h × 60min × (1-0.9999) = 4.3 minutos de tolerância
+  - Sem tempo para reagir antes do budget esgotar
+  - Burn rate alerts disparam após o budget acabar (zero-level)
+
+CERTO: target ≤ 99.95% para SLO real
+       Para 99.99%+, use métricas/dashboards informativos (não alerta)
+```
+
+### ANTI: SLO global "site up"
+
+```text
+ANTI: 1 SLO "site availability" para tudo
+  - Falha em /api/v1/admin não conta para 99% dos clientes
+  - Falha em /api/v1/checkout = catastrófico
+  - Misturar = alarmes confusos, ações vagas
+
+CERTO: 1 SLO por jornada crítica do user
+  - checkout_success: 99.9%
+  - login_success: 99.95%
+  - search_p95_latency: 99% < 200ms
+  - admin_panel: SEM SLO (uso baixo, latência aceitável)
+```
+
+### ANTI: SLO sem owner
+
+```text
+ANTI: SLO definido em retrospectiva, sem dono nomeado
+  - Burn alert dispara → ninguém atende → escalation
+  - Sem follow-up no fim do mês
+
+CERTO: SLO tem owner em arquivo (yaml ou tabela DB)
+       owner = team email ou pessoa específica
+       Burn alert roteia direto para owner antes de escalation
+```
+
+### ANTI: SLO == SLA externo
+
+```text
+ANTI: usar SLA do contrato (99.9% uptime) como SLO interno
+
+PROBLEMA: 0 margem de segurança. Atinge SLA mínimo no fio = 1 incident e quebra.
+
+CERTO: SLO interno mais rígido que SLA externo
+       SLA externo: 99.9% (compromisso com cliente)
+       SLO interno: 99.95% (margem de 5× para reagir)
+```
+
+### ANTI: alterar SLI quando burn ocorre
+
+```text
+ANTI: SLO está queimando → "vamos relaxar SLI para reduzir false positives"
+       (definir bad_event mais frouxo)
+
+PROBLEMA: você está mascarando dor real. Próximo incident similar passa silencioso.
+
+CERTO: SLI é compromisso com customer experience. Se está queimando, fixar
+       o problema (root cause via core-analysis-loop), não o SLI.
+       Se SLI sistematicamente errado (mede coisa errada): substituir, não relaxar.
+```
+
+### ANTI: fixed window (mensal/calendário)
+
+```text
+ANTI: error budget reseta dia 1 do mês
+
+PROBLEMA: 
+  - "Tivemos outage dia 31, reseta amanhã" — cliente NÃO esquece
+  - Pressão para postergar fixes para "depois do reset"
+  - Behavioral hazard: deploy arriscado dia 30
+
+CERTO: sliding window 30d
+       Outage dia 31 fica no budget até dia 30 do mês seguinte (sai gradualmente)
+       Sem incentivo perverso, comportamento humano realista
+```
+
+## Verificação
+
+Antes de marcar SLO como produção-pronto:
+
+1. **Owner nomeado** — email/team em `slo.owner`
+2. **SLI event-based** — pred boolean, não time-bucket
+3. **Target ≤ 99.95%** — > 99.95% sinaliza informativo, não SLO
+4. **Window 30d sliding** — não fixed
+5. **Customer-facing journey** — SLI mede o que o cliente sente
+6. **Materialized view** existe e é refreshable (pg_cron)
+7. **Burn alerts** configurados (ver skill `burn-rate-alerting`)
+8. **Quero SLO ou metric?** — se a resposta é "informativo", crie metric, não SLO
+
+---
+
+## Ver também
+
+- `kit/skills/_shared-observability/glossary.md` — termos canônicos SLI/SLO/error budget
+- `kit/skills/structured-events/SKILL.md` — eventos canônicos para alimentar SLI
+- `kit/skills/burn-rate-alerting/SKILL.md` — lookahead/baseline windows
+- `kit/skills/core-analysis-loop/SKILL.md` — investigar quando SLO queima
+- `kit/agents/slo-engineer.md` — gera SLO.md + SQL para materializar SLI
+
+*Material-fonte: Observability Engineering (O'Reilly, 2022) — Cap 12: "Using Service-Level Objectives for Reliability".*

package/kit/skills/four-golden-signals/SKILL.md

@@ -0,0 +1,297 @@
+---
+name: four-golden-signals
+description: Use ao instrumentar serviço user-facing — Latency + Traffic + Errors + Saturation, percentis (não mean), histogram exponencial, latência success vs error separadas.
+---
+
+# SRE — Four Golden Signals
+
+## Quando usar
+
+LLM carrega esta skill ao instrumentar Edge Function/serviço/microservice user-facing. Trigger phrases:
+
+- "golden signals", "4 sinais dourados"
+- "latency, traffic, errors, saturation"
+- "instrumentar serviço", "métricas mínimas"
+- "p99 latency", "percentis vs mean"
+- "black-box vs white-box monitoring"
+- "Google SRE cap 6"
+- "Latency success vs error"
+
+## Regras absolutas
+
+- **4 sinais são universais para serviço user-facing** — Latency + Traffic + Errors + Saturation. Se mede esses 4, captura ~95% da saúde operacional. Outros sinais (CPU, memória, disco I/O) são **causas potenciais**, não sintomas — vão em white-box monitoring secundário.
+- **Latency success vs error sempre separadas** — falhas rápidas (HTTP 500 em 5ms) mascaram latência ruim de successes se misturadas. Sempre `histogram(duration_ms, {result: 'success'})` e `histogram(duration_ms, {result: 'error'})` em séries distintas.
+- **NUNCA mean para latency** — long tail invisível: mean=50ms mas p99=5000ms é UX ruim para 1% dos usuários (tipicamente os mais valiosos: enterprise tier). SEMPRE histogram com percentis.
+- **Histogram com bucketing exponencial** — buckets `[1, 2, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000, 30000]` ms ou base 1.5/2. Captura long tail sem cardinality explosion.
+- **Errors counter por error.type (não message)** — `error.type` enumerado (5-15 valores: `timeout`, `validation`, `auth`, `rate_limit`, `db`, `provider_down`, ...). `error.message` é alta cardinalidade — não usar como dimension.
+- **Saturation é resource-specific** — não existe métrica genérica de saturação. Para HTTP service: connection pool used %. Para DB: tablespace used %. Para queue: queue depth. Para CPU-bound: load average. Identificar O recurso mais escasso ANTES de instrumentar.
+- **Black-box monitora UX, white-box monitora internals** — black-box (synthetic prober HTTP) detecta "site offline" mesmo se métricas internas estão verdes (corner case clássico). White-box (golden signals) explica "porquê" quando black-box dispara.
+- **Reportar p50, p95, p99, p99.9 — não só p99** — p50 (mediana) é UX típica; p95 é primeiro deslize; p99 é cauda; p99.9 é seu 1 em 1000 que é seu cliente enterprise. Cada percentil conta uma história diferente.
+
+## Patterns canônicos
+
+### Pattern: definição canônica dos 4 signals (tabela)
+
+| Signal | Definição | Tipo de instrument | Granularity recomendada |
+|---|---|---|---|
+| **Latency** | Tempo de request bem-sucedido vs falho — SEPARADO | Histogram (ms) com bucketing exponencial | Por endpoint × `result` (success/error) |
+| **Traffic** | Volume de demanda — requests/s, msgs/s, bytes/s | Counter | Por endpoint × method |
+| **Errors** | Taxa de requests que falharam (explícitas: 5xx; implícitas: 200 com payload errado; políticas: > SLO target) | Counter | Por endpoint × `error.type` |
+| **Saturation** | "Quão cheio" o serviço está — % do recurso mais escasso | ObservableGauge (%) | Por resource (connection pool, queue, CPU) |
+
+### Pattern: instrumentação canônica em OTel SDK (TypeScript/Deno)
+
+```ts
+// PT-BR: 4 golden signals em Edge Function — copiar este shape
+import { trace, metrics } from '@opentelemetry/api'
+
+const tracer = trace.getTracer('orders-service')
+const meter = metrics.getMeter('orders-service')
+
+// PT-BR: 1. LATENCY — histogram bucketed exponencial
+const latencyHistogram = meter.createHistogram('http_request_duration_ms', {
+  description: 'Request latency in ms — split by result',
+  unit: 'ms',
+  advice: { explicitBucketBoundaries: [1, 2, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000, 30000] }
+})
+
+// PT-BR: 2. TRAFFIC — counter de requests recebidos
+const trafficCounter = meter.createCounter('http_requests_total', {
+  description: 'Total HTTP requests received'
+})
+
+// PT-BR: 3. ERRORS — counter por error.type (categoria, não message)
+const errorsCounter = meter.createCounter('http_errors_total', {
+  description: 'Total HTTP errors by error.type'
+})
+
+// PT-BR: 4. SATURATION — gauge do recurso mais escasso
+const saturationGauge = meter.createObservableGauge('db_connection_pool_used_pct', {
+  description: 'DB connection pool utilization %',
+  unit: '%'
+})
+saturationGauge.addCallback((result) => {
+  // PT-BR: callback executado em scrape — lê estado atual do pool
+  result.observe(getConnectionPoolUsedPct(), { resource: 'db_pool', service: 'orders' })
+})
+
+export async function placeOrder(req: Request) {
+  const startMs = performance.now()
+  const dims = { endpoint: '/api/v1/orders', method: 'POST' }
+
+  // PT-BR: 2. Traffic — incrementar antes de processar
+  trafficCounter.add(1, dims)
+
+  return tracer.startActiveSpan('place_order', async (span) => {
+    try {
+      const order = await db.insertOrder(req.body)
+      // PT-BR: 1. Latency success — só após success confirmar
+      const durationMs = performance.now() - startMs
+      latencyHistogram.record(durationMs, { ...dims, result: 'success' })
+      return order
+    } catch (e) {
+      // PT-BR: 1. Latency error — separada da success
+      const durationMs = performance.now() - startMs
+      latencyHistogram.record(durationMs, { ...dims, result: 'error' })
+      // PT-BR: 3. Errors — counter por error.type (enum baixa cardinalidade)
+      errorsCounter.add(1, { ...dims, error_type: classify(e) })
+      throw e
+    } finally {
+      span.end()
+    }
+  })
+}
+
+// PT-BR: classifier — enum estável de 5-15 valores
+function classify(e: unknown): string {
+  if (e instanceof TimeoutError) return 'timeout'
+  if (e instanceof ValidationError) return 'validation'
+  if (e instanceof AuthError) return 'auth'
+  if (e instanceof RateLimitError) return 'rate_limit'
+  if (e instanceof DbError) return 'db'
+  return 'unknown'
+}
+```
+
+### Pattern: queries SQL para 4 signals em 1 dashboard
+
+```sql
+-- PT-BR: dashboard único — 4 golden signals últimos 60 minutos, por minuto
+select
+  date_trunc('minute', timestamp) as minute,
+  -- Traffic
+  count(*) as traffic_rpm,
+  -- Errors (por error.type)
+  count(*) filter (where result_success = false) as errors_total,
+  count(*) filter (where error_type = 'timeout') as errors_timeout,
+  count(*) filter (where error_type = 'rate_limit') as errors_rate_limit,
+  count(*) filter (where error_type = 'db') as errors_db,
+  -- Latency p50/p95/p99 — APENAS success
+  percentile_cont(0.50) within group (order by duration_ms)
+    filter (where result_success = true) as latency_p50_success,
+  percentile_cont(0.95) within group (order by duration_ms)
+    filter (where result_success = true) as latency_p95_success,
+  percentile_cont(0.99) within group (order by duration_ms)
+    filter (where result_success = true) as latency_p99_success,
+  -- Latency p99 — APENAS error (visibilidade de error path lentidão)
+  percentile_cont(0.99) within group (order by duration_ms)
+    filter (where result_success = false) as latency_p99_error,
+  -- Saturation (gauge max no minuto)
+  max(connection_pool_used_pct) as saturation_pool_max
+from observability.events
+where service = 'orders-api' and timestamp > now() - interval '60 minutes'
+group by minute
+order by minute desc;
+```
+
+### Pattern: black-box probe complementar (synthetic check)
+
+```ts
+// PT-BR: black-box monitoring — chamar serviço como cliente externo
+// Roda em CI ou serviço external (uptimerobot, datadog synthetics)
+async function blackBoxProbe(): Promise<{ ok: boolean; durationMs: number }> {
+  const startMs = Date.now()
+  const r = await fetch('https://api.example.com/api/v1/orders/probe', {
+    method: 'POST',
+    body: JSON.stringify({ probe: true, sku: 'TEST-001' }),
+    headers: { 'X-Probe': 'true' }
+  })
+  const durationMs = Date.now() - startMs
+  // PT-BR: validar resposta — não basta status 200
+  const body = await r.json()
+  const ok = r.status === 200 && body.order_id != null && durationMs < 1000
+  return { ok, durationMs }
+}
+
+// PT-BR: rodar a cada 30s; alerta se 3 consecutivos falham (debounce contra flake)
+```
+
+### Pattern: saturation por tipo de serviço
+
+| Tipo de serviço | Recurso mais escasso | Métrica de saturation |
+|---|---|---|
+| HTTP API stateless | Connection pool DB | `db_connection_pool_used_pct` |
+| API com cache | Memory do cache | `cache_memory_used_pct` |
+| Worker async | Queue depth | `queue_depth_messages` |
+| Edge Function | Concurrency limit Deno | `concurrent_executions_pct` |
+| DB | Tablespace ou WAL | `disk_used_pct`, `wal_lag_bytes` |
+| CPU-bound (encoder, ML) | Load average | `cpu_load_avg_5min` |
+| Network egress | Bandwidth | `egress_bytes_per_sec_pct` |
+
+## Anti-patterns
+
+### ANTI: mean latency
+
+```text
+ANTI: alerta/dashboard com avg(duration_ms) — long tail invisível.
+
+PROBLEMA: mean=50ms mas p99=5000ms = UX ruim invisível; cliente enterprise
+          (no p99) sofre sem nunca disparar alerta. Mean é puxado para baixo
+          por mass de requests rápidos; sinaliza "tudo ok" enquanto 1% dos
+          users espera 5s.
+
+CERTO: histogram com percentile_cont(0.99); alertar em p99 > target.
+       Reportar p50/p95/p99/p99.9 para ver formato da distribuição.
+```
+
+### ANTI: latência success+error misturadas
+
+```text
+ANTI: histogram(duration_ms) sem dimension result.
+
+PROBLEMA: falhas rápidas (HTTP 500 em 5ms quando timeout dispara cedo)
+          puxam mean/percentis para baixo; mascaram lentidão real de
+          requests bem-sucedidos. Dashboard mostra "p99=80ms" mas
+          successes reais são 800ms.
+
+CERTO: dimension {result: 'success'} vs {result: 'error'} SEMPRE separadas
+       em séries distintas. SLI/SLO computado APENAS sobre success path.
+```
+
+### ANTI: Errors com error.message como dimension
+
+```text
+ANTI: errorsCounter.add(1, { error_message: e.message })
+
+PROBLEMA: cada mensagem única é uma série temporal; cardinality explosion
+          (1M+ séries em horas se message contém timestamps/IDs/random);
+          time-series DB OOMs ou throttles; queries lentas/impossíveis;
+          custo de armazenamento explode.
+
+CERTO: enum error.type com 5-15 valores fixos (timeout, validation, auth,
+       rate_limit, db, provider_down, unknown); error.message em
+       log/span attribute (não métrica) para debug pontual.
+```
+
+### ANTI: monitoring causes não symptoms
+
+```text
+ANTI: alertar em "CPU > 80% / memory < 10% / threads > N"
+
+PROBLEMA: mistura "what" (sintoma user-facing) com "why" (causa interna);
+          falsos positivos (cron job legítimo dispara CPU);
+          falsos negativos (sistema lento sem CPU alta — saturação em
+          connection pool ou rede); on-call paginado por nada e
+          incidents reais passam silenciosos.
+
+CERTO: alertar em SLO burn rate sobre os 4 signals (event-based,
+       customer-impacting); usar CPU/memory como debug context em
+       white-box monitoring, não como alert source.
+```
+
+### ANTI: saturation genérica
+
+```text
+ANTI: copiar pattern de saturation de outro serviço sem identificar o
+      gargalo real.
+
+PROBLEMA: mede CPU em serviço onde gargalo é connection pool; mede memory
+          em serviço CPU-bound; saturation alerta nunca dispara antes do
+          incident; quando incident acontece, dashboard mostra "saturação
+          OK" e ninguém sabe explicar por quê.
+
+CERTO: identificar EXPLICITAMENTE o recurso mais escasso (DB pool? queue
+       depth? Deno concurrency? tablespace?) ANTES de instrumentar (ver
+       Pattern: saturation por tipo de serviço). Cada serviço tem 1 ou 2
+       gargalos reais — instrumentar esses, não copiar template.
+```
+
+### ANTI: black-box only (sem white-box)
+
+```text
+ANTI: só prober externo (synthetic check), sem instrumentação interna.
+
+PROBLEMA: sabe que "site offline" mas não sabe porquê; debug requer SSH
+          em prod / log dive sem instrumentation; MTTR cresce horas;
+          incidents repetem porque root cause nunca foi capturada.
+
+CERTO: black-box detecta UX impact (cliente real não consegue) + white-box
+       (4 signals) explica root cause. Os dois juntos: black-box dispara,
+       white-box mostra qual signal degradou (latency? errors? saturation?)
+       e em qual endpoint.
+```
+
+## Verificação
+
+Antes de marcar instrumentação como production-ready, validar:
+
+1. **Os 4 signals presentes** — Latency (histogram), Traffic (counter), Errors (counter por error.type), Saturation (gauge resource-specific)
+2. **Latency separada** — `result: 'success'` e `result: 'error'` em séries distintas
+3. **Histogram com bucketing exponencial** — não fixed buckets lineares
+4. **error.type é enum (5-15 valores)** — não `error.message` como dimension
+5. **Saturation tem o recurso certo identificado** — connection pool? queue depth? concurrency? CPU load?
+6. **Black-box probe complementar** — synthetic check do happy path principal a cada 30s
+7. **Dashboard de 4 signals** existe e é o **primeiro** lugar de debug em incident
+
+## Ver também
+
+- [`_shared-sre/glossary.md`](../_shared-sre/glossary.md) — termos canônicos golden signals, black-box, white-box, percentile
+- [`opentelemetry-standard`](../opentelemetry-standard/SKILL.md) (v1.9) — OTel SDK base, exporter, OTLP
+- [`structured-events`](../structured-events/SKILL.md) (v1.9) — wide events que alimentam SLI de Errors
+- [`event-based-slos`](../event-based-slos/SKILL.md) (v1.9) — SLO sobre Errors+Latency forma SLI canônico
+- [`burn-rate-alerting`](../burn-rate-alerting/SKILL.md) (v1.9) — alertar em SLO burn-rate, não em CPU
+- [`production-readiness-review`](../production-readiness-review/SKILL.md) — PRR axis "Instrumentation" exige 4 signals
+
+---
+
+*Material-fonte: Site Reliability Engineering — Beyer, Jones, Petoff, Murphy (Google/O'Reilly, 2016) — Cap 6: "Monitoring Distributed Systems" (Four Golden Signals).*