observability-setup — скилл для Claude Code: трейсы, метрики и логи
Скилл observability-setup разворачивает в проекте трейсы OpenTelemetry, метрики Prometheus и структурные логи, добавляя к ним дашборд Grafana и черновики алертов.
MIT 289 установок ★ 64 обновлён 2026-01-12
npx skills add patricio0312rev/skills --skill observability-setup -a claude-codeЧто делает observability-setup
Скилл проводит по трём столпам наблюдаемости сразу: трейсы, метрики, логи. Внутри готовые куски кода на TypeScript — провайдер NodeTracerProvider с автоинструментацией HTTP, Express и Prisma, кастомные спаны с атрибутами и статусом, счётчики и гистограммы на prom-client. Для метрик есть middleware, который замеряет длительность запроса, и ручка /metrics для скрейпа.
Логи строятся на pino: поля сервиса и окружения, уровень из LOG_LEVEL. К метрикам приложен JSON дашборда Grafana с частотой запросов, долей ошибок, p95 задержки и активными соединениями. Отдельный файл — правила алертов Prometheus: рост доли ответов 5xx, p95 выше 2 секунд, доступность ниже 95%.
Инструментация в примерах завязана на Express и Prisma. В проекте на другом фреймворке или без этого ORM регистрации в registerInstrumentations придётся заменить своими. Финальный чек-лист проверяет, что трейсинг настроен, метрики отдаются, логи структурированы, а алерты описаны.
Какие задачи решает
- добавить трейсы OpenTelemetry в Node-сервис
- выставить метрики Prometheus и ручку
/metrics - перевести логи на структурный вывод через
pino - собрать дашборд Grafana из готовых панелей
- заготовить правила алертов на 5xx и p95
Примеры запросов агенту
- Настрой наблюдаемость для моего API на Express: трейсы OpenTelemetry, метрики Prometheus и структурные логи.
- Добавь в проект ручку
/metricsи middleware для замера длительности запросов. - Собери дашборд Grafana по метрике
http_requests_totalи правила алертов на 5xx.
Как установить observability-setup
1Через Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill observability-setup -a claude-code2Вручную: положить файлы
~/.claude/skills/observability-setup/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/observability-setup/
1Через Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill observability-setup -a codex2Вручную: положить файлы
.agents/skills/observability-setup/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill observability-setup -a cursor2Вручную: положить файлы
.cursor/skills/observability-setup/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install patricio0312rev/skills performance/observability-setup/SKILL.md2Вручную: положить файлы
.github/skills/observability-setup/SKILL.md1Через Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill observability-setup -a gemini-cli2Командой платформы
gemini skills install https://github.com/patricio0312rev/skills --path performance/observability-setupВручную: положить файлы
.devin/skills/observability-setup/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill observability-setup -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы об observability-setup
Как установить observability-setup в Claude Code?
Выполни npx skills add patricio0312rev/skills --skill observability-setup -a claude-code. Файл скилла появится по пути ~/.claude/skills/observability-setup/SKILL.md.
Что делает observability-setup?
Добавляет в сервис трейсы OpenTelemetry, метрики Prometheus и логи на pino, а вместе с ними дашборд Grafana и заготовки правил алертов.
Сработает ли скилл в проекте не на Express?
Примеры инструментации перечисляют HTTP, Express и Prisma. Для другого фреймворка или ORM эти регистрации в registerInstrumentations нужно заменить своими.
Исходный текст
SKILL.md · MIT
---
name: observability-setup
description: Implements comprehensive observability with OpenTelemetry tracing, Prometheus metrics, and structured logging. Includes instrumentation plans, sample dashboards, and alert candidates. Use for "observability", "monitoring", "tracing", or "metrics".
---
# Observability Setup
Implement the three pillars: Traces, Metrics, and Logs.
## OpenTelemetry Tracing
```typescript
// tracing.ts
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { Resource } from "@opentelemetry/resources";
import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
import { PrismaInstrumentation } from "@prisma/instrumentation";
const provider = new NodeTracerProvider({
resource: new Resource({
[SemanticResourceAttributes.SERVICE_NAME]: "my-api",
[SemanticResourceAttributes.SERVICE_VERSION]: "1.0.0",
}),
});
registerInstrumentations({
instrumentations: [
new HttpInstrumentation(),
new ExpressInstrumentation(),
new PrismaInstrumentation(),
],
});
provider.register();
// Custom spans
import { trace } from "@opentelemetry/api";
const tracer = trace.getTracer("my-app");
async function processOrder(orderId: string) {
const span = tracer.startSpan("processOrder");
span.setAttribute("order.id", orderId);
try {
await validateOrder(orderId);
await chargePayment(orderId);
await fulfillOrder(orderId);
span.setStatus({ code: 0 }); // OK
} catch (error) {
span.setStatus({ code: 2, message: error.message }); // ERROR
throw error;
} finally {
span.end();
}
}
```
## Prometheus Metrics
```typescript
// metrics.ts
import { Registry, Counter, Histogram, Gauge } from "prom-client";
const register = new Registry();
// HTTP request counter
export const httpRequestCounter = new Counter({
name: "http_requests_total",
help: "Total HTTP requests",
labelNames: ["method", "route", "status_code"],
registers: [register],
});
// HTTP request duration
export const httpRequestDuration = new Histogram({
name: "http_request_duration_seconds",
help: "HTTP request duration in seconds",
labelNames: ["method", "route", "status_code"],
buckets: [0.1, 0.5, 1, 2, 5, 10],
registers: [register],
});
// Active connections
export const activeConnections = new Gauge({
name: "active_connections",
help: "Number of active connections",
registers: [register],
});
// Business metrics
export const ordersProcessed = new Counter({
name: "orders_processed_total",
help: "Total orders processed",
labelNames: ["status"],
registers: [register],
});
// Middleware
app.use((req, res, next) => {
const start = Date.now();
res.on("finish", () => {
const duration = (Date.now() - start) / 1000;
const route = req.route?.path || "unknown";
httpRequestCounter.inc({
method: req.method,
route,
status_code: res.statusCode,
});
httpRequestDuration.observe(
{ method: req.method, route, status_code: res.statusCode },
duration
);
});
next();
});
// Metrics endpoint
app.get("/metrics", async (req, res) => {
res.set("Content-Type", register.contentType);
res.end(await register.metrics());
});
```
## Structured Logging
```typescript
// logger.ts
import pino from "pino";
export const logger = pino({
level: process.env.LOG_LEVEL || "info",
formatters: {
level: (label) => ({ level: label }),
},
base: {
service: "my-api",
environment: process.env.NODE_ENV,
},
});
// Usage
logger.info({ userId: "123", action: "login" }, "User logged in");
logger.error({ err: error, orderId: "456" }, "Order processing failed");
```
## Sample Dashboard (Grafana)
```json
{
"dashboard": {
"title": "API Overview",
"panels": [
{
"title": "Request Rate",
"targets": [{
"expr": "rate(http_requests_total[5m])"
}]
},
{
"title": "Error Rate",
"targets": [{
"expr": "rate(http_requests_total{status_code=~"5.."}[5m])"
}]
},
{
"title": "p95 Latency",
"targets": [{
"expr": "histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))"
}]
},
{
"title": "Active Connections",
"targets": [{
"expr": "active_connections"
}]
}
]
}
}
```
## Alert Candidates
```yaml
# alerts.yml
groups:
- name: api_alerts
interval: 30s
rules:
- alert: HighErrorRate
expr: rate(http_requests_total{status_code=~"5.."}[5m]) > 0.05
for: 5m
labels:
severity: critical
annotations:
summary: "High error rate detected"
- alert: HighLatency
expr: histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) > 2
for: 10m
labels:
severity: warning
annotations:
summary: "p95 latency above 2s"
- alert: LowAvailability
expr: rate(http_requests_total{status_code="200"}[5m]) / rate(http_requests_total[5m]) < 0.95
for: 5m
labels:
severity: critical
annotations:
summary: "Availability below 95%"
```
## Output Checklist
- [ ] OpenTelemetry tracing configured
- [ ] Prometheus metrics instrumented
- [ ] Structured logging implemented
- [ ] Sample dashboards created
- [ ] Alert rules defined
- [ ] Metrics endpoint exposed
- [ ] Instrumentation tested
ENDFILE
© patricio0312rev · MIT · patricio0312rev/skills