Konfiguracja logowania i monitoringu w Cursorze

Konfiguracja logowania i monitoringu w Cursorze polega na tym, że agent Cursora generuje dla serwisu cztery warstwy obserwowalności oraz dashboardy: ustrukturyzowane logi JSON, metryki Prometheusa, trace’y OpenTelemetry i reguły alertów. Agent pisze każdą warstwę szybko, bo konwencje są dobrze udokumentowane; zaufaj warstwie dopiero wtedy, gdy dowiedzie tego test, promtool lub test dymny trace’ów.

Ta strona jest dla programistów, którzy utrzymują serwis w Node.js lub TypeScripcie, i dla tech leadów, którzy ustalają konwencje obserwowalności w zespole. O 2:00 w nocy dzwoni pager: „wysoki odsetek błędów w API zamówień”. W logach jest tylko Internal Server Error, bez ID żądania, bez trasy i bez użytkownika, a skoku na dashboardzie nie da się powiązać z żadną linią kodu. Rozwiązaniem nie jest więcej logów. Są nim logi, metryki i trace’y, które dzielą identyfikatory, oraz alerty reagujące na objawy odczuwalne przez użytkownika.

Co daje stos obserwowalności zbudowany przez agenta

• Regułę projektu, która ustala nazwy pól, zestawy etykiet i poziomy logów, zanim agent napisze jakikolwiek kod.
• Logger pino z kontekstem żądania, maskowaniem sekretów i trace_id w każdej linii.
• Metryki prom-client z ograniczonym zestawem etykiet oraz test, który nie przechodzi, gdy ktoś doda etykietę o nieograniczonej liczbie wartości.
• Tracing OpenTelemetry ładowany przed aplikacją, który propaguje nagłówek W3C traceparent między serwisami.
• Reguły alertów Prometheusa z testami jednostkowymi w promtool, więc wiesz, że każdy alert działa, zanim sprawdzi go produkcja.
• Cursora podłączonego przez MCP do Sentry lub Grafany, dzięki czemu agent czyta prawdziwą telemetrię podczas debugowania.

Przykłady używają Expressa na Node.js. Prompty działają też z Fastify, NestJS czy route handlerami Next.js, gdy zmienisz nazwę frameworka i sposób odczytu wzorca trasy (na przykład routeOptions.url w Fastify).

W jakiej kolejności agent powinien budować obserwowalność?

Buduj warstwy w kolejności zależności: konwencje, potem logi, metryki, trace’y, alerty, a dashboardy na końcu. Alerty odpytują nazwy metryk, a dashboardy jedno i drugie, więc wygenerowane jako pierwsze wskazywałyby serie, które nie istnieją. Każdy krok poniżej kończy się bramką. Nie zaczynaj kolejnego, dopóki bramka nie jest zielona.

1. Zapisz konwencje jako regułę projektu. Bez niej agent wybiera nazwy pól osobno w każdym pliku: requestId w middleware, req_id w serwisie zamówień, request_id w testach. Reguła ujednolica każdy kolejny prompt. Gdzie reguły leżą i jak się ładują, opisuje strona o regułach projektu w Cursorze.

2. Poproś o plan przed kodem. Przełącz agenta w Plan Mode i każ mu zinwentaryzować to, co już istnieje. Plan Mode „tworzy szczegółowe plany implementacji przed napisaniem jakiegokolwiek kodu” (dokumentacja Cursora, sprawdzone 2026-08-28), więc agent nie dokręci drugiego loggera do serwisu, który już jeden ma.

3. Generuj jedną warstwę na rozmowę. Nowa rozmowa dla każdej warstwy utrzymuje mały kontekst i diff, który da się przejrzeć. Commituj po każdej zielonej bramce, żeby wadliwą warstwę dało się czysto wycofać przez git revert.

Prompt do skopiowania: reguła konwencji obserwowalności

Create a Cursor project rule named "observability" that applies to every
file under src/. It must state these conventions, and nothing else:

Logging
- Logger: the pino instance exported from src/lib/logger.ts. Never console.log.
- Required fields on every line: time (ISO 8601), level, service, env,
  request_id, trace_id, span_id. Use snake_case for all field names.
- Levels: error = a request failed or data was lost; warn = degraded but
  served; info = one line per business event; debug = off in production.
- Never log: password, token, authorization, cookie, card numbers, full
  request bodies.

Metrics
- Library: prom-client, registry exported from src/lib/metrics.ts.
- Allowed label keys: method, route, status_class, payment_method, provider,
  result. The route label is the Express route pattern (/orders/:id), never
  the raw URL. Never use user_id, order_id, email or request_id as a label.
- Names: snake_case, unit suffix (_seconds, _bytes), counters end in _total.

Tracing
- OpenTelemetry. Use current HTTP semantic conventions
  (http.request.method, http.route, http.response.status_code), not the
  deprecated http.method / http.status_code.

Before writing the rule, read the existing code and list any place that
already breaks these conventions. Do not fix them yet.

Wygeneruj ustrukturyzowane logowanie z kontekstem żądania

Logi są pierwszą warstwą, bo wszystkie pozostałe odwołują się do ich identyfikatorów. Prompt poniżej prosi w jednym przebiegu o logger, middleware żądań i test, który dowodzi, że oba działają.

Prompt do skopiowania: logger pino z kontekstem żądania

Follow the observability project rule.

1. Create src/lib/logger.ts using pino:
   - base fields: service (SERVICE_NAME), env (NODE_ENV)
   - level from LOG_LEVEL, default "info"
   - redact: password, token, authorization, cookie, and the same keys
     nested under req.headers and body
   - pretty output only when NODE_ENV=development (pino-pretty transport);
     single-line JSON otherwise
   - a mixin that adds request_id from AsyncLocalStorage and trace_id /
     span_id from the active OpenTelemetry span, when present

2. Create src/middleware/request-context.ts (Express):
   - request_id = incoming x-request-id header if it is a UUID, else a new UUID
   - store it in AsyncLocalStorage for the whole request
   - echo it back as the x-request-id response header
   - log one "request completed" line with method, route pattern,
     status_code and duration_ms; skip /health and /ready

3. Create tests/logger.test.ts. Capture pino output into an in-memory
   stream and assert:
   - every line parses as JSON and has the required fields from the rule
   - a logged object with password and headers.authorization comes out
     with both values replaced by "[Redacted]"
   - two concurrent requests keep their own request_id (no leakage
     through AsyncLocalStorage)

Run the tests and show me one captured production-mode log line.

Bramka: trzy testy przechodzą, a przykładowa linia zawiera request_id i żadnego sekretu. Najważniejszy jest test współbieżności: przeciek AsyncLocalStorage między żądaniami jest niewidoczny przy ręcznym sprawdzeniu jednego żądania.

Kontekst biznesowy dodawaj później przez logger potomny dla jednostki pracy, a nie nowe pola w każdym wywołaniu: „W src/services/orders.ts utwórz na początku processOrder child logger z order_id i customer_id i używaj go w każdej linii logu tej funkcji”. Identyfikatory biznesowe należą do logów, gdzie każda linia to jedno zdarzenie, i nigdy do etykiet metryk.

Dodaj metryki Prometheusa bez eksplozji kardynalności

Metryki odpowiadają zbiorczo na pytania „jak często” i „jak wolno”. Prawdziwą decyzją projektową jest zestaw etykiet. Każda odrębna kombinacja wartości etykiet tworzy nową serię czasową, więc jedna etykieta user_id zamienia licznik w osobną serię na każdego użytkownika.

Prompt do skopiowania: metryki prom-client ze strażnikiem kardynalności

Follow the observability project rule.

1. Create src/lib/metrics.ts with prom-client:
   - call collectDefaultMetrics() once; do not redefine its Node.js metrics
   - http_requests_total (counter: method, route, status_class)
   - http_request_duration_seconds (histogram: method, route;
     buckets 0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5)
   - orders_created_total (counter: payment_method)
   - payment_attempts_total (counter: provider, result)
   - helpers recordOrderCreated(paymentMethod) and
     recordPaymentAttempt(provider, result)

2. Middleware that records the HTTP metrics on res "finish", using
   req.baseUrl + req.route.path as the route label, and "unmatched" when
   Express matched no route. Expose GET /metrics; do not record /metrics
   or /health themselves.

3. tests/metrics.test.ts:
   - fire 50 requests to /orders/<random id> and assert
     http_requests_total has exactly one series for route="/orders/:id"
   - request an unknown path 20 times with different URLs and assert
     they all land in route="unmatched"
   - parse /metrics output and, for metrics this service defines
     (exclude process_* and nodejs_*), fail if any label key other than
     the allowed list in the rule or the histogram "le" label appears

Run the tests and paste the /metrics lines for http_requests_total.

Bramka: test liczby serii przechodzi. Przypadek unmatched łapie najczęstszy błąd w wygenerowanym kodzie: req.path albo req.originalUrl jako etykietę, co działa w demo, a pod ruchem skanera tworzy osobną serię na każdy URL.

Podłącz tracing OpenTelemetry między serwisami

Tracing łączy jedno żądanie użytkownika w wielu serwisach i przez trace_id wiąże je z liniami logów. SDK dla Node.js ma jedną twardą zasadę, którą agent często pomija: musi się załadować przed importem express, http i klientów baz danych. Inaczej automatyczna instrumentacja niczego nie łata, a ty dostajesz puste trace’y bez żadnego błędu.

Prompt do skopiowania: konfiguracja OpenTelemetry w Node.js

Follow the observability project rule.

1. Create src/instrumentation.ts using @opentelemetry/sdk-node and
   @opentelemetry/auto-instrumentations-node:
   - service.name from SERVICE_NAME
   - OTLP HTTP trace exporter; endpoint from OTEL_EXPORTER_OTLP_ENDPOINT
   - ConsoleSpanExporter when NODE_ENV=development
   - disable the fs instrumentation (too noisy)
   - shut the SDK down on SIGTERM so the last spans are flushed

2. Load it before the app: change the start script to
   node --import ./dist/instrumentation.js dist/server.js
   (or --require for CommonJS). Do not import it from server.ts.
   If the built app is ESM, also pass the OpenTelemetry loader hook:
   node --experimental-loader=@opentelemetry/instrumentation/hook.mjs \
     --import ./dist/instrumentation.js dist/server.js
   Without the hook, ESM imports of express and http are never patched.

3. Do not write custom middleware that creates server spans. The HTTP and
   Express auto-instrumentations already do. Only add a withSpan(name, fn)
   helper for business steps such as "reserve-inventory".

4. tests/tracing.smoke.test.ts: start the app with an in-memory span
   exporter, send a request with the header
   traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
   and assert that
   - the server span has trace_id 4bf92f3577b34da6a3ce929d0e0e4736
   - the "request completed" log line has the same trace_id
   - an outgoing fetch to a stub service carries a traceparent header
     with that trace_id

Bramka: test dymny przechodzi. Dowodzi trzech rzeczy, które inaczej sprawdzałbyś ręcznie w trzech narzędziach: SDK załadowało się na czas, logger czyta aktywny span, a propagacja działa w wywołaniach wychodzących. Nazwy pakietów powyżej są aktualne w npm na 2026-09-26 (@opentelemetry/sdk-node 0.222.0, @opentelemetry/auto-instrumentations-node 0.80.0).

Wygeneruj reguły alertów i udowodnij, że się odpalają

Alertuj na objawy odczuwalne przez użytkownika, takie jak odsetek błędów i opóźnienie, a nie na przyczyny w rodzaju CPU. Agent dobrze pisze składnię reguł Prometheusa. Luką są progi, których nikt nigdy nie przećwiczył. Zamyka ją promtool test rules: podaje regułom syntetyczne serie i sprawdza, które alerty odpalają się w której minucie.

Prompt do skopiowania: reguły alertów z testami promtool

Use only metric names that exist in src/lib/metrics.ts.

1. monitoring/alerts/api.yml (Prometheus rule format):
   - ApiErrorRatioHigh: 5xx / all requests > 0.05 for 5m, severity page
   - ApiLatencyP99High: histogram_quantile(0.99, ...) > 2s for 10m,
     severity ticket
   - ApiNoTraffic: absent or zero request rate for 5m, severity page
   Every alert has labels.severity and annotations summary, description
   and runbook_url (https://runbooks.example.internal/<alert-name>).

2. monitoring/alerts/business.yml:
   - PaymentFailureRatioHigh: failed / all payment_attempts_total > 0.10
     for 10m, severity page

3. monitoring/alerts/tests/api_test.yml with promtool unit tests:
   - a series at 1% errors for 15m: ApiErrorRatioHigh does NOT fire
   - a series at 10% errors: does NOT fire at 4m; fires by 7m
   - zero traffic: ApiNoTraffic fires
   Derive each eval_time from the rule's for: plus its rate() window,
   and explain the choice in a comment.

Then give me the exact commands to run promtool check rules and
promtool test rules in the prom/prometheus Docker image.

Uruchom bramkę w terminalu. Obraz prom/prometheus zawiera promtool, więc nie potrzebujesz lokalnej instalacji Prometheusa:

docker run --rm -v "$PWD/monitoring:/m" --entrypoint promtool \
  prom/prometheus check rules /m/alerts/api.yml /m/alerts/business.yml
docker run --rm -v "$PWD/monitoring:/m" --entrypoint promtool \
  prom/prometheus test rules /m/alerts/tests/api_test.yml

Bramka: obie komendy kończą się kodem 0. Dodaj je do CI obok testów jednostkowych, żeby późniejsza zmiana nazwy metryki psuła build, a nie budziła dyżurnego. Gdzie umieścić ten job, pokazuje strona CI/CD z Cursorem.

Dashboardy są na końcu i niosą najmniejsze ryzyko: błędny panel wprowadza człowieka w błąd, a błędny alert go budzi. Poproś o JSON dashboardu Grafany ze zmiennymi szablonu environment i service oraz po jednym wierszu na ruch, błędy, opóźnienie i nasycenie. Każ agentowi używać wyłącznie nazw metryk z src/lib/metrics.ts. Zaimportuj dashboard do stagingowej Grafany i sprawdź, czy każdy panel zwraca dane.

Pozwól Cursorowi czytać telemetrię z produkcji przez MCP

Wygenerowana instrumentacja to połowa pętli. Druga połowa to agent, który czyta, co ta instrumentacja raportuje, gdy coś się psuje. Cursor wczytuje serwery MCP z .cursor/mcp.json w projekcie albo globalnie z ~/.cursor/mcp.json. Oficjalny zdalny serwer Sentry używa OAuth, więc konfiguracja nie zawiera żadnego sekretu:

{
  "mcpServers": {
    "sentry": { "url": "https://mcp.sentry.dev/mcp" }
  }
}

Dzięki temu prompt debugujący może zaczynać się od prawdziwych danych, a nie od wklejonego stack trace’a:

Prompt do skopiowania: debugowanie na podstawie błędów z produkcji

Using the Sentry MCP server, find the most frequent unresolved error in
the orders-api project over the last 24 hours. Show me its stack trace and
the request_id and trace_id from the event. Map the top in-app frame to
our source, explain the root cause, and propose a fix with a failing test
that reproduces it first. Do not change code until I approve the plan.

Dla metryk i logów Grafana Labs publikuje oficjalny serwer (uvx mcp-grafana, PyPI 1.6.0 na 2026-09-26), który odpytuje Prometheusa i Lokiego. Uruchamiaj go z --disable-write, żeby agent mógł czytać dashboardy, ale nie mógł ich zmieniać. Token konta serwisowego trzymaj w zmiennych środowiskowych, nigdy w commitowanym mcp.json. Konfigurację obu serwerów w różnych narzędziach opisują strony konfiguracja MCP w Cursorze i serwery MCP do obserwowalności.

Automations w Cursorze potrafią też uruchomić Cloud Agenta na zdarzenie z Sentry lub PagerDuty (dokumentacja Cursora, sprawdzone 2026-08-28). To przydaje się do wstępnej diagnozy w pull requeście, ale poprawka i tak przechodzi przez twoje zwykłe testy i review. Zanim podepniesz alert pod agenta, przeczytaj stronę o Cloud Agents i Automations.

Jak zweryfikować wygenerowany kod obserwowalności bez czytania go w całości?

Każda warstwa ma sprawdzenie behawioralne, które trwa kilka sekund. Razem zastępują przegląd linia po linii kilkuset linii instrumentacji.

Warstwa	Co może się zepsuć po cichu	Sprawdzenie, które to łapie
Logi	Sekrety w logach; request_id przecieka między żądaniami	Testy maskowania sekretów i współbieżności na przechwyconym wyjściu
Metryki	Etykiety bez limitu wartości; zła etykieta trasy	Test liczby serii i test dozwolonych kluczy etykiet na metrykach aplikacji
Trace’y	SDK ładuje się za późno; brak propagacji	Test dymny z traceparent i eksporterem w pamięci
Alerty	Reguła nigdy się nie odpala albo reaguje na szum	promtool test rules z przypadkami pozytywnymi i negatywnymi
Dashboardy	Panele odpytują metryki, które nie istnieją	Import do stagingowej Grafany; każdy panel pokazuje dane

Za testy odpowiada programista, który otwiera pull request. Tech lead odpowiada za regułę projektu i zatwierdza progi i priorytety alertów, bo to one decydują, kogo obudzi pager. Wzrokiem czytasz już niewiele: plik reguły, listę etykiet i progi alertów.

Kiedy wygenerowany kod obserwowalności zawodzi

Trace’y są puste i nic nie zgłasza błędu. SDK OpenTelemetry zostało zaimportowane po express lub http, więc niczego nie załatało. Druga przyczyna, przy buildzie ESM: SDK ładuje się pierwsze, ale brakuje hooka loadera, więc importy ESM nie zostają załatane. Naprawa: przenieś ładowanie do --import lub --require w komendzie startowej, dla aplikacji ESM dodaj --experimental-loader=@opentelemetry/instrumentation/hook.mjs, jak w prompcie o tracingu, i uruchom ponownie test dymny.

Po wdrożeniu rosną rachunki za przechowywanie metryk. Jakaś etykieta niesie surowy URL, identyfikator albo komunikat błędu. Naprawa: odpytaj Prometheusa o liczbę serii na metrykę (count by (__name__)({__name__=~"http_.*"})), znajdź winną etykietę i dopisz ją do listy zakazanych w regule projektu, żeby kolejne generowanie jej nie powtórzyło. Test kluczy etykiet pilnuje tego później.

Agent dopisał własne middleware tworzące spany obok automatycznej instrumentacji. Każde żądanie daje dwa zagnieżdżone spany serwerowe o tej samej nazwie. Naprawa: usuń własne middleware, a withSpan zostaw tylko dla kroków biznesowych. Prompt o tracingu mówi to od razu, bo agent domyślnie dodaje takie middleware.

Nazwy atrybutów nie pasują do zapytań w twoim backendzie. Wygenerowany kod często używa przestarzałych atrybutów http.method i http.status_code. Naprawa: zapisz aktualne konwencje w regule projektu, jak w prompcie o konwencjach, i poproś agenta o migrację istniejących spanów w jednym przebiegu.

Alerty odpalają się codziennie i ktoś je wycisza. Progi wybrano bez danych. Naprawa: przez pierwsze dwa tygodnie ustaw nowym alertom severity: ticket, porównaj historię ich odpaleń z prawdziwymi incydentami i dopiero te, które się pokryły, podnieś do page. Dla każdego zmienionego progu dodaj przypadek w promtool.

Logi produkcyjne są zbyt gadatliwe. Agent logował na poziomie info wewnątrz pętli. Naprawa: wyszukaj wywołania loggera w ciałach for i map, przenieś je na debug i potwierdź, że LOG_LEVEL bez ustawionej wartości przyjmuje domyślnie info, żeby produkcja nigdy nie logowała na poziomie debug, chyba że ktoś ustawi go celowo.

Co dalej z Cursorem i obserwowalnością

Monitoring i obserwowalność we wszystkich narzędziach Ta sama praktyka w Claude Code i Codeksie, plus SLO i dashboardy.

Reagowanie na incydenty z AI Jak używać tych logów, trace'ów i alertów podczas incydentu.

Obserwowalność agentów Monitorowanie samych agentów: trace'y, wywołania narzędzi, koszty i logi audytowe.

DevOps z Cursorem Wdrażanie Prometheusa, Grafany i kolektora jako infrastruktury jako kodu.

Mikroserwisy z Cursorem Propagacja trace'ów przez granicę każdego serwisu.

Eksploatacja z Cursorem Wydajność, bezpieczeństwo i zarządzanie tokenami w Cursorze na produkcji.