Konfiguracja obserwowalności z CLI

Jest 2 w nocy i PagerDuty uruchamia alarm. Alert mówi “wysoki wskaźnik błędów na API.” Otwierasz Grafanę i widzisz skok, ale dashboard pokazuje tylko kody statusu HTTP — żadnych trace ID, żadnej korelacji logów, żadnego sposobu na ustalenie, który endpoint lub która usługa downstream jest winowajcą. Logujesz się przez SSH na serwer, grepujesz przez niestrukturalne logi i spędzasz czterdzieści minut na zawężeniu problemu do timeoutu w API dostawcy płatności. Naprawa trwa dwie minuty. Śledztwo trwało dwadzieścia razy dłużej, ponieważ obserwowalność była dodatkiem na końcu.

Czego się nauczysz

• Workflow Claude Code do generowania instrumentacji OpenTelemetry, strukturalnego logowania i reguł alertów Prometheus z istniejącego kodu
• Prompty do skopiowania tworzące JSON dashboardów Grafana, konfiguracje routingu Alertmanager i definicje SLO
• Systematyczne podejście do dodawania obserwowalności po fakcie bez przepisywania aplikacji

Bootstrapping OpenTelemetry w istniejącej aplikacji

Najtrudniejsza część obserwowalności to początkowa konfiguracja. Masz aplikację Node.js (lub Python, lub Go) już na produkcji, a dodanie tracingu wydaje się jak operacja na działającym pacjencie. Claude Code sprawia, że jest to wykonalne, ponieważ potrafi przeczytać twój faktyczny punkt wejścia aplikacji i stworzyć instrumentację, która pasuje.

Wskazówka

Prompt do skopiowania — bootstrap OpenTelemetry:

Read my application's entry point and main middleware stack. Generate an OpenTelemetry setup file (telemetry.ts) that: 1) auto-instruments HTTP, Express/Fastify, and database calls, 2) exports traces to an OTLP endpoint configured via OTEL_EXPORTER_OTLP_ENDPOINT env var, 3) adds service.name and deployment.environment resource attributes, 4) disables noisy fs instrumentation, 5) must be imported before any other module in the entry point. Also update my entry point to import this file first.

Claude Code czyta twój package.json, aby określić framework (Express, Fastify, Hono itp.) i bibliotekę bazodanową (Prisma, Drizzle, pg, Mongoose), a następnie generuje dokładnie te pakiety instrumentacji, których potrzebujesz. Koniec z zgadywaniem, który pakiet @opentelemetry/instrumentation-* obsługuje twój stack.

Po wygenerowaniu konfiguracji zweryfikuj, że trace’y płyną:

# Start the OTEL collector locally
docker run -p 4318:4318 otel/opentelemetry-collector-contrib

# Start your app with telemetry
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 node -r ./telemetry.js dist/index.js

# Hit an endpoint and check the collector logs
curl http://localhost:3000/api/health

Następnie iteruj z Claude Code:

The traces are showing up but database queries don't include the SQL statement. Update the instrumentation config to capture the db.statement attribute for Prisma queries, but redact any parameter values to avoid leaking PII.

Strukturalne logowanie, które naprawdę pomaga

Niestrukturalne logi to szum. Strukturalne logi to dane. Claude Code może retrofitować strukturalne logowanie do istniejącego kodu w jednej sesji.

Wskazówka

Prompt do skopiowania — retrofit strukturalnego logowania:

Our app uses console.log everywhere for logging. Replace all console.log/warn/error calls with a structured logger (use pino for Node.js). The logger should: 1) output JSON in production, pretty-print in development, 2) include a correlationId from the request headers or generate one, 3) attach the active OpenTelemetry traceId and spanId to every log entry, 4) mask fields named password, token, secret, or creditCard in log output, 5) support log levels via LOG_LEVEL env var defaulting to info. Create the logger module and update all existing console calls.

To duża zmiana, a Claude Code obsługuje ją metodycznie. Najpierw tworzy moduł loggera, a następnie przechodzi przez każdy plik zastępując wywołania console.log. Kluczową korzyścią jest korelacja trace’ów — każdy wpis logu może być połączony z rozproszonym trace’em, co zamienia debugowanie oparte na grepie w przeszukiwalną, skorelowaną investigację.

Po wprowadzeniu zmian przez Claude, zweryfikuj szybkim sprawdzeniem:

Run a request through the app and show me a sample log entry to confirm the traceId and correlationId are present.

Metryki Prometheus i reguły alertów

Metryki bez alertów to dashboardy, na które nikt nie patrzy. Claude Code może wygenerować zarówno instrumentację, jak i reguły alertów w jednym przejściu.

Look at our API routes and generate Prometheus metrics for: 1) request count by method, route, and status code, 2) request duration histogram with buckets at 50ms, 100ms, 250ms, 500ms, 1s, 5s, 3) active database connection pool gauge, 4) business metrics for orders_created and payments_processed counters. Then generate a prometheus-rules.yml with alerts for: error rate above 1% for 5 minutes (critical), p95 latency above 2 seconds for 10 minutes (warning), and database connection pool above 80% utilization (warning).

Notatka

Claude Code generuje nazwy metryk zgodnie z konwencjami nazewnictwa Prometheus (http_requests_total, http_request_duration_seconds) zamiast arbitralnych nazw. Jeśli twoje istniejące metryki używają innych konwencji, wspomnij o tym w prompcie, aby Claude dostosował się do twojego stylu.

Dashboardy Grafana jako kod

Dashboardy Grafana tworzone przez klikanie w interfejsie mają tendencję do gnicia. Dashboardy zdefiniowane jako JSON i przechowywane w kontroli wersji pozostają dokładne. Claude Code może wygenerować JSON dashboardu, który commitujesz obok kodu aplikacji.

Wskazówka

Prompt do skopiowania — JSON dashboardu Grafana:

Generate a Grafana dashboard JSON file for our API service. Include panels for: 1) request rate by status code (timeseries), 2) p50/p95/p99 latency (timeseries), 3) error rate percentage (stat with red threshold at 1%), 4) top 5 slowest endpoints (table), 5) database query duration histogram (heatmap), 6) active connections gauge. Use the Prometheus datasource named 'default'. Set the dashboard to auto-refresh every 30 seconds with a default time range of 6 hours.

Commituj JSON do monitoring/dashboards/api-overview.json i provisionuj go przez dashboard provisioning Grafany. W ten sposób zmiany dashboardu przechodzą przez code review tak samo jak zmiany aplikacji.

Definicje SLO i budżety błędów

Service Level Objectives zamieniają mgliste “powinno być szybkie” w mierzalne cele z alertami opartymi na burn-rate.

Define SLOs for our API: 99.9% availability (successful responses / total responses) and 95% of requests under 500ms. Generate Prometheus recording rules for the SLO ratios, error budget remaining (over a 30-day window), and multi-window burn-rate alerts. Use the standard Google SRE approach with 1h/6h fast-burn and 3d/30d slow-burn windows. Also generate the Alertmanager routing that sends fast-burn alerts to PagerDuty and slow-burn alerts to Slack.

To tworzy zestaw recording rules i alert rules, które ręczne napisanie zajęłoby godziny, szczególnie matematyka multi-window burn-rate. Claude Code poprawnie pisze PromQL, ponieważ widział tysiące implementacji SLO.

Monitorowanie użycia Claude Code

Jeśli twój zespół używa Claude Code w CI (przez claude-code-action do review PR lub automatycznych poprawek), powinieneś śledzić również to użycie. Claude Code wspiera eksport OpenTelemetry dla swoich własnych operacji.

# Enable Claude Code telemetry export
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_EXPORTER_OTLP_ENDPOINT=https://your-collector:4318
export OTEL_RESOURCE_ATTRIBUTES="team=platform,cost_center=eng-42"

Następnie poproś Claude Code o wygenerowanie dashboardu dla swoich własnych metryk:

Generate a Grafana dashboard for Claude Code team usage. Use the claude_code.* metric namespace. Include panels for: sessions per day by user, average tokens per session, tool acceptance rate (accepted edits / total edits), cost per team, and most-used languages.

Gdy coś idzie nie tak

Trace’y nie mają spanów dla pewnych tras. Automatyczna instrumentacja obejmuje standardowe handlery HTTP, ale pomija własny middleware lub konsumentów kolejek. Poproś Claude Code: “Add manual span creation for our Bull queue job processors in workers/” — wygeneruje wrapper tracer.startActiveSpan wokół każdego handlera jobów.

Objętość logów eksploduje po migracji na strukturalne logowanie. Strukturalne logi są większe niż łańcuchy console.log. Dodaj sampling logów dla często używanych ścieżek o niskiej wartości: “Add log sampling at 10% for GET /api/health and GET /api/readiness routes. Log all errors at 100% regardless of sampling.”

Cele scrapowania Prometheus nie są odkrywane. Jeśli używasz Kubernetes, service discovery opiera się na adnotacjach podów. Poproś Claude Code: “Add the prometheus.io/scrape, prometheus.io/port, and prometheus.io/path annotations to our Kubernetes deployment manifest so Prometheus discovers our metrics endpoint at /metrics on port 9090.”

Dashboard Grafana pokazuje “No data” po deployu. Nazwy metryk lub wartości etykiet się zmieniły. Claude Code może pomóc: “Compare our old Prometheus metric names with the new ones from the OpenTelemetry migration and generate a recording rules file that maps old names to new names for backward compatibility.”

Zmęczenie alertami z powodu zbyt wielu ostrzeżeń. Pierwsza wersja reguł alertów jest zawsze zbyt hałaśliwa. Iteruj: “Review our current alert rules and increase the ‘for’ duration on warning-level alerts from 5 minutes to 15 minutes. Group related alerts so we get one notification per incident, not one per pod.”

Co dalej

Analiza wydajności Użyj danych obserwowalności, które właśnie skonfigurowałeś, do znajdowania i naprawiania wąskich gardeł wydajnościowych

Audyt bezpieczeństwa Dodaj monitoring skoncentrowany na bezpieczeństwie i logowanie audytowe do swojego stacku obserwowalności

Automatyzacja wdrożeń Podłącz monitoring do skryptów deploy dla automatycznego wycofania w przypadku anomalii