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

implementing-observability — скилл Claude Code: что делает и установка

Скилл implementing-observability для Claude Code настраивает метрики, логи и трейсы через OpenTelemetry и показывает, как запустить Loki, Grafana, Tempo и Mimir у себя. По трейсу ищут ошибки между сервисами.

MIT 1 установок ★ 533 обновлён 2025-12-11

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

Что делает implementing-observability

Скилл ведёт агента по трём столпам наблюдаемости: метрики, логи, трейсы. Примеры на Python — счётчик http.server.requests, автотрейсинг FastAPI через FastAPIInstrumentor, структурные логи на structlog; для Rust есть отдельный пример с tracing, для Go и TypeScript названы SDK.

Дальше — стек LGTM: Loki под логи, Grafana под дашборды, Tempo под трейсы, Mimir под метрики, Grafana Alloy принимает OTLP на порту 4317. Поднять всё целиком можно из examples/lgtm-docker-compose/docker-compose.yml; детали по каждому куску разложены в references/lgtm-stack.md и references/opentelemetry-setup.md.

Связка логов с трейсами — главное, что стоит забрать отсюда: в каждую запись подставляются trace_id и span_id, поэтому строка с ошибкой сразу ведёт к трейсу. Для маленьких систем автор советует пропустить скилл: меньше 100 запросов в день закрывает консольный лог. Настройка структурного логирования расписана в references/structured-logging.md.

Какие задачи решает

  • развернуть метрики, логи и трейсы на одном SDK
  • связать запись в логе с конкретным трейсом
  • поднять локальный стек Grafana с Loki и Tempo
  • включить автотрейсинг HTTP-запросов в FastAPI
  • выбрать тип метрики под задачу: счётчик, гистограмма, датчик

Примеры запросов агенту

  • Добавь в сервис OpenTelemetry: метрики, трейсы и структурные логи через structlog.
  • Разверни LGTM-стек из examples/lgtm-docker-compose/docker-compose.yml и направь экспортёр на OTLP.
  • Пропиши в каждой строке лога trace_id и span_id, чтобы ошибка находилась в Tempo.

Как установить implementing-observability

1Через Skills CLI (Vercel)

npx skills add ancoleman/ai-design-components --skill implementing-observability -a claude-code

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

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

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

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об implementing-observability

Как установить implementing-observability в Claude Code?

Выполните npx skills add ancoleman/ai-design-components --skill implementing-observability -a claude-code. Скилл встанет в ~/.claude/skills/implementing-observability/SKILL.md.

Что делает implementing-observability?

Описывает, как собрать метрики, логи и трейсы на OpenTelemetry, и даёт примеры инструментирования сервисов. Отдельно разбирает стек LGTM и подстановку trace_id в логи.

Нужен ли скилл маленькому сервису?

Автор советует пропустить его, если система обрабатывает меньше 100 запросов в день: консольного лога хватает. Для нескольких распределённых сервисов он уже уместен.

Исходный текст

SKILL.md · MIT
---
name: implementing-observability
description: Monitoring, logging, and tracing implementation using OpenTelemetry as the unified standard. Use when building production systems requiring visibility into performance, errors, and behavior. Covers OpenTelemetry (metrics, logs, traces), Prometheus, Grafana, Loki, Jaeger, Tempo, structured logging (structlog, tracing, slog, pino), and alerting.
---

# Production Observability with OpenTelemetry

## Purpose

Implement production-grade observability using OpenTelemetry as the 2025 industry standard. Covers the three pillars (metrics, logs, traces), LGTM stack deployment, and critical log-trace correlation patterns.

## When to Use

Use when:
- Building production systems requiring visibility into performance and errors
- Debugging distributed systems with multiple services
- Setting up monitoring, logging, or tracing infrastructure
- Implementing structured logging with trace correlation
- Configuring alerting rules for production systems

Skip if:
- Building proof-of-concept without production deployment
- System has < 100 requests/day (console logging may suffice)

## The OpenTelemetry Standard (2025)

OpenTelemetry is the CNCF graduated project unifying observability:

```
┌────────────────────────────────────────────────────────┐
│          OpenTelemetry: The Unified Standard           │
├────────────────────────────────────────────────────────┤
│                                                         │
│  ONE SDK for ALL signals:                              │
│  ├── Metrics (Prometheus-compatible)                   │
│  ├── Logs (structured, correlated)                     │
│  ├── Traces (distributed, standardized)                │
│  └── Context (propagates across services)              │
│                                                         │
│  Language SDKs:                                         │
│  ├── Python: opentelemetry-api, opentelemetry-sdk      │
│  ├── Rust: opentelemetry, tracing-opentelemetry        │
│  ├── Go: go.opentelemetry.io/otel                      │
│  └── TypeScript: @opentelemetry/api                    │
│                                                         │
│  Export to ANY backend:                                │
│  ├── LGTM Stack (Loki, Grafana, Tempo, Mimir)          │
│  ├── Prometheus + Jaeger                               │
│  ├── Datadog, New Relic, Honeycomb (SaaS)              │
│  └── Custom backends via OTLP protocol                 │
│                                                         │
└────────────────────────────────────────────────────────┘
```

**Context7 Reference**: `/websites/opentelemetry_io` (Trust: High, Snippets: 5,888, Score: 85.9)

## The Three Pillars of Observability

### 1. Metrics (What is happening?)

Track system health and performance over time.

**Metric Types**: Counters (always increase), Gauges (up/down), Histograms (distributions), Summaries (percentiles).

**Brief Example (Python)**:
```python
from opentelemetry import metrics

meter = metrics.get_meter(__name__)
http_requests = meter.create_counter("http.server.requests")
http_requests.add(1, {"method": "GET", "status": 200})
```

### 2. Logs (What happened?)

Record discrete events with context.

**CRITICAL**: Always inject trace_id/span_id for log-trace correlation.

**Brief Example (Python + structlog)**:
```python
import structlog
from opentelemetry import trace

logger = structlog.get_logger()
span = trace.get_current_span()
ctx = span.get_span_context()

logger.info(
    "processing_request",
    trace_id=format(ctx.trace_id, '032x'),
    span_id=format(ctx.span_id, '016x'),
    user_id=user_id
)
```

**See**: `references/structured-logging.md` for complete configuration.

### 3. Traces (Where did time go?)

Track request flow across distributed services.

**Key Concepts**: Trace (end-to-end journey), Span (individual operation), Parent-Child (nested operations).

**Brief Example (Python + FastAPI)**:
```python
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor

app = FastAPI()
FastAPIInstrumentor.instrument_app(app)  # Auto-traces all HTTP requests
```

**See**: `references/opentelemetry-setup.md` for SDK installation by language.

## The LGTM Stack (Self-Hosted Observability)

LGTM = **L**oki (Logs) + **G**rafana (Visualization) + **T**empo (Traces) + **M**imir (Metrics)

```
┌────────────────────────────────────────────────────────┐
│                  LGTM Architecture                      │
├────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────────────────────────────────────────┐      │
│  │           Grafana Dashboard (Port 3000)      │      │
│  │  Unified UI for Logs, Metrics, Traces       │      │
│  └──────┬──────────────┬─────────────┬─────────┘      │
│         │              │             │                 │
│         ▼              ▼             ▼                 │
│  ┌──────────┐   ┌──────────┐  ┌──────────┐            │
│  │   Loki   │   │  Tempo   │  │  Mimir   │            │
│  │  (Logs)  │   │ (Traces) │  │(Metrics) │            │
│  │Port 3100 │   │Port 3200 │  │Port 9009 │            │
│  └────▲─────┘   └────▲─────┘  └────▲─────┘            │
│       │              │             │                   │
│       └──────────────┴─────────────┘                   │
│                      │                                 │
│              ┌───────▼────────┐                        │
│              │ Grafana Alloy  │                        │
│              │  (Collector)   │                        │
│              │  Port 4317/8   │ ← OTLP gRPC/HTTP       │
│              └───────▲────────┘                        │
│                      │                                 │
│         OpenTelemetry Instrumented Apps                │
│                                                         │
└────────────────────────────────────────────────────────┘
```

**Quick Start**: Run `examples/lgtm-docker-compose/docker-compose.yml` for a complete LGTM stack.

**See**: `references/lgtm-stack.md` for production deployment guide.

## Critical Pattern: Log-Trace Correlation

**The Problem**: Logs and traces live in separate systems. You see an error log but can't find the related trace.

**The Solution**: Inject `trace_id` and `span_id` into every log record.

### Python (structlog)

```python
import structlog
from opentelemetry import trace

logger = structlog.get_logger()
span = trace.get_current_span()
ctx = span.get_span_context()

logger.info(
    "request_processed",
    trace_id=format(ctx.trace_id, '032x'),  # 32-char hex
    span_id=format(ctx.span_id, '016x'),    # 16-char hex
    user_id=user_id
)
```

### Rust (tracing)

```rust
use tracing::{info, instrument};

#[instrument(fields(user_id = %user_id))]
async fn process_request(user_id: u64) -> Result<Response> {
    // trace_id/span_id automatically included
    info!(user_id = user_id, "processing request");
    Ok(result)
}
```

**See**: `references/trace-context.md` for Go and TypeScript patterns.

### Query in Grafana

```logql
{job="api-service"} |= "trace_id=4bf92f3577b34da6a3ce929d0e0e4736"
```

## Quick Setup Guide

### 1. Choose Your Stack

**Decision Tree**:
- **Greenfield**: OpenTelemetry SDK + LGTM Stack (self-hosted) or Grafana Cloud (managed)
- **Existing Prometheus**: Add Loki (logs) + Tempo (traces)
- **Kubernetes**: LGTM via Helm, Alloy DaemonSet
- **Zero-ops**: Managed SaaS (Grafana Cloud, Datadog, New Relic)

### 2. Install OpenTelemetry SDK

**Bootstrap Script**:
```bash
python scripts/setup_otel.py --language python --framework fastapi
```

**Manual (Python)**:
```bash
pip install opentelemetry-api opentelemetry-sdk \
    opentelemetry-instrumentation-fastapi \
    opentelemetry-exporter-otlp
```

**See**: `references/opentelemetry-setup.md` for Rust, Go, TypeScript installation.

### 3. Deploy LGTM Stack

**Docker Compose** (development):
```bash
cd examples/lgtm-docker-compose
docker-compose up -d
# Grafana: http://localhost:3000 (admin/admin)
# OTLP: localhost:4317 (gRPC), localhost:4318 (HTTP)
```

**See**: `references/lgtm-stack.md` for production Kubernetes deployment.

### 4. Configure Structured Logging

**See**: `references/structured-logging.md` for complete setup (Python, Rust, Go, TypeScript).

### 5. Set Up Alerting

**See**: `references/alerting-rules.md` for Prometheus and Loki alert patterns.

## Auto-Instrumentation

OpenTelemetry auto-instruments popular frameworks:

```python
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor

app = FastAPI()
FastAPIInstrumentor.instrument_app(app)  # Auto-trace all HTTP requests
```

**Supported**: FastAPI, Flask, Django, Express, Gin, Echo, Nest.js

**See**: `references/opentelemetry-setup.md` for framework-specific setup.

## Common Patterns

### Custom Spans

```python
from opentelemetry import trace

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("fetch_user_details") as span:
    span.set_attribute("user_id", user_id)
    user = await db.fetch_user(user_id)
    span.set_attribute("user_found", user is not None)
```

### Error Tracking

```python
from opentelemetry.trace import Status, StatusCode

with tracer.start_as_current_span("process_payment") as span:
    try:
        result = process_payment(amount, card_token)
        span.set_status(Status(StatusCode.OK))
    except PaymentError as e:
        span.set_status(Status(StatusCode.ERROR, str(e)))
        span.record_exception(e)
        raise
```

**See**: `references/trace-context.md` for background job tracing and context propagation.

## Validation and Testing

```bash
# Test log-trace correlation
# 1. Make request to your app
# 2. Copy trace_id from logs
# 3. Query in Grafana: {job="myapp"} |= "trace_id=<TRACE_ID>"

# Validate metrics
python scripts/validate_metrics.py
```

## Integration with Other Skills

- **Dashboards**: Embed Grafana panels, query Prometheus metrics
- **Feedback**: Alert routing (Slack, PagerDuty), notification UI
- **Data-Viz**: Time-series charts, trace waterfall, latency heatmaps

**See**: `examples/fastapi-otel/` for complete integration.

## Progressive Disclosure

**Setup Guides**:
- `references/opentelemetry-setup.md` - SDK installation (Python, Rust, Go, TypeScript)
- `references/structured-logging.md` - structlog, tracing, slog, pino configuration
- `references/lgtm-stack.md` - LGTM deployment (Docker, Kubernetes)
- `references/trace-context.md` - Log-trace correlation patterns
- `references/alerting-rules.md` - Prometheus and Loki alert templates

**Examples**:
- `examples/fastapi-otel/` - FastAPI + OpenTelemetry + LGTM
- `examples/axum-tracing/` - Rust Axum + tracing + LGTM
- `examples/lgtm-docker-compose/` - Production-ready LGTM stack

**Scripts**:
- `scripts/setup_otel.py` - Bootstrap OpenTelemetry SDK
- `scripts/generate_dashboards.py` - Generate Grafana dashboards
- `scripts/validate_metrics.py` - Validate metric naming

## Key Principles

1. **OpenTelemetry is THE standard** - Use OTel SDK, not vendor-specific SDKs
2. **Auto-instrumentation first** - Prefer auto over manual spans
3. **Always correlate logs and traces** - Inject trace_id/span_id into every log
4. **Use structured logging** - JSON format, consistent field names
5. **LGTM stack for self-hosting** - Production-ready open-source stack

## Common Pitfalls

**Don't**:
- Use vendor-specific SDKs (use OpenTelemetry)
- Log without trace_id/span_id context
- Manually instrument what auto-instrumentation covers
- Mix logging libraries (pick one: structlog, tracing, slog, pino)

**Do**:
- Start with auto-instrumentation
- Add manual spans only for business-critical operations
- Use semantic conventions for span attributes
- Export to OTLP (gRPC preferred over HTTP)
- Test locally with LGTM docker-compose before production

## Success Metrics

1. 100% of logs include trace_id when in request context
2. Mean time to resolution (MTTR) decreases by >50%
3. Developers use Grafana as first debugging tool
4. 80%+ of telemetry from auto-instrumentation
5. Alert noise < 5% false positives

© ancoleman · MIT · ancoleman/ai-design-components

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

Все скиллы по теме «DevOps и инфраструктура» →
logging-observability curiositech Скилл logging-observability настраивает структурированное логирование, сквозную трассировку через OpenTelemetry и пороги алертов. Помогает связать логи сервисов и убрать лишний шум из оповещений. CX Codex +1 152установок monitoring-observability rohitg00 Скилл monitoring-observability для Claude Code добавляет в Node.js-сервис трассировки, метрики, структурированные логи и правила оповещений. Связывает сигналы приложения с дашбордами и SLO. CX Codex +1 ★ 2 858звёзд репо opentelemetry grafana Скилл opentelemetry для Claude Code настраивает сбор метрик, логов и трейсов в Grafana Cloud или локальные Mimir, Loki и Tempo. Подключается при настройке OTLP-экспорта и отладке пропадающих спанов. CX Codex +1 6 900установок app-observability grafana Скилл app-observability ведёт агента по настройке Grafana Cloud: RED-метрики из OTel-трейсов, карты сервисов, браузерный RUM через Faro и наблюдение за вызовами LLM. CX Codex +1 4 800установок observability-sre majiayu000 Скилл observability-sre помогает настраивать наблюдаемость, SLO и процессы реагирования на инциденты. Подключайте его при работе с Prometheus, Grafana и OpenTelemetry. CX Codex +1 165установок setup-monitoring-observability davila7 Команда setup-monitoring-observability настраивает наблюдаемость проекта: метрики, логи, трассировку и оповещения. Укажите нужный тип или запросите полный стек. CX Codex +1 279установок

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

Весь набор →
building-ai-chat Скилл building-ai-chat для Claude Code помогает проектировать интерфейсы ИИ-чата с потоковыми ответами, управлением контекстом и вводом файлов, изображений или голоса. Задача — создать ассистента или чат-копилота. CX Codex +1 1установок architecting-networks Скилл architecting-networks помогает проектировать облачные сети: выбирать между плоской архитектурой, multi-VPC, hub-and-spoke и полносвязной топологией. Нужен при планировании VPC, сегментации сети или гибридной связности. CX Codex +1 1установок implementing-navigation Скилл implementing-navigation внедряет шаблоны навигации для React и маршрутизацию для бэкенда на Python с проверкой доступности по стандарту WCAG 2.1 AA. CX Codex +1 1установок security-hardening Скилл security-hardening проверяет и ужесточает настройки ОС, контейнеров, облака, сети и баз данных. Нужен перед production-развёртыванием, аудитом или проверкой уязвимостей. CX Codex +1 1установок ingesting-data Скилл ingesting-data для Claude Code содержит паттерны и примеры загрузки данных из облачных хранилищ, API, файлов и потоков в базы данных. CX Codex +1 1установок configuring-firewalls Скилл configuring-firewalls помогает настроить правила для Linux-файрволов, облачных групп безопасности и Kubernetes NetworkPolicies. Пригодится при открытии сервиса или ограничении сетевого доступа. CX Codex +1 1установок building-ci-pipelines Скилл building-ci-pipelines для Claude Code помогает создавать безопасные CI/CD-конвейеры с SLSA, кешированием и параллелизацией тестов в GitHub Actions, GitLab CI и Argo Workflows. CX Codex +1 1установок implementing-realtime-sync Скилл implementing-realtime-sync помогает выбрать и настроить транспорт для передачи данных в реальном времени: стриминг токенов LLM, чаты, совместное редактирование через CRDT и офлайн-синхронизацию. CX Codex +1 1установок

Ещё в каталоге

lingbot-map-3d-reconstruction reason-machines Скилл lingbot-map-3d-reconstruction для Claude Code, Codex, Cursor и других платформ ИИ-кодинга, который запускает модель LingBot-Map — feed-forward нейросеть для потоковой 3D-реконструкции сцен из видео и последовательностей изображений. CX Codex +1 426установок java-debugging официальный github Скилл java-debugging для GitHub Copilot ведёт агента по методике поиска причины бага в Java: воспроизвести, сузить, проверить гипотезу, подключить отладчик. Использует логи и логпоинты вместо брейкпоинтов. CX Codex +1 1установок design-system-creator curiositech Скилл design-system-creator для Claude Code собирает дизайн-системы: токены, CSS-архитектуру, библиотеку компонентов и документацию. Создаёт систему для нового UI и аудита существующих стилей. CX Codex +1 250установок mobile-security-coder sickn33 Скилл mobile-security-coder помогает писать защищённый код для iOS и Android: настраивает хранение данных, проверяет WebView и внедряет биометрию. CX Codex +1 3установок

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

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