Оқиғаларды логикалау және трассалау

Оқиғаларды логикалау және трассалау

1) Мақсат және шеңбер

Логтар мен трейстер - бақылаудың іргетасы.
Логтар «не болды» және «қандай контексте» деп жауап береді.
Трестер сұрау салудың бөлінген жолында «қайда және неге баяу/қате» деп жауап береді.

• Structured by default (JSON); Trace-first: ыстық жолдағы әрбір лог 'trace _ id '/' span _ id' байланады.
• Шудың минимумы, сигналдың максимумы: деңгейлер, сэмплинг, анти-кардиналдық.
• Қауіпсіздік және құпиялылық: жасыру, редакциялау, қолжетімділікті шектеу.
• Логтар мен оқиғалардың нұсқаланған схемалары.

2) Оқиғалардың таксономиясы

1. Техникалық логтар (runtime, қателер, желілік таймауттар, ретрациялар).

2. Бизнес-оқиғалар (тіркеу, депозит, мөлшерлеме, қорытынды, KYC-кезең) - «ақша» жолдары бойынша азық-түлік талдауы мен тосын оқиғалар үшін жарамды.

3. Аудит (кім/қашан өзгертті: конфигтер, қолжетімділік, жалаулар, лимиттер) - өзгермейтін журнал.

4. Қауіпсіздік (аутентификация, артықшылықтарды күшейту, санкциялар/РЕР-жалаулар).

5. Инфрақұрылым (K8s events, autoscaling, HPA/VPA, тораптар/диск/желі).

Әрбір ағын үшін - ретеншн, индекстеу және қол жеткізудің жеке ережелері.

3) Құрылымдық лог (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" }
}

Талаптар: тегіс схема + домендер бойынша тіркемелер, міндетті өрістер ('ts, level, service, env, trace_id, msg'), сандық мәндер - жолдармен емес, сандармен.

4) Деңгейлер, түбегейлілік және көлем

Деңгейлері: 'DEBUG' (сынамада емес), 'INFO' (бизнес-фактілер), 'WARN' (аномалиялар), 'ERROR' (қателер), 'FATAL' (бояулар).
Түбегейлі: еркін кілттерді/динамикалық label 'дерді болдырмаңыз. Кілтте «id» жоқ.
Логтардың сэмплингі: rate-limit қайталанатын хабарлар; 'DEBUG' дегенді тек scoped және уақыт бойынша қосыңыз (feature flag).
Сәйкестік: Тұтынушылардың қайталанған оқиғаларын басу үшін 'idempotency _ key' логинін орнатыңыз.

5) Құпиялылық және қауіпсіздік

PII/құпияларды агенттерде жасырыңыз (Fluent Bit/Vector): кілттер бойынша жасыру карталары ('email', 'card', 'token', 'authorization').
'user _ key' деп хештеңіз, тек қажетті мәтінмәнді ұстаңыз (ел, KYC-деңгей, VIP-tier).
Қоймаларды бөліңіз: жылы (жедел іздеу) және суық (PII/c қысқартылған мәтінмен мұрағат).
Аудит - append-only, WORM-сақтау орны, қолжетімділік least privilege қағидаты бойынша ғана.

6) Трассалау: стандарттар мен контекст

W3C Trace Context: 'traceparent '/' tracestate', плюс қауіпсіз кілттер үшін baggage тақырыптары (мысалы, 'tenant _ id', 'region').
Метриктер мен трестердің байланысы: Exemplars - 'trace _ id' дегенді гистограммалардың жинақталған нүктелеріне жіберіңіз (RCA жылдамдатады).
Sampling: негізгі сэмплинг 1-5% + динамикалық «қателер/баяу p95» проблемалық сұраулар үшін 100% дейін.
Links: асинхронды кезектер/сағдар үшін 'parent' арқылы ғана емес, 'links' арқылы ұйықтатыңыз.

7) Жинау және бағыттау

Агенттер: Логтар үшін Fluent Bit/Vector; OTLP - OpenTelemetry Collector бағдарламасына экспорттау.
Collector: орталық шлюз (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) Аспаптау: SDK мысалдары

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. 4 NGINX → тақырып трассировкасы

nginx proxy_set_header traceparent $http_traceparent;
proxy_set_header tracestate $http_tracestate;

9) Алерталар мен авто-әрекеттер үшін сигнал ретінде логтар

Қате үлгілер ('psp _ decline', 'fraud _ flag') SLO-мен біріктіріп, корреляциялаңыз.
Pattern-rate: "5xx бойынша/withdraw> 0. 10 м үшін 5%", "fraud_flag spike> + 200% базалық".
Авто-әрекеттер: 'withdrawals _ manual _ mode = true' логында жалаулар платформасы арқылы kill-switch қосыңыз.

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

10) Ретеншн, индекстеу, сақтау

Ыстық: 7-14 күн (жедел тергеу).
Жылы: 30-90 күн (трендтер, RCA).
Суық: 180-365 + (мұрағат, аудит) - қысу, арзан сыныптар, толық мәтінді іздеусіз болуы мүмкін.
Индекстеу: тіркелген кілттер ('service, env, level, event, trace_id, user. tenant_id'), «барлығы қатарынан» индексіне тыйым салу.
Оқиғаның мөлшеріне арналған лимиттер (мысалы, 32KB ≤), трим/төменнен: «storage артық - MTTR жауы».

11) Аудит және өзгермеу

Аудит оқиғаларын қолтаңбалармен/хэштермен, серверлік уақытпен, 'who/what/when/why', тикетке сілтемемен жеке ағынмен жазыңыз.
«DE-де 100% бонус жалауын кім қосқан?» - жауап 1-2 сұрауда болуы тиіс.

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) Бизнес-оқиғалар және деректер моделі

• `event_type`, `event_id`, `occurred_at`, `actor`, `subject`, `amount`, `currency`, `status`, `idempotency_key`.
• Демпотентті тұтынушылармен Outbox және «at-least-once» пайдаланыңыз.

13) Kubernetes және pipeline логтар

Sidecar/DaemonSet дискіге буфері бар агенттер (желілік үзілістер кезінде).
Бағыттау үшін тақталар аңдатпалары ('log. type`, `retention. tier`).
K8s-бақылаушылардың логтарын бөлек жинаңыз (кластерлік индекс).

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

14) Қарсы үлгілер

«Қажет болғанда» жол логтары, 'trace _ id' жоқ.
PII/журналдардағы құпиялар, дампалар тұтастай payload.
Миллиондаған бірегей кілттер → «жарылған» индекстеу.
DEBUG өнімдегі 24/7.
Аудитті, қауіпсіздікті және техлогтарды бір индекске араластыру.
Ретеншн саясаты мен мұрағаттан қалпына келтіру тесті жоқ.

15) Енгізу чек-парағы (0-45 күн)

0-10 күн

W3C Trace Context бағдарламасын gateway/клиенттерде қосу, тақырыптар жүгірісі.
JSON бағдарламасына аудару, 'trace _ id '/' span _ id' қосу.
PII/құпияларға тыйым салу (агентте бүркемелеу), өрістер тізімін бекіту.

11-25 күн

Ағындарды бөлу: tech/biz/audit/security/infra, ретеншн және ACL орнату.
OTel Collector бағдарламасын қосу, қателерді/баяу сұрауларды tail-sampling жасау.
«Log Rate/Error by route» + Jump-to-trace (Exemplars) дашбордтары.

26-45 күн

Оқиғалар үлгісі бойынша алерттар және SLO-мен корреляция.
Суық логтар үшін архив/қалпына келтіру (DR-тест).
CI логтар схемасының линтері, бизнес-оқиғаларға арналған келісімшарт.

16) Жетілу метрикасы

'trace _ id' сұрауларын жабу 95% ≥.
JSON логының үлесі ≥ 99%.
via «jump-to-trace» табылған инциденттер <15 мин (p50) шешілді.
Логтарда PII 0 жағдайы (ағу сканері).
Ретеншн барлық ағындар бойынша сақталған (аудитті автоматты түрде дәлелдейміз).

17) Қосымшалар: шағын сниппеттер

W3C traceparent генерациясы (жалған)

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

PromQL - логтар мен SLO байланысы (мысал)

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 - Кореляциялық тақырыптар

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

18) Қорытынды

Логирлеу мен трассирлеудің күшті контуры - бұл келісімдер + тәртіп: құрылымдық JSON-логтар, бірыңғай 'trace _ id', PII қауіпсіз өңдеу, бағыттау және ағындар бойынша ретеншн, сондай-ақ SLO-мен, алертингпен және кері қайтумен тығыз байланысу. «Мәтіндер үйіндісінен» оқиғалар мен трассалардың келісімшарттарына көшіңіз және прод-инциденттерді диагностикалау жылдам, болжамды және тексерілетін болады.