{"_id":"@elven-observability/observability-auditor-skill","_rev":"2-03ccbf7cb29e487766e1c2074a24d509","name":"@elven-observability/observability-auditor-skill","dist-tags":{"latest":"1.2.0"},"versions":{"1.0.0":{"name":"@elven-observability/observability-auditor-skill","version":"1.0.0","keywords":["mcp","model-context-protocol","grafana","grafana-mcp","observability","auditor","audit","prometheus","mimir","loki","tempo","pyroscope","clickhouse","elasticsearch","alerts","alerting","slo","burn-rate","error-budget","incident","incident-timeline","dashboard","opentelemetry","otel","skill","agent-skill","claude","claude-code","codex","anthropic","elven-works","elven-observability"],"author":{"url":"https://elven.works","name":"Elven Observability","email":"engineering@elven.works"},"license":"MIT","_id":"@elven-observability/observability-auditor-skill@1.0.0","maintainers":[{"name":"elven_observability","email":"elven.observability@elven.works"}],"homepage":"https://github.com/elven-observability/observability-auditor-skill#readme","bugs":{"url":"https://github.com/elven-observability/observability-auditor-skill/issues"},"bin":{"observability-auditor":"bin/mcp-observability-auditor.mjs","mcp-observability-auditor":"bin/mcp-observability-auditor.mjs"},"dist":{"shasum":"2d258882d8fd9ad9b4310f540adf84071af24190","tarball":"https://registry.npmjs.org/@elven-observability/observability-auditor-skill/-/observability-auditor-skill-1.0.0.tgz","fileCount":42,"integrity":"sha512-BMxWpIZMx26CjroMvLucqG68N5FyoVbQwGpePKoIypKFeInCVGsE7eb5BRsH7B3uA7Ox+cz1wzOCySDv8mOk5Q==","signatures":[{"sig":"MEYCIQCIo5tL67klAlk68wDGHYLYP5yzIgjLTooG/w/hYv7bKQIhAKXn8udasOI2QVbIiAM+PSDzGYWGtJr+/TBKRkEXojDB","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":244777},"type":"module","engines":{"node":">=18.0.0"},"scripts":{"lint":"node --check ./bin/mcp-observability-auditor.mjs && for f in skill/mcp-observability-auditor/scripts/*.mjs skill/mcp-observability-auditor/scripts/lib/*.mjs; do node --check $f || exit 1; done","test":"node --test","doctor":"node ./bin/mcp-observability-auditor.mjs doctor","pack:dry":"npm pack --dry-run","prepublishOnly":"npm run lint && npm test && npm run doctor"},"_npmUser":{"name":"elven_observability","email":"elven.observability@elven.works"},"repository":{"url":"git+https://github.com/elven-observability/observability-auditor-skill.git","type":"git"},"_npmVersion":"11.11.0","description":"Elite, read-only MCP/Grafana observability audit skill plus CLI — org/app/incident audits, alert and dashboard scoring (0–5 rubric), SLO and burn-rate recommendations, 2026-grade evidence ledger, two-layer client reports, OTel-stable semantic conventions,","directories":{},"_nodeVersion":"25.8.1","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/observability-auditor-skill_1.0.0_1778601902913_0.7584243742800441","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@elven-observability/observability-auditor-skill","version":"1.2.0","description":"Elite, read-only MCP/Grafana observability audit skill plus CLI — org/app/incident audits, alert and dashboard scoring (0–5 rubric), SLO and burn-rate recommendations, 2026-grade evidence ledger, two-layer client reports, OTel-stable semantic conventions,","type":"module","bin":{"observability-auditor":"bin/observability-auditor.mjs","mcp-observability-auditor":"bin/observability-auditor.mjs"},"scripts":{"doctor":"node ./bin/observability-auditor.mjs doctor","test":"node --test","lint":"node --check ./bin/observability-auditor.mjs && for f in skill/observability-auditor/scripts/*.mjs skill/observability-auditor/scripts/lib/*.mjs; do node --check $f || exit 1; done","pack:dry":"npm pack --dry-run","prepublishOnly":"npm run lint && npm test && npm run doctor"},"keywords":["mcp","model-context-protocol","grafana","grafana-mcp","observability","auditor","audit","prometheus","mimir","loki","tempo","pyroscope","clickhouse","elasticsearch","alerts","alerting","slo","burn-rate","error-budget","incident","incident-timeline","dashboard","opentelemetry","otel","skill","agent-skill","claude","claude-code","codex","anthropic","elven-works","elven-observability"],"author":{"name":"Elven Observability","email":"engineering@elven.works","url":"https://elven.works"},"license":"MIT","engines":{"node":">=18.0.0"},"homepage":"https://github.com/elven-observability/observability-auditor-skill#readme","repository":{"type":"git","url":"git+https://github.com/elven-observability/observability-auditor-skill.git"},"bugs":{"url":"https://github.com/elven-observability/observability-auditor-skill/issues"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"gitHead":"38a66cbd17db120d4453beb0ffff10f1cac4fde2","_id":"@elven-observability/observability-auditor-skill@1.2.0","_nodeVersion":"25.8.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-i2cW0fHp6cZ8/vJJiHSvXCxnra7efBaGvLDV5qyDVzbOpKG6cuCMi0zFRnObjQzGxJveVFA3TCTOeRJMQxv2fA==","shasum":"367f393322b69c045610e32b04528989a29e742a","tarball":"https://registry.npmjs.org/@elven-observability/observability-auditor-skill/-/observability-auditor-skill-1.2.0.tgz","fileCount":48,"unpackedSize":284148,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGk3M0wD/gWRajgfwnjCyJbWaOCRyFVVQG7IV3VXD2wSAiAHKpxudosLlVO8wqY8E6mMRlV8xq1xjArdnM+ExTRQCQ=="}]},"_npmUser":{"name":"elven_observability","email":"elven.observability@elven.works"},"directories":{},"maintainers":[{"name":"elven_observability","email":"elven.observability@elven.works"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/observability-auditor-skill_1.2.0_1778605071267_0.3174216484228989"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-12T16:05:02.821Z","modified":"2026-05-12T16:57:51.523Z","1.0.0":"2026-05-12T16:05:03.096Z","1.2.0":"2026-05-12T16:57:51.418Z"},"bugs":{"url":"https://github.com/elven-observability/observability-auditor-skill/issues"},"author":{"name":"Elven Observability","email":"engineering@elven.works","url":"https://elven.works"},"license":"MIT","homepage":"https://github.com/elven-observability/observability-auditor-skill#readme","keywords":["mcp","model-context-protocol","grafana","grafana-mcp","observability","auditor","audit","prometheus","mimir","loki","tempo","pyroscope","clickhouse","elasticsearch","alerts","alerting","slo","burn-rate","error-budget","incident","incident-timeline","dashboard","opentelemetry","otel","skill","agent-skill","claude","claude-code","codex","anthropic","elven-works","elven-observability"],"repository":{"type":"git","url":"git+https://github.com/elven-observability/observability-auditor-skill.git"},"description":"Elite, read-only MCP/Grafana observability audit skill plus CLI — org/app/incident audits, alert and dashboard scoring (0–5 rubric), SLO and burn-rate recommendations, 2026-grade evidence ledger, two-layer client reports, OTel-stable semantic conventions,","maintainers":[{"name":"elven_observability","email":"elven.observability@elven.works"}],"readme":"<div align=\"center\">\n\n# 🛰️ Observability Auditor Skill\n\n**Pergunte ao seu agente \"o que quebrou ontem no checkout?\" — receba um relatório executivo + evidência reproduzível, sem teatro.**\n\n[![npm](https://img.shields.io/npm/v/@elven-observability/observability-auditor-skill.svg?color=cb3837&label=npm)](https://www.npmjs.com/package/@elven-observability/observability-auditor-skill)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![Node ≥18](https://img.shields.io/badge/node-%E2%89%A518-brightgreen)](https://nodejs.org/)\n[![Tests](https://img.shields.io/badge/tests-40%20passing-brightgreen)](./tests)\n[![Skills Spec](https://img.shields.io/badge/agentskills.io-1.0-blueviolet)](https://agentskills.io/specification)\n[![Read-only by default](https://img.shields.io/badge/read--only-by%20default-success)](./skill/observability-auditor/references/mcp-safety.md)\n\n</div>\n\n---\n\n## TL;DR\n\nUma **Agent Skill** (Claude / Codex / qualquer agente que entenda MCP) + um **CLI Node sem dependências** que **audita stacks Grafana** (Mimir/Prometheus, Loki, Tempo, Pyroscope, ClickHouse, …) através de MCP, com regras de honestidade que recusam achismo:\n\n- 🔒 **Read-only por padrão** — nenhum write em alerta/dashboard/incidente sem autorização explícita.\n- 🧾 **Toda afirmação tem citação** — datasource, query, janela com timezone, observado, baseline, confiança, próxima validação.\n- ⚖️ **Escala de confiança 3 níveis** com counter-test exigido para \"high\".\n- 📜 **Redação automática** de Bearer/JWT/AWS/Stripe/cookies/CPF/CNPJ/PII.\n- 📈 **2026-ready**: OTel semconv estável, exemplars, multi-window burn-rate, error-budget policy.\n\n---\n\n## Veja em 30 segundos\n\nVocê pede:\n\n> 💬 *\"Cliente AcmeRetail (org 42, TZ America/Sao_Paulo). Por que o checkout caiu entre 14:00 e 16:30 ontem? Read-only.\"*\n\nA skill devolve:\n\n```text\nBetween 2026-05-10T14:00:00-03:00 and 2026-05-10T16:30:00-03:00 (America/Sao_Paulo),\ncheckout completion rate dropped 42% (from 87% to 50%).\n\nThe strongest evidence indicates Postgres connection-pool exhaustion on\ncheckout-db, aligned with traffic burst from marketing campaign.\nConfidence: high.\n\nTop 3 actions:\n1. Raise checkout-db max_connections 200→400  (owner: data-platform)\n2. Add 14.4×/6× burn-rate alert on Checkout-SLO 99.5%/28d  (owner: checkout-platform)\n3. Enable Tempo↔Mimir exemplars on http_server_request_duration_seconds (owner: platform-obs)\n\n[+ timeline table, evidence ledger, scored alerts/dashboards,\n   reproducible appendix with every query and deeplink]\n```\n\nCada linha cita **datasource + query + window + observado + baseline + confiança + next validation**. Sem isso, não vira finding.\n\n---\n\n## Instalação\n\n### 🤖 Como Agent Skill (no Claude Code / Codex)\n\n```bash\nnpx @elven-observability/observability-auditor-skill install-skill --dest ~/.claude/skills\n# ou para Codex / Agent SDK:\nnpx @elven-observability/observability-auditor-skill install-skill --dest ~/.agents/skills\n```\n\nPronto. Abra seu agente e mande \"audita o checkout do cliente X\" — ele já carrega a skill sozinho.\n\n### 💻 Como CLI\n\n```bash\nnpm install -g @elven-observability/observability-auditor-skill\nobservability-auditor welcome     # 👋 30-second intro\nobservability-auditor doctor      # ✓ check the install\n```\n\nOu sem instalar nada:\n\n```bash\nnpx @elven-observability/observability-auditor-skill welcome\n```\n\n> 💡 **Primeira vez?** O comando `welcome` resume tudo: as duas formas de usar (agente / CLI), comandos típicos, e um link para `examples/` (uma auditoria completa pronta para copiar e adaptar).\n\n---\n\n## Quickstart em 3 passos\n\n```bash\n# 1️⃣  Exporta os templates pra dentro do seu cliente/projeto\nobservability-auditor export-templates --dest ./meu-audit\n\n# 2️⃣  Preenche audit-context.yaml (cliente, org_id, timezone, janelas) e valida\ncd ./meu-audit\nobservability-auditor validate-context --context ./audit-context.yaml --strict\n\n# 3️⃣  No agente, executa o prompt master e deixa ele dirigir o MCP\nobservability-auditor prompt master \\\n  --client AcmeRetail --org-id 42 \\\n  --grafana-url https://grafana.acme.com --timezone America/Sao_Paulo\n```\n\nNo final você roda:\n\n```bash\nobservability-auditor render-report \\\n  --findings ./findings.json --context ./audit-context.yaml \\\n  --out ./audit-report.md\n```\n\nE entrega o **markdown executivo + técnico** pro cliente.\n\n---\n\n## Casos de uso típicos (prompts que funcionam)\n\n| Pergunta | O que a skill faz |\n|---|---|\n| *\"O que quebrou ontem no checkout do cliente X entre 14h e 16h?\"* | Normaliza janela em TZ, monta `bad/good/baseline`, walka traffic → errors → p95 → deps → biz, entrega timeline + leading hypothesis com counter-test. |\n| *\"Audita as alert rules do org 42 — quais ficam, quais ajusta, quais deleta.\"* | Rubrica 0–5 por alerta, threshold validado contra p50/p95/p99 do baseline, recomendação concreta (keep/tune/delete/split/replace). |\n| *\"Esses 6 dashboards do folder Checkout — quais ajudam num incidente, quais são teatro?\"* | Score por dashboard, flagga \"All\" defaults, counter-on-gauge, links faltando para logs/traces, recomendações por painel. |\n| *\"Recomenda SLOs para payment-svc, auth-svc e checkout-svc (200/30/5 rps).\"* | SLO inventory por serviço, multi-window burn-rate, **traffic-floor guard** para o serviço de baixa carga, error-budget policy 4-tiers. |\n| *\"Cria um alerta e silencia o de CPU enquanto investigo.\"* | **Recusa** sem autorização explícita echoando UIDs. Mostra o body proposto + diff + rollback antes de qualquer write. |\n\nTodos esses prompts estão em [`evals/evals.json`](./evals/evals.json) — você pode rodar contra o seu MCP real pra validar.\n\n---\n\n## O que vem dentro\n\n```\nobservability-auditor-skill/\n├── bin/                            CLI (`observability-auditor`, alias `mcp-observability-auditor`)\n├── evals/evals.json                6 prompts pt-BR realistas\n├── tests/                          40 testes node:test\n└── skill/observability-auditor/\n    ├── SKILL.md                    router enxuto (761 chars frontmatter, CSO-compliant)\n    ├── references/                 13 playbooks\n    │   ├── preflight-readonly.md\n    │   ├── mcp-safety.md           🆕 allowlist + protocolo de write\n    │   ├── redaction-patterns.md   🆕 catálogo regex (Bearer/JWT/AWS/CPF/…)\n    │   ├── org-discovery.md\n    │   ├── app-deep-dive.md\n    │   ├── incident-timeline.md\n    │   ├── alert-threshold-audit.md\n    │   ├── dashboard-audit.md\n    │   ├── slo-best-practices-2026.md  🆕 OTel-stable + exemplars + error-budget\n    │   ├── query-library.md            🆕 OTel semconv + HTTP client + DB + exemplars\n    │   ├── mcp-tool-catalog.md\n    │   ├── anti-patterns.md\n    │   └── report-template.md\n    ├── assets/\n    │   ├── manifest.json           tudo que o CLI expõe\n    │   ├── templates/              audit-context.yaml, audit-report.md, findings.json, evidence-ledger.yaml\n    │   ├── schemas/                🆕 4 JSON Schemas 2020-12\n    │   └── profiles/elven.yaml     🆕 defaults Elven (label model, datasources)\n    └── scripts/                    7 helpers determinísticos (zero deps)\n        ├── window_math.mjs         normaliza janela + baselines + slice grid\n        ├── validate_context.mjs    schema + lint\n        ├── score_alert.mjs         rubrica 0–5 com 5-step priority\n        ├── score_dashboard.mjs     idem\n        ├── render_report.mjs       findings.json → audit-report.md\n        ├── render_prompt.mjs       substitui [PLACEHOLDERS] em prompts\n        ├── redaction.mjs           🆕 aplica catálogo (--hash preserva distinct-count)\n        └── lib/\n            ├── yaml_subset.mjs     loader YAML zero-dep\n            └── schema_check.mjs    validator JSON Schema zero-dep\n```\n\n---\n\n## Cheat sheet — CLI\n\n<details>\n<summary><b>Clique para abrir a lista completa de comandos</b></summary>\n\n```text\nobservability-auditor [--version | --help]\nobservability-auditor list [--json]\nobservability-auditor playbooks | prompts | templates | schemas | profiles | scripts [--json]\nobservability-auditor show <id>                                # auto-resolve com hint\nobservability-auditor show playbook:<id> | prompt:<id> | profile:<id>    # explícito\nobservability-auditor prompt [id] [--client X] [--org-id X] [--timezone X] [--set KEY=VALUE …] [--output file]\nobservability-auditor export-templates [--dest dir] [--force] [--dry-run]\nobservability-auditor install-skill [--dest ~/.agents/skills] [--force] [--dry-run]\nobservability-auditor window --start <ISO> --end <ISO> [--tz <IANA>] [--slice <m>] [--json]\nobservability-auditor validate-context --context <file> [--strict] [--schema <file>] [--no-schema]\nobservability-auditor score-alert (--alert <file> | --batch <file>|- | --inline <json>)\nobservability-auditor score-dashboard (--dashboard <file> | --batch <file>|- | --inline <json>)\nobservability-auditor render-report --findings <file> [--context <file>] [--template <file>] [--out <file>]\nobservability-auditor render-prompt --id <prompt-id> [--set KEY=VALUE …] [--out <file>]\nobservability-auditor redact [--in <file>] [--out <file>] [--hash] [--keep-emails] [--keep-ips] [--extra <file>]\nobservability-auditor doctor [--strict]\n```\n\n**Exit codes** consistentes em todos os scripts: `0` ok · `1` usage error · `2` data/validation error. Todo script responde a `--version` e `--help`.\n\n</details>\n\n---\n\n## Honesty contract\n\nA skill se recusa a fazer estas coisas, mesmo sob pressão:\n\n- ❌ Inventar nomes de métricas / fabricar valores\n- ❌ Filtrar por label sem provar que ele existe (`list_*_label_names` primeiro, sempre)\n- ❌ Chamar `root cause` sem ≥2 sinais corroborantes + counter-test que rodou\n- ❌ Mutar produção sem autorização explícita echoando UID/escopo\n- ❌ Esconder cobertura faltando atrás de \"no issues found\"\n- ❌ Vazar token, cookie, JWT, AWS key, PII no relatório (catálogo de redação aplicado)\n\nEm compensação, **toda** afirmação no relatório vem com:\n\n```yaml\ndatasource: mimir-prod\ntool_or_query: histogram_quantile(0.95, sum by (le, service_name)(rate(...)))\ntime_range: 2026-05-10T14:00:00-03:00 → 2026-05-10T16:30:00-03:00\nfilters: { service_name: checkout, environment: prod }\nobserved: p95 = 850ms\nbaseline_or_comparator: same-hour-yesterday p95 = 12ms\nconfidence: high\ncounter_test: db p95 stayed flat → upstream caller (refutado: db saltou no mesmo minuto)\nnext_validation: <cheapest query that would falsify this finding>\n```\n\nDetalhes em [`references/anti-patterns.md`](./skill/observability-auditor/references/anti-patterns.md).\n\n---\n\n## Compatibilidade\n\n| Categoria | Compatível |\n|---|---|\n| **Agents** | Claude Code, Claude Desktop, Codex CLI, Claude Agent SDK, qualquer runtime que carregue `SKILL.md` |\n| **MCP servers** | `mcp-grafana`, `EOAdmin`, `ElvenGrafana`, `EO-MCP-WEVY`, qualquer Grafana-MCP-compatible |\n| **Backends** | Mimir, Prometheus, Loki, Tempo, Pyroscope, ClickHouse-OTel, Elasticsearch (Lucene/DSL), Grafana Incident, Grafana OnCall, Sift |\n| **Auto-instrumentation** | OTel SDK ≥1.27 (stable), Beyla, manual semconv |\n| **Node** | ≥18 (testado em 18 / 20 / 22) |\n\n---\n\n## Desenvolvimento\n\n```bash\ngit clone https://github.com/elven-observability/observability-auditor-skill\ncd observability-auditor-skill\nnpm install\nnpm test            # 36 tests, ~2s\nnpm run doctor      # valida o skill manifest inteiro\nnpm run lint        # node --check em cada .mjs\nnpm run pack:dry    # preview do tarball npm\n```\n\nQuer adicionar um playbook ou helper? Veja [CONTRIBUTING.md](./CONTRIBUTING.md). Resumo: zero deps, ESM, todos os scripts respondem a `--help` / `--version`, exit codes consistentes.\n\n---\n\n## Roadmap\n\n- [ ] **Adapters MCP** — adaptador first-class para `mcp-grafana`, Datadog MCP, New Relic MCP.\n- [ ] **`audit-context.json`** alternativo ao YAML (já suportado, mas precisa de doc dedicada).\n- [ ] **Web UI** opcional pra explorar `findings.json` (provavelmente em outro pacote).\n- [ ] **AI evals** automatizados rodando os 6 prompts em `evals/` contra um Grafana MCP mock.\n\nSugestões: abra uma issue ou um PR — o tom da skill é \"boring beats clever\".\n\n---\n\n## Licença\n\n[MIT](./LICENSE) © Elven Observability — feito com 💚 pelo time de plataforma.\n\nQuer usar fora da Elven? Vai em frente. Crédito é bem-vindo mas não obrigatório.\n","readmeFilename":"README.md"}