Наблюдаемость: логи, метрики, трейсы

Встраивает в фичу JSON-логи с ID запроса, метрики RED и USE с ограниченными метками, трейсы OpenTelemetry и алерты по симптомам с ранбуками, а затем проверяет саму телеметрию. Для случаев, когда фича, фоновая задача или интеграция идёт в прод.

DevOpsПак: Agent Skills (Addy Osmani)238 строкobservability-and-instrumentation
Автор
Источник
addyosmani/agent-skills/skills/observability-and-instrumentation @ 8c99fa3
Лицензия
MIT · Copyright (c) 2025 Addy Osmani

Об этом скилле

Что делает

Скилл заставляет агента писать телеметрию вместе с фичей, а не после первого инцидента. Начинается всё с двух-четырёх вопросов, которые задаст дежурный инженер; каждый лог, метрика и спан должны отвечать на один из них. Метрики показывают, что что-то сломалось, трейсы — где, логи — почему.

Логи — это JSON-события со стабильным именем и полями, а не строки со вставленными значениями, с единообразными уровнями и ID запроса в каждой строке. Если в один лог пишут планировщик, эндпоинт повтора и CLI, у каждого запуска есть ещё поле entryPoint. Метрики строятся по RED для эндпоинтов и внешних зависимостей и по USE для очередей и пулов, задержка — гистограммой с p95/p99, метки — только из небольших фиксированных наборов, никаких ID пользователей и полных URL. Трейсинг — автоинструментация OpenTelemetry плюс несколько ручных спанов, контекст передаётся и через очереди. Алерты срабатывают на то, что чувствуют пользователи, бывают двух уровней (page и ticket), и у каждого есть ссылка на короткий ранбук в docs/runbooks/. В конце агент проверяет саму телеметрию: вызывает ошибку на стейджинге, находит её по ID запроса и один раз прогоняет каждый новый алерт.

В папке — SKILL.md и лицензия. Чек-лист, на который ссылается скилл, ../../references/observability-checklist.md, лежит в репозитории автора и вместе со скиллом не ставится.

Когда включать и когда не надо

Для любой фичи, эндпоинта, фоновой задачи или интеграции, которая пойдёт в прод; на ревью PR с ретраями, очередями или вызовами между сервисами; после инцидента, который не удалось объяснить по имеющимся данным.

Не для сбоя, который идёт прямо сейчас, не для профилирования уже измеренной медлительности и не для критериев отката в день запуска — их скилл отдаёт другим скиллам, перечисленным ниже.

Как поставить и вызвать

Команда установки ниже кладёт SKILL.md и лицензию. Агент сам подхватывает скилл по описанию, когда вы добавляете логи, метрики, трейсинг или алерты. Вызвать вручную:

  • Claude Code: /observability-and-instrumentation или попросить скилл по имени.
  • Codex: $observability-and-instrumentation.
  • Cursor: наберите / в чате Agent и выберите observability-and-instrumentation.

Пример: /observability-and-instrumentation Добавь телеметрию в новый обработчик вебхуков: логи, RED-метрики и один алерт с ранбуком.

Скилл передаёт работу скиллам Отладка и восстановление после ошибок, Оптимизация производительности и Подготовка к запуску в прод, а правило «никаких секретов в логах» берёт из скилла Защита кода от уязвимостей.

Чем отличается от похожих

Разбор логов и Разбор инцидента начинают работу, когда что-то уже сломалось: первый ищет в имеющихся логах самый ранний сбой, второй ведёт живой инцидент до постмортема. Этот скилл заранее решает, что окажется в этих логах, метриках и алертах. Подготовка к запуску в прод перечисляет, за чем следить при выкатке, а сами сигналы строятся здесь. Скилл Ошибки и события в Sentry только читает через CLI ошибки, которые уже попали в Sentry, а этот решает, какую телеметрию код вообще будет отправлять.

Установка

Выполните одну команду — она сохранит SKILL.md и файлы, которые он использует, в папку скиллов агента. Claude Code и Codex подхватывают новый скилл без перезапуска; если скилл не появился, перезапустите агента.

Скилл написан на английском — агент поймёт его и ответит вам по-русски.

Claude Code — macOS, Linux
curl -fsSL --create-dirs -o ~/.claude/skills/observability-and-instrumentation/SKILL.md https://anymodel.org/en/skills/addy-osmani/observability-and-instrumentation/SKILL.md -o ~/.claude/skills/observability-and-instrumentation/LICENSE https://anymodel.org/en/skills/addy-osmani/observability-and-instrumentation/LICENSE
Codex, Cursor — macOS, Linux
curl -fsSL --create-dirs -o ~/.agents/skills/observability-and-instrumentation/SKILL.md https://anymodel.org/en/skills/addy-osmani/observability-and-instrumentation/SKILL.md -o ~/.agents/skills/observability-and-instrumentation/LICENSE https://anymodel.org/en/skills/addy-osmani/observability-and-instrumentation/LICENSE
Claude Code — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE') { $p = Join-Path "$HOME\.claude\skills\observability-and-instrumentation" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/addy-osmani/observability-and-instrumentation/$f" -UseBasicParsing -OutFile $p }
Codex, Cursor — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE') { $p = Join-Path "$HOME\.agents\skills\observability-and-instrumentation" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/addy-osmani/observability-and-instrumentation/$f" -UseBasicParsing -OutFile $p }

Другой агент: сохраните файл в его папку скиллов или дайте ему ссылку на файл: https://anymodel.org/en/skills/addy-osmani/observability-and-instrumentation/SKILL.md

SKILL.md

Исходник

Observability and Instrumentation

Overview

Code you can't observe is code you can't operate. Observability is the ability to answer "what is the system doing and why?" from the outside, using the telemetry the code emits. Instrumentation is not a post-launch add-on — it's written alongside the feature, the same way tests are. If a feature ships without telemetry, the first user-reported bug becomes archaeology instead of a query.

When to Use

  • Building any feature that will run in production
  • Adding a new service, endpoint, background job, or external integration
  • A production incident took too long to diagnose ("we couldn't tell what happened")
  • Setting up or reviewing alerting rules
  • Reviewing a PR that adds I/O, retries, queues, or cross-service calls

NOT for:

  • Diagnosing a failure happening right now — use the debugging-and-error-recovery skill (observability is what makes that skill fast next time)
  • Profiling and optimizing measured slowness — use the performance-optimization skill
  • Launch-day monitoring checklists and rollback triggers — see the shipping-and-launch skill; this skill covers the instrumentation that feeds them

Process

1. Define "working" before instrumenting

Telemetry without a question is noise. Before adding any instrumentation, write down 2–4 questions an on-call engineer will ask about this feature:

FEATURE: checkout payment retry
QUESTIONS ON-CALL WILL ASK:
1. What fraction of payments succeed on first attempt vs after retry?
2. When a payment fails permanently, why? (provider error? timeout? validation?)
3. Is the payment provider slower than usual?
→ Every signal below must help answer one of these.

If you can't name the questions, you're not ready to instrument — you'll log everything and learn nothing.

2. Pick the right signal for each question

Signal Answers Cost profile Example
Structured log "What happened in this specific case?" Per-event; grows with traffic payment_failed with provider error code
Metric "How often / how fast, in aggregate?" Fixed per series; cheap to query p99 latency of provider calls
Trace "Where did time go across services?" Per-request; usually sampled One slow checkout, broken down by hop

Rule of thumb: metrics tell you that something is wrong, traces tell you where, logs tell you why.

3. Structured logging

Log events, not prose. Every log line is a JSON object with a stable event name and machine-readable fields:

// BAD: string interpolation — unqueryable, inconsistent
logger.info(`Payment ${id} failed for user ${userId} after ${n} retries`);

// GOOD: stable event name + structured fields
logger.warn({
  event: 'payment_failed',
  paymentId: id,
  provider: 'stripe',
  errorCode: err.code,
  attempt: n,
}, 'payment failed');

Log levels — use them consistently:

Level Meaning On-call action
error Invariant broken; someone may need to act Investigate
warn Degraded but handled (retry succeeded, fallback used) Watch for trends
info Significant business event (order placed, job finished) None
debug Diagnostic detail Off in production by default

Correlation IDs are mandatory. Generate (or accept) a request ID at the system boundary and attach it to every log line, span, and outbound call. Without it, you cannot reconstruct a single request from interleaved logs:

// Express: child logger per request, ID propagated downstream
app.use((req, res, next) => {
  req.id = req.headers['x-request-id'] ?? crypto.randomUUID();
  req.log = logger.child({ requestId: req.id });
  res.setHeader('x-request-id', req.id);
  next();
});

When several entry points write to one log, name the entry point. A correlation ID identifies a run; it does not say which code path started it. The same job reached by a scheduler, by a replay endpoint, and by a manual CLI run produces interchangeable lines in one sink, so attributing a line falls back to elimination — cross-reading the scheduler's history, the process table, a deploy log — and that argument holds only as long as those external records happen to still exist. Stamp the entry point where the run starts, next to the correlation ID, and propagate both the same way:

// One helper for every entry point: the run's own logger carries both fields.
// `entryPoint`, not `source` — ECS reserves `source.*` for network fields.
export const runLog = (entryPoint: 'scheduler' | 'replay_endpoint' | 'cli', runId: string) =>
  logger.child({ entryPoint, requestId: runId });

// scheduler tick        -> runLog('scheduler', crypto.randomUUID())
// POST /jobs/:id/replay -> runLog('replay_endpoint', req.id)
// CLI invocation        -> runLog('cli', process.env.RUN_ID ?? crypto.randomUUID())

Both fields have to cross the same boundaries as the correlation ID — queue metadata, HTTP headers — or a worker re-derives the entry point and guesses. A field that merely correlates with an entry point is a hint, not an attribution: anything that can invoke the job can reproduce it.

Never log secrets, tokens, passwords, or full PII. This is a hard rule from the security-and-hardening skill — telemetry pipelines are a classic data-leak path. Allowlist fields; don't log whole request bodies.

4. Metrics

For request-driven services, instrument RED on every endpoint and every external dependency: Rate (requests/sec), Errors (failure rate), Duration (latency histogram, not average). For resources (queues, pools, hosts), use USE: Utilization, Saturation, Errors.

As with tracing, the vendor-neutral path is the OpenTelemetry metrics API (same SDK and context as step 5). The example below uses Prometheus' prom-client — one common backend choice, not the only one; the RED/USE and cardinality rules are identical either way.

import { Histogram } from 'prom-client';

const httpDuration = new Histogram({
  name: 'http_request_duration_seconds',
  help: 'HTTP request duration',
  labelNames: ['method', 'route', 'status_class'],  // '2xx', not '200'
  buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
});

Cardinality is the failure mode. Every unique label combination is a separate time series. Labels must come from small, fixed sets (route template, status class, provider name). Never use user IDs, raw URLs, error messages, or other unbounded values as labels — that belongs in logs and traces.

OK as label:    route="/api/tasks/:id"   status_class="5xx"   provider="stripe"
NEVER a label:  user_id, email, request_id, full URL, error message text

Track averages never, percentiles always: an average hides the 1% of users having a terrible time. Use histograms and read p50/p95/p99.

5. Distributed tracing

Use OpenTelemetry — it's the vendor-neutral standard, and auto-instrumentation covers HTTP, gRPC, and common DB clients with near-zero code:

// tracing.ts — must be imported before anything else
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';

const sdk = new NodeSDK({
  serviceName: 'checkout-service',
  instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();

Add manual spans only around meaningful internal units of work (e.g., applyDiscounts, chargeProvider) and attach the attributes on-call will filter by. Propagate context across every async boundary — HTTP headers, queue message metadata — or the trace dies at the gap. Sample head-based at a low rate by default; keep 100% of errors if your backend supports tail sampling.

6. Alerting

Alert on symptoms users feel, not on causes:

SYMPTOM (page-worthy):           CAUSE (dashboard, not a page):
error rate > 1% for 5 min        CPU at 85%
p99 latency > 2s                 one pod restarted
queue age > 10 min               disk at 70%

Cause-based alerts fire when nothing is wrong and miss failures you didn't predict. Symptom-based alerts fire exactly when users are hurt, regardless of the cause.

Rules for every alert you create:

  1. It must be actionable. If the response is "ignore it, it self-heals", delete the alert.
  2. It links to a runbook — even three lines: what it means, first query to run, escalation path.
  3. It has a threshold and duration justified by the SLO or by historical data, not by a guess.
  4. Use two severities only: page (user-facing, act now) and ticket (degradation, act this week). A third tier becomes noise that trains people to ignore everything.
Writing Runbooks

Rule 2 above requires every alert to link to a runbook. A runbook's job is to answer three questions without requiring the reader to think: what is happening, what to check first, and who to call if that doesn't resolve it. Store in docs/runbooks/ named after the alert.

Minimum viable runbook (three lines):

# Runbook: High Error Rate on /api/tasks
**Means:** DB connection pool likely exhausted, or a bad deploy.
**First check:** `SELECT count(*) FROM pg_stat_activity WHERE backend_type = 'client backend';`
  — if count > pool limit, see Step 2. (Swap in the equivalent for your database.)
**Escalate to:** #db-oncall or engineering on-call rotation.

When to expand beyond three lines: add steps only when the first check alone isn't enough to decide. A five-step runbook that covers the three most common causes is better than a twenty-step document that covers every edge case and gets skimmed.

Keep runbooks current. Update the runbook as part of closing every incident it was used in — a stale runbook builds false confidence. If a step was wrong or missing, fix it before marking the incident resolved.

7. Verify the telemetry itself

Instrumentation is code; it can be wrong. Before calling the work done, trigger the paths and look at the actual output:

  • Force an error in staging → find it in the logs by requestId, confirm fields are structured (not [object Object])
  • Send test traffic → confirm metric series appear with the expected labels and sane values
  • Follow one request across services in the tracing UI → no broken spans
  • Fire each new alert once (lower the threshold temporarily) → confirm it reaches the right channel and the runbook link works

Common Rationalizations

Rationalization Reality
"I'll add logging after it works" "After" becomes "after the first incident", which is the most expensive moment to discover you're blind. Instrument as you build.
"More logs = more observability" Unstructured noise makes incidents slower, not faster. Three queryable events beat three hundred prose lines.
"console.log is fine for now" Unstructured output can't be filtered, correlated, or alerted on. The structured logger costs five extra minutes once.
"We can just look at the dashboards when something breaks" Dashboards built without defined questions show you everything except the answer. Start from on-call questions.
"Alert on everything important, we'll tune later" A noisy pager trains people to ignore it. The tuning never happens; the missed real page does.
"User ID as a metric label makes debugging easier" It also makes your metrics backend fall over. High-cardinality lookups belong in logs and traces.
"Tracing is overkill for our two services" Two services already means cross-service latency questions logs can't answer. Auto-instrumentation makes the cost trivial.

Red Flags

  • A feature PR with retries, queues, or external calls and zero new telemetry
  • Log lines built by string interpolation instead of structured fields
  • No correlation/request ID — each log line is an orphan
  • One log stream fed by a scheduler, a webhook, and manual runs, with no field naming which one produced the line
  • Metrics labeled with user IDs, raw URLs, or error message text (cardinality bomb)
  • Latency tracked as an average with no percentiles
  • Alerts that fire daily and get acknowledged without action
  • Alerts on causes (CPU, memory) paging humans while user-facing error rate is unmonitored
  • Secrets, tokens, or full request bodies appearing in logs
  • "It works on my machine" as the only evidence a production feature is healthy

Verification

After instrumenting a feature, confirm:

  • The on-call questions for this feature are written down, and each signal maps to one
  • All log output is structured (JSON), with stable event names and a correlation ID on every line
  • Every log sink written by more than one entry point carries an entry-point field, set where the run starts and propagated with the correlation ID rather than inferred downstream
  • No secrets, tokens, or unredacted PII in any log line (spot-check actual output)
  • RED metrics exist for every new endpoint and every external dependency, with bounded label sets
  • Latency is a histogram; p95/p99 are queryable
  • A single request can be followed end-to-end in the tracing UI without broken spans
  • Every new alert is symptom-based, has a runbook link, and was test-fired once
  • An induced failure in staging was located via telemetry alone, without reading the source

For the at-a-glance version of this list, including the pre-launch instrumentation gate, see ../../references/observability-checklist.md.

Подключить через AnyModel API

Скилл работает на той модели, которую использует агент. Подключите Claude Code, Codex или Cursor к AnyModel и запускайте его на Claude, GPT, Gemini и других моделях по одному ключу — оплата за токены, без подписки.

Ещё из пака Agent Skills (Addy Osmani)

Доступность: аудит и исправления по WCAG 2.2

Делает аудит готового интерфейса по WCAG 2.2 AA: axe-core и pa11y, затем клавиатура, экранный чтец и контраст, и исправляет подтверждённые нарушения, начиная с семантического HTML. Для случаев, когда страницу нужно проверить на доступность перед выкладкой.

Проектирование API и интерфейсов

Делает проект API и интерфейсов модулей от контракта: одна форма ошибок, проверка на границах, только добавляющие изменения, пагинация и ключи идемпотентности. Для случаев, когда проектируются эндпоинты или меняется публичный интерфейс.

Тесты в браузере через Chrome DevTools MCP

Делает проверку изменений в настоящем Chrome через MCP-сервер Chrome DevTools: скриншоты, DOM, консоль, сеть и трейсы, а содержимое страницы считает недоверенным. Для случаев, когда разрабатывается или отлаживается что-то в браузере.

Настройка CI/CD

Делает пайплайн CI/CD с закреплённым порядком проверок от линтера до размера бандла, примерами на GitHub Actions, превью-деплоями, фича-флагами, поэтапной выкаткой и откатом. Для случаев, когда настраивается или чинится сборка и деплой.

Код-ревью по нескольким осям

Делает ревью изменения по пяти осям — корректность, читаемость, архитектура, безопасность, производительность, — проверяет тесты мутацией условия и помечает находки по уровню. Для случаев, когда ветку, пул-реквест или дифф пора сливать.

Упрощение кода

Делает работающий код проще для чтения, не меняя поведения: сначала выясняет, зачем он такой, потом упрощает по одному шагу с тестами после каждого. Для случаев, когда код работает, но читается тяжелее, чем мог бы.

Планка качества как контракт

Делает из планки качества проекта контракт: после короткого опроса записывает числа в CONSTRAINTS.md, привязывает их к инструментам и ловит в диффе пропущенные тесты и ослабленные пороги. Для случаев, когда планка нигде не записана.

Настройка контекста агента

Делает настройку контекста агента: шаблон файла правил, загрузка только нужных файлов и разделов спецификации, чистка длинной сессии и безопасный момент начать новую. Для случаев, когда начинается сессия или ответы агента портятся.

Отладка и восстановление после ошибок

Останавливает новую работу при поломке, воспроизводит и сужает сбой, чинит первопричину, добавляет регрессионный тест и не выполняет команды из текста ошибок. Для случаев, когда упал тест, сломалась сборка или перестало работать то, что работало.

Вывод из эксплуатации и миграции

Выводит из эксплуатации старые системы, API и фичи: решает, стоит ли, проверяет замену, переводит потребителей по одному, удаляет код при нулевом использовании, схему меняет через expand/contract. Для случаев, когда старое заменяют или переименовывают колонку.

Документация и ADR

Записывает решения в ADR по формату проекта, документирует API, README и changelog с упором на «почему», по истории git проверяет, не устарел ли документ. Для случаев, когда принято дорогое решение, меняется публичный API или документы разошлись с кодом.

Разработка через сомнение

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

Фронтенд-интерфейсы для продакшена

Строит компоненты и страницы на дизайн-системе проекта: композиция, простое состояние, WCAG 2.1 AA, mobile-first, состояния загрузки, пустого списка и ошибки, без ИИ-эстетики. Для случаев, когда создают или меняют пользовательский интерфейс.

Git-процесс и версионирование

Ведёт работу в git атомарными коммитами в коротких ветках: сообщения с типом, проверка секретов и тестов перед коммитом, worktree для параллельных агентов, semver, теги и changelog. Для случаев, когда коммитят, ветвятся, открывают PR или выпускают релиз.

Доработка сырой идеи

Доводит сырую идею за три фазы: уточняющие вопросы и пять-восемь вариантов, два-три направления с проверкой ценности, реализуемости и допущений, затем одностраничник с MVP и списком «Чего не делаем». Для случаев, когда идея расплывчата или план надо проверить.

Реализация тонкими срезами

Строит изменения тонкими срезами — вертикально, от контракта или от риска, — тестируя и коммитя каждый перед следующим, в рамках задачи, с feature-флагами и откатываемыми шагами. Для случаев, когда правка затрагивает несколько файлов или задача велика.

Интервью о задаче

Расспрашивает по одному вопросу с догадкой об ответе и оценкой уверенности, пока агент не сможет предсказать ответы, и до спецификации и кода получает подтверждённое намерение. Для случаев, когда в запросе неясно, для кого, зачем и что считать успехом.

Оптимизация производительности

Ускоряет приложение по замерам: снимает базу, исправляет одно доказанное узкое место, перемеряет с учётом разброса и откатывает нейтральные правки; есть примеры для N+1, индексов, кэша и бандла. Для случаев, когда что-то тормозит или не влезает в бюджет.

Разбивка работы на задачи

Разбивает спецификацию на небольшие вертикальные задачи с критериями приёмки, проверками, размером, порядком и контрольными точками — в tasks/todo.md или в трекер. Для случаев, когда спецификация готова, а работа слишком велика для одного захода.

Защита кода от уязвимостей

Защищает код: модель угроз, правила «всегда», «сначала спросить», «никогда» и паттерны против инъекций, XSS, обхода доступа, SSRF, утечки секретов и опасных зависимостей. Для случаев, когда код принимает ввод, ведёт вход, хранит личные данные или зовёт LLM.

Подготовка к запуску в прод

Готовит запуск в прод: чек-лист перед выкаткой, фича-флаг с этапами от 5% до 100%, пороги для продолжения или отката, бюджет ошибок, письменный план отката и проверки в первый час. Для случаев, когда фича или крупное изменение вот-вот уйдёт в прод.

Код по официальной документации

Пишет код под фреймворк по официальной документации: берёт точные версии из файла зависимостей, открывает нужную страницу, следует описанному API и даёт ссылки, помечая непроверенное. Для случаев, когда код должен соответствовать версии фреймворка в проекте.

Спецификация и PRD до начала работы

Пишет спецификацию до кода: выявляет допущения, описывает цель, команды, структуру, стиль, тесты и границы, а план, задачи и код начинает только после одобрения; есть карты модулей и дельта-спецификации. Для случаев, когда у новой фичи размытые требования.

TDD: красный, зелёный, рефакторинг

Ведёт изменения по циклу «красный, зелёный, рефакторинг»: находит команды тестов проекта, пишет падающий тест первым, воспроизводит каждый баг тестом до исправления и задаёт правила для моков и имён. Для случаев, когда добавляется логика или чинится баг.