Protokollierung und Verfolgung von Ereignissen

Protokollierung und Verfolgung von Ereignissen

1) Ziel und Rahmen

Logs und Traces sind die Grundlage der Beobachtbarkeit.
Die Protokolle antworten auf „was passiert ist“ und „mit welchem Kontext“.
Traces beantworten das „Wo und Warum langsam/falsch“ im verteilten Anfragepfad.

• Structured by default (JSON); Trace-first: Jedes Log im Hot Path ist an 'trace _ id '/' span _ id' gebunden.
• Minimales Rauschen, maximales Signal: Pegel, Sampling, Anti-Kardinalität.
• Sicherheit und Privatsphäre: Maskieren, Bearbeiten, Abgrenzung des Zugangs.
• Versionierte Protokoll- und Ereignisschemata.

2) Taxonomie der Ereignisse

1. Technische Protokolle (Laufzeit, Fehler, Netzwerk-Timeouts, Retrays).

2. Geschäftsereignisse (Registrierung, Einzahlung, Wette, Auszahlung, KYC-Phase) - geeignet für Produktanalysen und Vorfälle auf „monetären“ Wegen.

3. Auditing (wer/wann hat was geändert: Configs, Zugriffe, Flags, Limits) ist ein unveränderliches Protokoll.

4. Sicherheit (Authentifizierung, Eskalationen von Privilegien, Sanktions-/PP-Flags).

5. Infrastruktur (K8s Events, Autoscaling, HPA/VPA, Knoten/Laufwerk/Netzwerk).

Für jeden Thread gibt es separate Regeln für Retenche, Indexierung und Zugriff.

3) Strukturprotokoll (JSON-Referenz)

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" }
}

Anforderungen: flaches Schema + Anhänge für Domänen, obligatorische Felder ('ts, level, service, env, trace_id, msg'), numerische Werte - Zahlen, nicht Zeilen.

4) Ebenen, Kardinalität und Umfang

Ebenen: 'DEBUG' (nicht in der Produktion), 'INFO' (geschäftliche Fakten), 'WARN' (Anomalien), 'ERROR' (Fehler), 'FATAL' (Abstürze).
Kardinalität: Vermeiden Sie beliebige Schlüssel/dynamische Labels. Kein „Id-in-Key“.
Log-Sampling: Rate-Limit-Nachrichten; Aktivieren Sie' DEBUG 'nur scoped und zeitlich (feature flag).
Idempotenz: Loggen Sie' idempotency _ key', um doppelte Ereignisse durch Verbraucher zu unterdrücken.

5) Privatsphäre und Sicherheit

Tarnen Sie PII/Geheimnisse auf Agenten (Fluent Bit/Vector): Schlüsselmaskierungskarten ('email', 'card', 'token', 'authorization').
Hash 'user _ key', halten Sie nur den gewünschten Kontext (Land, KYC-Level, VIP-Tier).
Trennen Sie die Speicher: warm (Online-Suche) und kalt (Archiv ohne PII/c durch den Kontext abgeschnitten).
Audit - nur Append, WORM-Speicher, Zugriff nur nach dem Prinzip des Least Privilege.

6) Tracing: Standards und Kontext

W3C Trace Context: Überschriften 'traceparent '/' tracestate', plus baggage für sichere Schlüssel (z.B. 'tenant _ id', 'region').
Verknüpfung von Metriken und Traces: Beispiele - Übergeben Sie' trace _ id 'an die Sample-Punkte der Histogramme (beschleunigt den RCA).
Sampling: Basis-Sampling 1-5% + dynamisch „auf Fehler/slow p95“ bis zu 100% für problematische Abfragen.
Links: Bei asynchronen Warteschlangen/Sagen verbinden Sie die Spans über 'links' und nicht nur über 'parent'.

7) Sammlung und Routing

Agenten: Fluent Bit/Vector für Protokolle; OTLP-Export nach OpenTelemetry Collector.
Collector: zentrales Gateway (batch/transform/filter/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) Instrumentierung: SDK-Beispiele

8. 1 Node. 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. NGINX- 4 → Header-Tracing

nginx proxy_set_header traceparent $http_traceparent;
proxy_set_header tracestate $http_tracestate;

9) Logs als Signal für Alerts und Auto-Aktionen

Fehlerhafte Muster ('psp _ decline', 'fraud _ flag') aggregieren und korrelieren mit dem SLO.
Alerts auf Muster-Rate: "5xx von/withdraw> 0. 5% für 10m", "fraud_flag spike> + 200% der Basis".
Auto-Aktionen: Mit dem Log 'withdrawals _ manual _ mode = true' aktivieren Sie den Kill-Switch über die Flag-Plattform.

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

10) Retention, Indexierung, Lagerung

Heiß: 7-14 Tage (operative Untersuchung).
Warm: 30-90 Tage (Trends, RCA).
Kalt: 180-365 + (Archiv, Audit) - Komprimierung, günstige Klassen, eventuell ohne Volltextsuche.
Indizierung: feste Schlüssel ('service, env, level, event, trace_id, user. tenant_id') Verbot des Index „nur in Folge“.
Limits für Event-Größe (z.B. ≤ 32KB), Trim/Bottom: „Extra in Storage - Feind von MTTR“.

11) Audit und Unveränderlichkeit

Audit-Ereignisse schreiben Sie in einem separaten Thread mit Signaturen/Hashes, Serverzeit, 'who/what/when/why', Link zum Ticket.
„Wer hat die Bonus-Flagge zu 100% in DE aufgenommen?“ - die Antwort sollte in 1-2 Anfragen sein.

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) Geschäftsereignisse und Datenmodell

• `event_type`, `event_id`, `occurred_at`, `actor`, `subject`, `amount`, `currency`, `status`, `idempotency_key`.
• Verwenden Sie Outbox und „at-least-once“ mit idempotenten Verbrauchern.

13) Kubernetes und Pipeline-Logs

Sidecar/DaemonSet-Agenten mit Puffer auf Festplatte (bei Netzwerkunterbrechungen).
Anmerkungen der Pods für das Routing ('log. type`, `retention. tier`).
Sammeln Sie die Protokolle der K8s-Controller separat (Cluster-Index).

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

14) Anti-Muster

String-Protokolle „wie Sie müssen“, das Fehlen von 'trace _ id'.
PII/Geheimnisse in den Protokollen, Payload-Dumps in ihrer Gesamtheit.
Millionen von einzigartigen Schlüsseln → „explodierte“ Indizierung.
DEBUG in der Produktion 24/7.
Mischen Sie Audit, Sicherheit und Techlogs in einem Index.
Es gibt keine Retention-Richtlinie und keinen Wiederherstellungstest aus dem Archiv.

15) Implementierung Checkliste (0-45 Tage)

0-10 Tage

Aktivieren Sie W3C Trace Context in Gateway/Clients, Überschriftenumbruch.
Anwendungsprotokolle in JSON übersetzen, 'trace _ id '/' span _ id' hinzufügen.
PII/Secrets verbieten (Maskierung am Agenten), Feldliste genehmigen.

11-25 Tage

Threads auflösen: tech/biz/audit/security/infra, retention und ACL einstellen.
Aktivieren Sie OTel Collector, machen Sie tail-sampling Fehler/langsame Anfragen.
Dashboards „Log Rate/Error by route“ + Jump-to-trace (Beispiele).

26-45 Tage

Alerts durch Ereignismuster und Korrelation mit SLO.
Archiv/Wiederherstellung (DR-Test) für kalte Protokolle.
Linter Logdiagramme in CI, Vertrag für Business-Events.

16) Reifegradkennzahlen

Die Abdeckung der Anfragen „trace _ id“ ≥ 95%.
Der Anteil der JSON-Logs ≥ 99%.
Die über „jump-to-trace“ gefundenen Vorfälle wurden <15 min gelöst (p50).
0 PII-Fälle in den Protokollen (Leck-Scanner).
Die Retention wird bei allen Streams eingehalten (Audit wird automatisch nachgewiesen).

17) Anwendungen: Mini-Schnipsel

W3C traceparent Erzeugung (Pseudo)

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

PromQL - Logbündel und SLO (Beispiel)

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 - Korrelative Header

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

18) Schlussfolgerung

Eine starke Log- und Trace-Schleife ist Konventionen + Disziplin: strukturelle JSON-Logs, eine einzige' trace _ id', sichere PII-Verarbeitung, Routing und Retention nach Threads sowie eine enge Verknüpfung mit SLO, Alerting und Pullbacks. Machen Sie den Übergang von der „Deponie von Texten“ zu Ereignis- und Trassenverträgen und die Diagnose von Prod-Vorfällen wird schnell, vorhersehbar und überprüfbar.