К основному содержанию
скилл CX Codex

observability-setup — скилл для Claude Code: трейсы, метрики и логи

Скилл observability-setup разворачивает в проекте трейсы OpenTelemetry, метрики Prometheus и структурные логи, добавляя к ним дашборд Grafana и черновики алертов.

MIT 289 установок ★ 64 обновлён 2026-01-12

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add patricio0312rev/skills --skill observability-setup -a claude-code
Открыть на GitHub

Что делает 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-code

2Вручную: положить файлы

~/.claude/skills/observability-setup/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/observability-setup/

По шагам, с командами для каждой платформы: Как установить скилл в 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

Похожие скиллы

Все скиллы по теме «DevOps и инфраструктура» →
monitoring-observability rohitg00 Скилл monitoring-observability для Claude Code добавляет в Node.js-сервис трассировки, метрики, структурированные логи и правила оповещений. Связывает сигналы приложения с дашбордами и SLO. CX Codex +1 ★ 2 858звёзд репо observability-and-instrumentation addyosmani Скилл observability-and-instrumentation для Claude Code учит ИИ добавлять в код логи, метрики, трейсинг и корреляционные ID. Включается при добавлении фич в продакшн для наблюдения за поведением системы. CX Codex +1 70 700установок oma-observability First Fluke Скилл oma-observability маршрутизирует задачи наблюдаемости, трейсинга и сигналов MELT+P между инструментами, помогает настроить OpenTelemetry и расследовать инциденты. CX Codex +1 ★ 1 472звёзд репо go-observability eduardo-sl Скилл go-observability для Go-сервисов в Claude Code: настраивает структурные логи на log/slog, трейсы и метрики через OpenTelemetry, алерты по SLO. Помогает видеть, что происходит в сервисе, уже работающем в продакшене. CX Codex +1 ★ 90звёзд репо implementing-observability ancoleman Скилл implementing-observability для Claude Code настраивает метрики, логи и трейсы через OpenTelemetry и показывает, как запустить Loki, Grafana, Tempo и Mimir у себя. По трейсу ищут ошибки между сервисами. CX Codex +1 1установок observability-sre majiayu000 Скилл observability-sre помогает настраивать наблюдаемость, SLO и процессы реагирования на инциденты. Подключайте его при работе с Prometheus, Grafana и OpenTelemetry. CX Codex +1 165установок

Из того же набора148

Весь набор →
prompt-template-builder Скилл prompt-template-builder для Claude Code собирает промпт из переиспользуемых частей: системной роли, переменных, формата ответа и примеров. Повторяющиеся запросы получают ответы в одном формате. CX Codex +1 291установок modal-drawer-system Скилл modal-drawer-system генерирует доступные модальные окна, боковые панели и нижние шторки на React с порталами, захватом фокуса и блокировкой прокрутки. CX Codex +1 291установок env-secrets-manager Скилл env-secrets-manager помогает разложить ключи и переменные окружения по местам: что коммитить в .env.example, что держать в AWS Secrets Manager, как проверить конфиг при старте. CX Codex +1 289установок api-security-hardener Скилл api-security-hardener добавляет в Express API проверку входа по схемам Zod, лимиты запросов на Redis и JWT-аутентификацию с ролями. CX Codex +1 289установок agent-orchestration-planner Скилл agent-orchestration-planner для проектирования многошаговых агентов: цикл с инструментами, повторные попытки, память и лимит расходов в виде готовых схем на Python. CX Codex +1 288установок react-server-components Помогает проектировать архитектуру React Server Components в Next.js App Router, разделять серверный и клиентский код, настраивать выборку данных и стриминг через Suspense. CX Codex +1 288установок github-actions-pipeline-creator Скилл github-actions-pipeline-creator для Claude Code собирает GitHub Actions workflow для линтинга, тестов, сборки и деплоя. Описывает CI с кэшем, матрицей и артефактами. CX Codex +1 288установок webhook-receiver-hardener Скилл webhook-receiver-hardener помогает проектировать защищённые эндпоинты для вебхуков. Защищает обработчики от подделки запросов, повторных доставок и сбоев сторонних сервисов. CX Codex +1 287установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой