Wzorce Monitorowania i Logowania

Twoje API zwraca losowe błędy 500. Pulpity Grafany świecą na zielono, logi błędów nie pokrywają się ze spanami, a Twój PM chce oszacowania czasu. Bolesna prawda: konfiguracja obserwowalności jest drobiazgowa, łatwo ją źle skopiować, a ten jeden ślad, którego potrzebujesz, został odrzucony przez próbkowanie godzinę temu.

Ta receptura pokazuje, jak użyć Cursor, Claude Code i Codex do wygenerowania instrumentacji i konfiguracji, która wyłapuje te awarie — oraz jak połączyć AI bezpośrednio z Grafaną i Sentry, by mogło czytać telemetrię na żywo w trakcie debugowania.

Co Z Tego Wyniesiesz

• Gotowy do wklejenia prompt, który automatycznie instrumentuje usługę Express lub FastAPI za pomocą OpenTelemetry i eksportuje OTLP do Twojego kolektora
• Prompty generujące reguły nagrywania Prometheus, alerty burn-rate dla SLO oraz drzewo routingu AlertManagera, które możesz przejrzeć linijka po linijce
• Prompt do pipeline’u Logstash, który parsuje logi JSON, redaguje PII i koreluje trace_id, dzięki czemu logi linkują z powrotem do śladów
• Konfiguracja MCP dla Grafany i Sentry, która pozwala agentowi odpytywać Twoje prawdziwe pulpity i issues, zamiast zgadywać
• Tryby awarii, które gryzą na produkcji — eksplozje kardynalności, gubione spany, próbkowanie ukrywające ślad, którego potrzebujesz

Najpierw Podłącz Serwery MCP do Obserwowalności

Zanim wygenerujesz konfigurację, daj agentowi wgląd w telemetrię na żywo. Z podłączonymi serwerami MCP Grafany i Sentry model może czytać pulpity, odpytywać źródła danych i wyciągać stosy wywołań — więc jego sugestie opierają się na Twoich rzeczywistych danych, a nie na ogólnym szablonie.

Cursor

Dodaj do .cursor/mcp.json. Oficjalny serwer Sentry jest zdalny (hostowany); Grafana dostarcza oficjalny binarny plik Go, który uruchamiasz lokalnie i kierujesz na swoją instancję:

{
  "mcpServers": {
    "sentry": { "url": "https://mcp.sentry.dev/mcp" },
    "grafana": {
      "command": "mcp-grafana",
      "env": {
        "GRAFANA_URL": "https://grafana.example.com",
        "GRAFANA_API_KEY": "${GRAFANA_SERVICE_ACCOUNT_TOKEN}"
      }
    }
  }
}

Claude Code

Sentry to oficjalny serwer zdalny (uwierzytelnij się przez /mcp po dodaniu). Oficjalny binarny plik Grafany grafana/mcp-grafana działa przez stdio:

# Oficjalny zdalny serwer MCP Sentry — uwierzytelnianie przez /mcp
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# Oficjalny serwer MCP Grafana Labs (binarka mcp-grafana / obraz Docker mcp/grafana)
claude mcp add grafana \
  --env GRAFANA_URL=https://grafana.example.com \
  --env GRAFANA_API_KEY=$GRAFANA_SERVICE_ACCOUNT_TOKEN \
  -- mcp-grafana

Codex

Codex przechowuje wpisy MCP w ~/.codex/config.toml. Użyj --url dla hostowanego serwera Sentry oraz polecenia stdio dla Grafany:

# Hostowany serwer MCP Sentry (OAuth: codex mcp login sentry)
codex mcp add sentry --url https://mcp.sentry.dev/mcp

# Serwer stdio Grafana Labs
codex mcp add grafana \
  --env GRAFANA_URL=https://grafana.example.com \
  --env GRAFANA_API_KEY=$GRAFANA_SERVICE_ACCOUNT_TOKEN \
  -- mcp-grafana

Notatka

Używaj oficjalnych serwerów, a nie podróbek. Serwer Sentry to zdalny https://mcp.sentry.dev/mcp (lub pakiet npm @sentry/mcp-server do self-hostingu) — a nie porzucony sentry-mcp. Serwer Grafany to grafana/mcp-grafana od Grafana Labs, a nie reimplementacje firm trzecich na npm. Dla Elasticsearch firma Elastic publikuje @elastic/mcp-server-elasticsearch. Zajęte przez squatterów lub hobbystyczne pakiety MCP szybko się dezaktualizują i mogą wyciekać dane uwierzytelniające.

Korzyść: zamiast wklejać stos wywołań do czatu, prosisz agenta, by go pobrał.

Wskazówka

Debuguj incydent na żywo z podłączonym MCP Sentry:

Using the Sentry MCP, find the top 3 unresolved issues in project api-prod from the last 6 hours by event count. For the highest-frequency one, pull the latest event’s stack trace and breadcrumbs, identify which release introduced it (compare first_seen to our deploy times), and propose the smallest code fix. Show me the suspect function before you suggest changes.

Zinstrumentuj Usługę (Tam, Gdzie Naprawdę Zaczyna Się Większość Bugów)

Pulpity są pochodną instrumentacji. Jeśli usługa emituje złe atrybuty lub brak kontekstu śladu, żadna liczba paneli Grafany Cię nie uratuje. To rzecz o najwyższej dźwigni, którą trzeba zrobić dobrze, i jest identyczna niezależnie od tego, którego agenta używasz — liczy się prompt.

Wskazówka

Automatycznie zinstrumentuj usługę Node/Express za pomocą OpenTelemetry:

Instrument this Express service with OpenTelemetry using the OTLP/HTTP exporter (@opentelemetry/exporter-trace-otlp-proto), not the deprecated Jaeger exporter. Auto-instrument http, express, pg, and ioredis; disable fs instrumentation. Set service.name, service.version, and deployment.environment from env vars. Redact Authorization and Cookie headers on spans. Export to http://otel-collector:4318/v1/traces with a BatchSpanProcessor. Add a SIGTERM handler that flushes spans before exit.

To, co generuje agent, to standardowy bootstrap SDK — częścią wartą przejrzenia jest eksporter i zamykanie:

// tracing.js — load with: node --require ./tracing.js server.js
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto');
const { resourceFromAttributes } = require('@opentelemetry/resources');
const {
  ATTR_SERVICE_NAME,
  ATTR_SERVICE_VERSION,
} = require('@opentelemetry/semantic-conventions');

const sdk = new NodeSDK({
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: process.env.SERVICE_NAME ?? 'api-service',
    [ATTR_SERVICE_VERSION]: process.env.SERVICE_VERSION ?? '0.0.0',
    'deployment.environment': process.env.ENVIRONMENT ?? 'production',
  }),
  // Jaeger ingests OTLP natively since v1.35 — no Jaeger exporter needed.
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTLP_ENDPOINT ?? 'http://otel-collector:4318/v1/traces',
  }),
  instrumentations: [getNodeAutoInstrumentations({
    '@opentelemetry/instrumentation-fs': { enabled: false },
  })],
});

sdk.start();
process.on('SIGTERM', () => sdk.shutdown().finally(() => process.exit(0)));

Uwaga

Jeśli poprosisz starszy model o „śledzenie OpenTelemetry”, często sięgnie po @opentelemetry/exporter-jaeger i endpoint Thrift 14268/api/traces. OpenTelemetry porzuciło wsparcie dla eksportera Jaeger w lipcu 2023 i biblioteki klienckie Jaeger są zarchiwizowane. Zawsze eksportuj OTLP (port 4318 dla HTTP, 4317 dla gRPC). Jaeger przyjmuje natywny OTLP od v1.35 — kieruj eksporter na kolektor, a nie na port Thrift Jaegera.

Generuj Reguły Prometheus i Alerty SLO

Pliki reguł Prometheus to obszar, gdzie pomoc AI błyszczy — składnia jest wybredna, a PromQL łatwo subtelnie zepsuć. Trzymaj prompt zdecydowany, by dostać reguły nagrywania metodą RED plus alerty burn-rate, a nie ścianę wszystkich metryk, jakie tylko można sobie wyobrazić.

Wskazówka

Wygeneruj reguły alarmowania oparte na SLO:

Write a Prometheus rules file for an HTTP API. Add recording rules for request rate, 5xx error ratio, and p95/p99 latency from http_request_duration_seconds_bucket, all grouped by job. Then add multi-window burn-rate alerts for a 99.5% availability SLO: a fast-burn alert (1h and 5m windows, 14.4x budget burn, severity critical) and a slow-burn alert (6h and 30m windows, 6x burn, severity warning). Include summary, description, and a runbook_url annotation on each.

Wygenerowane reguły nagrywania wyglądają tak — krótkie, łatwe do przejrzenia i będące fundamentem każdego alertu:

rules/api.yml

groups:
  - name: api_recording
    interval: 30s
    rules:
      - record: job:http_requests:rate5m
        expr: sum by (job) (rate(http_requests_total[5m]))
      - record: job:http_errors:ratio5m
        expr: |
          sum by (job) (rate(http_requests_total{status=~"5.."}[5m]))
          / sum by (job) (rate(http_requests_total[5m]))
      - record: job:http_latency:p95_5m
        expr: |
          histogram_quantile(0.95,
            sum by (job, le) (rate(http_request_duration_seconds_bucket[5m])))

Uwaga

Uważaj na kardynalność. Modele uwielbiają dodawać etykiety o wysokiej kardynalności — user_id, request_id, pełne ścieżki URL z wbudowanymi identyfikatorami. Każda unikalna kombinacja etykiet to osobny szereg czasowy; etykieta taka jak user_id może pomnożyć liczbę szeregów przez miliony i wywołać OOM w Prometheusie. Przeglądając wygenerowane reguły, odrzucaj każdą etykietę, która nie jest ograniczona do małego, znanego zbioru (kod statusu, metoda, szablon trasy, job). Poproś agenta wprost: „audit these metrics for unbounded label cardinality.”

Dla routingu AlertManagera przekaż agentowi swoją politykę eskalacji prostym językiem i pozwól mu wytworzyć drzewo:

Wskazówka

Wygeneruj konfigurację routingu AlertManagera:

Write an alertmanager.yml. Route severity: critical to PagerDuty with group_wait: 0s and repeat_interval: 1h. Route alerts where service matches ^(postgres|redis|mongodb) to a #db-alerts Slack channel. Mute severity: warning alerts on weekends and outside 09:00–18:00 on weekdays via mute_time_intervals. Add an inhibit rule so a firing critical suppresses matching warning alerts for the same alertname and cluster. Reference secrets via env vars, never inline.

Parsuj i Koreluj Logi

Najbardziej wartościowy ruch w logowaniu to sprawienie, by logi linkowały ze śladami. Jeśli każda linia logu niesie trace_id, klikasz ze spanu w Grafanie prosto do otaczających logów. Poniższy prompt produkuje pipeline Logstash, który robi dokładnie to.

Wskazówka

Wygeneruj pipeline Logstash z korelacją śladów i redakcją PII:

Write a logstash.conf with a Beats input on 5044 (TLS) and a Kafka input on the application-logs topic. Parse JSON-formatted log bodies, promote trace_id and span_id to top-level fields so logs correlate with traces, and convert status to an integer. Redact credit-card and email patterns in the message with gsub. Drop DEBUG logs when environment == "production". Output to Elasticsearch using ILM with rollover alias logs, and tee anything where log_level == "ERROR" to a dead_letter file.

Blok korelacji śladów to część do zweryfikowania — upewnij się, że nazwy pól pasują do tego, co emituje Twój SDK OpenTelemetry:

filter {
  if [message] =~ /^\{/ {
    json { source => "message" target => "parsed" }
    mutate {
      rename => {
        "[parsed][trace_id]" => "trace_id"
        "[parsed][span_id]"  => "span_id"
        "[parsed][level]"    => "log_level"
      }
    }
  }
  if [environment] == "production" and [log_level] == "DEBUG" { drop {} }
}

Notatka

Wolisz Loki od stosu ELK? Prompty przekładają się bezpośrednio — zamień „pipeline Logstash” na „konfigurację Promtail/Alloy”, a „wyjście Elasticsearch” na „endpoint push Loki”. Logika korelacji śladów (trace_id jako etykieta/pole) to ta sama idea, a LogQL Loki naturalnie współgra z powyższymi regułami Prometheus, skoro oba żyją w Grafanie.

Próbkowanie Ogonowe w Kolektorze

Domyślne próbkowanie nagłówka (head sampling) odrzuca ślady na ślepo — i tak właśnie znika ten jeden ślad, którego potrzebowałeś. Próbkowanie ogonowe (tail sampling) decyduje po zakończeniu śladu, więc możesz zachować 100% błędów i wolnych żądań, próbkując nudne rzeczy na poziomie 5%.

Wskazówka

Skonfiguruj próbkowanie ogonowe w OpenTelemetry Collector:

Add a tail_sampling processor to my OTel Collector config with three policies combined: keep 100% of traces containing any span with status_code = ERROR, keep 100% of traces with total latency over 1000ms, and sample everything else at 5% probabilistic. Set decision_wait: 30s. Also add an attributes processor that deletes http.request.header.authorization and db.statement before export. Wire both into the traces pipeline exporting OTLP to our backend on 4317.

Uwaga

Próbkowanie ogonowe wymaga, by każdy span śladu trafił do tej samej instancji kolektora. Jeśli uruchamiasz wiele replik kolektora za load balancerem typu round-robin, spany z jednego śladu rozpraszają się po replikach, a sampler podejmuje decyzje na podstawie częściowych śladów — po cichu gubiąc dane. Użyj eksportera loadbalancing (routing świadomy trace-ID) w dwuwarstwowej konfiguracji kolektora albo uruchom pojedynczy kolektor z próbkowaniem ogonowym. Poproś agenta, by „explain how this scales to N replicas”, zanim go wdrożysz.

Kiedy To Się Psuje

1. Spany w ogóle się nie pojawiają. Najpierw sprawdź endpoint eksportera i niezgodność protokołu — OTLP/HTTP to 4318, OTLP/gRPC to 4317, a eksporter proto vs http/json musi pasować do odbiornika. Uruchom eksporter debug kolektora (verbosity: detailed), by potwierdzić, że spany docierają, zanim zaczniesz winić backend.

2. Prometheus dostaje OOM albo scrapy są wolne. Masz eksplozję kardynalności. Odpytaj topk(20, count by (__name__)({__name__=~".+"})) oraz prometheus_tsdb_head_series, by znaleźć winowajcę, a potem usuń sprawczą etykietę regułą metric_relabel_configs. Niemal zawsze jest to etykieta dodana przez AI, której nie wyłapałeś podczas przeglądu.

3. Alerty odpalają z opóźnieniem albo w burzach. Sprawdź ponownie for:, group_wait i repeat_interval. Alert burn-rate ze zbyt długim oknem nie zawiadomi, dopóki nie przepalisz już budżetu; group_wait: 0s na wszystkim zamienia awarię klastra w setki powiadomień.

4. Logi nie korelują ze śladami. Nazwa pola trace_id z Twojego SDK nie pasuje do tego, czego oczekuje pipeline, albo jest zagnieżdżona. Zaloguj jedno surowe zdarzenie i potwierdź dokładną ścieżkę, zanim zaufasz blokowi rename/mutate.

5. Ślad, którego potrzebowałeś, został odrzucony przez próbkowanie. Odrzuciło go próbkowanie nagłówka. Przenieś decyzje o błędach/opóźnieniu do próbkowania ogonowego w kolektorze (powyżej) i trzymaj błędy na 100%.

Co Dalej

Receptury Wzorców SQL Podłącz serwer MCP bazy danych i pozwól agentowi profilować wolne zapytania na prawdziwych danych.

Receptury Pipeline'ów CI/CD Wepnij te alerty i SLO w bramki wdrożeniowe oraz automatyczne rollbacki.

Wzorce Debugowania Systematyczne wzorce promptów, które zamieniają telemetrię w przyczynę źródłową.

Najlepsze Praktyki MCP Jak MCP działa w Cursor, Claude Code i Codex oraz jak ocenić serwer.