Evenimente de logare și urmărire

Evenimente de logare și urmărire

1) Scop și cadru

Jurnalele și traseele sunt baza observabilității.
Jurnalele răspund la „ce sa întâmplat” și „cu ce context”.
Urmele răspund la „unde și de ce încet/eronat” într-o cale de interogare distribuită.

• Structurat în mod implicit (JSON); Trace-first: fiecare jurnal de pe calea fierbinte este legat de 'trace _ id'/' span _ id'.
• Zgomot minim, semnal maxim: niveluri, prelevare de probe, anti-cardinalitate.
• Securitate și confidențialitate: mascare, editare, control acces.
• Diagrame versionate de busteni si evenimente.

2) Taxonomia evenimentelor

1. Jurnale tehnice (runtime, erori, timeout-uri de rețea, retroys).

2. Evenimente de afaceri (înregistrare, depozit, rată, retragere, etapa KYC) - potrivite pentru analiza produselor și incidente de-a lungul căilor „bani”.

3. Auditul (cine/când a schimbat ce: configurații, accesări, steaguri, limite) este un jurnal neschimbabil.

4. Securitate (autentificare, escaladare privilegiu, sancțiune/steaguri PEP).

5. Infrastructură (evenimente K8s, autoscaling, HPA/VPA, noduri/disc/rețea).

Pentru fiecare flux - reguli separate pentru retenție, indexare și acces.

3) Jurnal structural (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" }
}

Cerințe: sistem plat + atașamente pe domenii, câmpuri obligatorii ('ts, level, service, env, trace_id, msg'), valori numerice - numere, nu șiruri.

4) Niveluri, cardinalitate și domeniul de aplicare

Niveluri: „DEPANARE” (nu în vânzări), „INFO” (fapte de afaceri), „AVERTIZARE” (anomalii), „EROARE” (erori), „FATAL” (accidente).
Cardinalitate: evitați cheile arbitrare/etichetele dinamice. Nu „id-in-cheie”.
Jurnalele de eșantionare: mesaje repetate cu limită de rată; activați „DEPANARE” numai scoped și în timp (feature flag).
Idempotency: Log 'idempotency _ key' pentru a suprima evenimentele duplicate de către consumatori.

5) Confidențialitate și securitate

Masca PII/secrete pe agenți (Fluent Bit/Vector): carduri de mascare cheie ("e-mail", "card'," token "," autorizare ").
Hash 'user _ key', țineți doar contextul necesar (țară, nivel KYC, nivel VIP).
Depozite separate: cald (căutare online) și rece (arhivă fără PII/cu un context dezbrăcat).
Audit - numai adăugați, stocare WORM, acces numai pe principiul celui mai mic privilegiu.

6) Urmărirea: standarde și context

Context de urmărire W3C: anteturi „traceparente ”/„ tracestate”, plus bagaje pentru chei securizate (de ex. 'tenant _ id',' regiune ').
Link metrics and traces: Exemplars - pass' trace _ id' to the sampling points of the histograms (accelerează RCA).
Eșantionare: eșantionare de bază 1-5% + dinamică „pe eroare/lent p95” până la 100% pentru interogări de probleme.
Link-uri: Pentru cozi asincrone/sagas, link-ul se întinde prin „link-uri”, nu doar prin „părinte”.

7) Colectarea și rutarea

Agent: Fluent Bit/Vector pentru busteni; Exportul OTLP către OpenTelemetry Collector.
Colector: gateway central (lot/transforma/filtru/rutare).

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) Instrumentație: exemple SDK

8. 1 Nod. 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 → urmărirea antetului

nginx proxy_set_header traceparent $http_traceparent;
proxy_set_header tracestate $http_tracestate;

9) Jurnalele ca semnal pentru alerte și auto-acțiuni

Modelele eronate ('psp _ decline', 'fraud _ flag') se agregă și se corelează cu SLO.

Alerte privind rata de tipar: "5xx prin/retragere> 0. 5% pe 10m", "fraud_flag spike> + 200% din bază"

Auto-acțiuni: dacă jurnalul este 'withdrawals _ manual _ mode = true', activați kill-switch prin platforma de pavilion.

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

10) Retenție, indexare, stocare

Fierbinte: 7-14 zile (investigație operațională).
Cald: 30-90 zile (tendințe, RCA).
Rece: 180-365 + (arhivă, audit) - compresie, clase ieftine, eventual fără căutare full-text.
Indexare: chei fixe ('service, env, level, event, trace_id, user. tenant_id'), interzicerea indicelui „totul la rând”.
Limitele dimensiunii evenimentului (de exemplu, ≤ 32KB), tăiați/jos: „extra în depozitare este inamicul MTTR”.

11) Audit și imutabilitate

Scrieți evenimente de audit într-un flux separat cu semnături/hashes, timpul serverului, „cine/ce/când/de ce”, un link către bilet.
„Cine a inclus steagul bonus 100% în DE?” - răspunsul trebuie să fie în 1-2 cereri.

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) Evenimente de afaceri și modelul de date

• 'event _ type', 'event _ id',' happened _ at ',' actor ',' subject ',' cuantum ',' valute ',' status ',' idempotency _ key '.
• Utilizați Outbox și „cel puțin o dată” cu consumatori idempotenți.

13) Kubernete și jurnalele de conducte

Agenți Sidecar/DaemonSet cu tampon pe disc (în timpul întreruperilor de rețea).
Adnotări de tampoane pentru rutare ('log. tip ',' retenţie. nivelul ").
Colecta jurnalele de controlere K8s separat (cluster index).

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

14) Anti-modele

Jurnalele de coarde „după cum este necesar”, absența 'trace _ id'.
PII/secrete în jurnalele, haldele de sarcină utilă în întregime.
Milioane de chei unice → „explodat” indexarea.
DEPANARE în vânzare 24/7.
Amestecarea auditului, securității și tehnologilor într-un singur index.
Nu există nici o politică de retenție și nici un test de recuperare de rezervă.

15) Lista de verificare a implementării (0-45 zile)

0-10 zile

Activați contextul de urmărire W3C pe gateway/clienți, anteturi de redirecționare.
Traduceți jurnalele de aplicații în JSON, adăugați 'trace _ id'/' span _ id'.
Refuzați PII/secretele (mascarea pe agent), aprobați lista câmpurilor.

11-25 zile

Fluxuri separate: tech/biz/audit/securitate/infra, retenție set și ACL.
Activați OTel Collector, erori de eșantionare a cozii/interogări lente.
Tablouri de bord „Log Rate/Eroare pe rută” + Jump-to-trace (Exemplare).

26-45 zile

Alerte de model eveniment și corelație cu SLO.
Arhivă/restaurare (test DR) pentru jurnalele reci.
Linter de diagrame jurnal în CI, contract pentru evenimente de afaceri.

16) Valorile maturității

'Acoperire trace _ id' request ≥ 95%.
Ponderea jurnalelor JSON ≥ de 99%.
Incidentele constatate prin „salt-to-trace” s-au rezolvat <15 min (p50).
0 cazuri PII în jurnale (scaner de scurgeri).
Retenția este observată pentru toate fluxurile (dovedim auditul automat).

17) Aplicații: Mini fragmente

Generație traceparentă W3C (pseudo)

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

PromQL - o grămadă de jurnale și SLO (exemplu)

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 - anteturi de corelare

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

18) Concluzie

Un circuit puternic de logare și urmărire este un acord + disciplină: jurnale structurale JSON, o singură "trace _ id', procesare PII sigură, rutare și păstrare peste fluxuri, precum și o legătură strânsă cu SLO, alertă și rollback-uri. Faceți trecerea de la „groapa de texte” la contracte de evenimente și piese, iar diagnosticul incidentelor de producție va deveni rapid, previzibil și verificabil.