Rejestrowanie i śledzenie zdarzeń

Rejestrowanie i śledzenie zdarzeń

1) Przeznaczenie i ramka

Kłody i szlaki są podstawą obserwacji.
Dzienniki odpowiadają na „to, co się stało” i „z jakim kontekstem”.
Ślady odpowiadają na „gdzie i dlaczego powoli/błędnie” w rozproszonej ścieżce zapytań.

• Domyślna struktura (JSON); Trace-first: każdy dziennik na gorącej ścieżce jest powiązany z 'trace _ id'/' span _ id'.
• Minimalny hałas, maksymalny sygnał: poziomy, próbkowanie, antykardynalność.
• Bezpieczeństwo i prywatność: maskowanie, edycja, kontrola dostępu.
• Wersjonowane schematy dzienników i zdarzeń.

2) Taksonomia zdarzeń

1. Dzienniki techniczne (czas trwania, błędy, timeouts sieciowy, przekładki).

2. Wydarzenia biznesowe (rejestracja, depozyt, stawka, wypłata, etap KYC) - nadaje się do analizy produktów i incydentów wzdłuż ścieżek „pieniądze”.

3. Audyt (kto/kiedy zmienił co: konfiguracje, dostęp, flagi, limity) jest niezmiennym dziennikiem.

4. Bezpieczeństwo (uwierzytelnianie, eskalacja przywilejów, flagi sankcji/PEP).

5. Infrastruktura (wydarzenia K8s, autoskalarstwo, HPA/VPA, węzły/dysk/sieć).

Dla każdego strumienia - oddzielne zasady zatrzymywania, indeksowania i dostępu.

3) Dziennik strukturalny (standard JSON)

json
{
"ts": "2025-11-03T14:28:15.123Z",
"level": "ERROR",
"service": "payments-api",
"env": "prod",
"region": "eu-central-1",
"trace_id": "8a4f0c2e9b1f42d7",
"span_id": "c7d1f3a4b8b6e912",
"parent_span_id": "a1b2c3d4e5f60789",
"logger": "withdraw.handler",
"event": "psp_decline",
"msg": "PSP declined transaction",
"http": { "method": "POST", "route": "/withdraw", "status": 502, "latency_ms": 842 },
"user": { "tenant_id": "t_9f2", "user_key": "hash_0a7c", "vip_tier": 3 },
"payment": { "psp": "acme", "amount": 120.50, "currency": "EUR", "idempotency_key": "u123:wd:7845" },
"safe": true,         // пройдена проверка на секреты
"version": "1.14.2",     // версия сервиса (SemVer)
"build": "sha-1f2a3b4",
"kubernetes": { "pod": "payments-7cbdf", "node": "ip-10-0-2-41" }
}

Wymagania: schemat płaski + załączniki według domeny, wymagane pola ('ts, level, service, ا, trace_id, msg'), wartości liczbowe - liczby, nie ciągi.

4) Poziomy, kardynalność i zakres

Poziomy: "DEBUG" (nie w sprzedaży), "INFO" (fakty biznesowe), "WARN' (anomalie)," ERROR "(błędy)," FATAL "(awarie).
Kardynalność: unikać arbitralnych kluczy/etykiet dynamicznych. Brak „id-in-key”.
Dzienniki pobierania próbek: komunikaty powtarzające się o wartości granicznej; włączyć 'DEBUG' tylko w skopiowanym czasie (flaga funkcji).
Idempotency: Logowanie 'idempotency _ key' w celu stłumienia duplikatów zdarzeń przez konsumentów.

5) Prywatność i bezpieczeństwo

Maska PII/sekrety na agentach (Fluent Bit/Vector): karty do maskowania kluczy ('e-mail', 'card', 'token', 'authorization').
Hash 'user _ key', trzymaj tylko wymagany kontekst (kraj, poziom KYC, poziom VIP).
Oddzielne magazyny: ciepłe (wyszukiwanie online) i zimne (archiwum bez PII/z rozebranym kontekstem).
Audyt - tylko dodatek, przechowywanie WORM, dostęp tylko na zasadzie najmniejszego przywileju.

6) Śledzenie: normy i kontekst

Kontekst śladowy W3C: nagłówki "traceparent'/" tracestate", plus bagaż dla bezpiecznych kluczy (np. "najemca _ id'," region ").
Mierniki i ślady łącza: Przykłady - przekazać 'trace _ id' do punktów pobierania próbek histogramów (przyspiesza RCA).
Pobieranie próbek: próbkowanie podstawowe 1-5% + dynamiczne „na błędzie/wolnym p95” do 100% w przypadku zapytań problemowych.
Linki: Dla asynchronicznych kolejek/sagów, łącze obejmuje 'linki', a nie tylko 'rodzic'.

7) Zbieranie i routing

Agent: Fluent Bit/Vector dla dzienników; OTLP eksportuje do OpenTelemetry Collector.
Kolektor: centralna brama (partia/przekształcenie/filtr/routing).

App → (OTLP logs/traces/metrics) → OTel Collector
→ logs: redact → route(security    audit    tech    biz) → hot index / cold archive
→ traces: tail_sampling(errors    p95>threshold) → APM backend
→ metrics: Prometheus exporter (for SLO/alerts)

yaml processors:
batch: {}
attributes:
actions:
- key: env value: prod action: insert filter/logs:
logs:
include:
match_type: strict resource_attributes:
- key: service.name value: payments-api exporters:
otlp/traces: { endpoint: "apm:4317", tls: { insecure: true } }
loki: { endpoint: "http://loki:3100/loki/api/v1/push" }
prometheus: {}
service:
pipelines:
logs: { receivers: [otlp], processors: [attributes,batch], exporters: [loki] }
traces: { receivers: [otlp], processors: [batch], exporters: [otlp/traces] }
metrics: { receivers: [otlp], processors: [batch], exporters: [prometheus] }

8) Oprzyrządowanie: przykłady SDK

8. 1 węzeł. js (Pino + OTel)

js import pino from "pino";
import { context, trace } from "@opentelemetry/api";

const logger = pino({ level: process.env.LOG_LEVEL          "info" });

function log(info) {
const span = trace.getSpan(context.active());
const base = span? { trace_id: span.spanContext().traceId, span_id: span.spanContext().spanId }: {};
logger.info({...base,...info });
}

// пример log({ event: "deposit.created", amount: 50, currency: "EUR", user: { user_key: "hash_0a7c" } });

8. 2 Java (SLF4J + OTel)

java
MDC.put("trace_id", Span.current().getSpanContext().getTraceId());
MDC.put("span_id", Span.current().getSpanContext().getSpanId());
log.info("psp_response status={} latency_ms={}", status, latency);

8. 3 Python (structlog + OTel)

python import structlog from opentelemetry import trace log = structlog.get_logger()

def log_json(event, kwargs):
span = trace.get_current_span()
ctx = {}
if span and span.get_span_context().is_valid:
ctx = {"trace_id": span.get_span_context().trace_id, "span_id": span.get_span_context().span_id}
log.msg(event=event, ctx, kwargs)

8. 4 NGINX → odwzorowanie nagłówka

nginx proxy_set_header traceparent $http_traceparent;
proxy_set_header tracestate $http_tracestate;

9) Dzienniki jako sygnał do wpisów i akcji automatycznych

Błędne wzory ('psp _ decline', 'fraud _ flag') sumują się i korelują z SLO.

Alerty na wzór: "5xx by/withdraw> 0. 5% na 10m', „fraud_flag kolec> + 200% podstawy”

Automatyczne działania: jeśli dziennik jest 'withdrawals _ manual _ mode = true', włącz kill-switch przez platformę flag.

rate(count_over_time({service="payments-api", level="ERROR", event="psp_decline"}[5m])) > 5

10) Zatrzymywanie, indeksowanie, przechowywanie

Gorące: 7-14 dni (dochodzenie operacyjne).
Ciepło: 30-90 dni (trendy, RCA).
Zimno: 180-365 + (archiwum, audyt) - kompresja, tanie klasy, ewentualnie bez wyszukiwania pełnych tekstów.
Indeksowanie: klucze stałe ('serwis, na poziomie, zdarzenie, trace_id, użytkownik. tenant_id'), zakaz indeksu „wszystko z rzędu”.
Limity rozmiaru zdarzenia (na przykład ≤ 32KB), wykończenie/dno: „dodatkowa pamięć masowa jest wrogiem MTTR”.

11) Audyt i niezmienność

Zapisz zdarzenia audytu w osobnym strumieniu z podpisami/hashami, czasem serwera, „kto/co/kiedy/dlaczego”, link do biletu.
„Kto włączył flagę bonusową 100% w DE?” - odpowiedź musi być w 1-2 żądań.

json
{
"ts": "2025-11-03T14:00:00.000Z",
"actor": "alice@company",
"action": "feature_flag.update",
"target": "bonus.enable_vip",
"old": {"rollout": 10},
"new": {"rollout": 100},
"reason": "campaign_2311",
"ticket": "OPS-3481",
"trace_id": "cf12ab.."
}

12) Wydarzenia biznesowe i model danych

• 'event _ type', 'event _ id',' occurred _ at ',' actor ',' subject ',' amount ',' currency ',' status ',' idempotence _ key '.
• Użyj Outbox i „przynajmniej raz” z idempotentnymi konsumentami.

13) Kubernety i dzienniki rurociągów

Sidecar/DaemonSet agentów z buforem do dysku (podczas przerw w sieci).
Adnotacje podkładek do routingu ('log. typ „,” zatrzymanie. poziom dokładności ").
Zbierz dzienniki kontrolerów K8s osobno (klaster index).

ini
[FILTER]
Name     modify
Match
Remove    authorization, password, card_number

14) Anty-wzory

Dzienniki smyczkowe „w razie potrzeby”, brak 'trace _ id'.
PII/sekrety w dziennikach, ładunek w całości.
Miliony unikalnych kluczy → „eksplodował” indeksowanie.
DEBUG w sprzedaży 24/7.
Mieszanie audytu, bezpieczeństwa i technologów w jeden indeks.
Nie ma zasad zatrzymywania ani testu odzyskiwania kopii zapasowych.

15) Lista kontrolna realizacji (0-45 dni)

0-10 dni

Włącz kontekst śledzenia W3C na bramce/klientach, przesyłanie nagłówków.
Przetłumacz dzienniki aplikacji na JSON, dodaj 'trace _ id'/' span _ id'.
Odmowa PII/tajemnic (maskowanie agenta), zatwierdzenie listy pól.

11-25 dni

Oddzielne strumienie: tech/biz/audit/security/infra, set retention i ACL.
Włącz Kolektor OTel, błędy próbkowania ogona/powolne zapytania.
Deski rozdzielcze „Wskaźnik dziennika/błąd na trasie” + Jump-to-trace (Przykłady).

26-45 dni

Alerty i korelacje z SLO.
Archiwum/przywracanie (test DR) do zimnych dzienników.
Linter diagramów dziennika w CI, kontrakt na imprezy biznesowe.

16) Wskaźniki zapadalności

"Zasięg śladu _ id' wymagany ≥ 95%.
Udział kłód JSON ≥ 99%.
Zdarzenia stwierdzone przez „skok-do-śladu” rozwiązane <15 min (p50).
0 przypadków PII w dziennikach (skaner przecieku).
Retencja jest obserwowana dla wszystkich przepływów (udowadniamy audyt automatycznie).

17) Aplikacje: Mini Snippets

Generacja traceparent W3C (pseudo)

txt traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

PromQL - kilka dzienników i SLO (przykład)

high_error_logs = rate(log_events_total{service="payments-api",level="ERROR"}[5m])
5xx_rate = sum(rate(http_requests_total{service="payments-api",status=~"5.."}[5m])) / sum(rate(http_requests_total{service="payments-api"}[5m]))
alert if high_error_logs > 10 and 5xx_rate > 0.005

OpenAPI - nagłówki korelacji

yaml components:
parameters:
Traceparent:
name: traceparent in: header required: false schema: { type: string }

18) Wniosek

Silny obwód rejestrowania i śledzenia to porozumienie + dyscyplina: strukturalne dzienniki JSON, pojedynczy 'trace _ id', bezpieczne przetwarzanie PII, routing i zatrzymywanie nad strumieniami, a także bliskie połączenie z SLO, alert i rolki. Dokonaj przejścia od „zrzutu tekstów” do umów i utworów imprezowych, a diagnoza incydentów produkcyjnych stanie się szybka, przewidywalna i weryfikowalna.