ثبت و ردیابی رویدادها

ثبت و ردیابی رویدادها

1) هدف و قاب

لاگ ها و دنباله ها پایه و اساس مشاهده پذیری هستند.
گزارش ها به «چه اتفاقی افتاده» و «با چه زمینه ای» پاسخ می دهند.
Traces به «کجا و چرا به آرامی/به اشتباه» در یک مسیر پرس و جو توزیع شده پاسخ می دهند.

• ساختار به طور پیش فرض (JSON) ؛ Trace-first: هر ورودی در مسیر داغ به 'trace _ id '/' span _ id' محدود می شود.
• حداقل نویز، حداکثر سیگنال: سطح، نمونه برداری، ضد کاردینالیتی.
• امنیت و حریم خصوصی: پوشش، ویرایش، کنترل دسترسی.
• نمودار نسخه از سیاهههای مربوط و حوادث.

2) طبقه بندی رویدادها

1. سیاهههای فنی (زمان اجرا، خطاها، زمان بندی شبکه، بازپرداخت).

2. رویدادهای تجاری (ثبت نام، واریز، نرخ، برداشت، مرحله KYC) - مناسب برای تجزیه و تحلیل محصول و حوادث در مسیرهای «پول».

3. حسابرسی (چه کسی/چه زمانی تغییر کرد: پیکربندی ها، دسترسی ها، پرچم ها، محدودیت ها) یک مجله غیر قابل تغییر است.

4. امنیت (احراز هویت، افزایش امتیاز، تحریم/پرچم PEP).

5. زیرساخت (رویدادهای K8s، 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، سطح، خدمات، env، trace_id، msg')، مقادیر عددی - اعداد، رشته ها نیست.

4) سطوح، کاردینالیتی و دامنه

سطوح: «DEBUG» (نه در فروش)، «INFO» (حقایق کسب و کار)، «هشدار» (ناهنجاری ها)، «ERROR» (خطاها)، «FATAL» (سقوط).
کاردینالیتی: اجتناب از کلید های دلخواه/برچسب های پویا. بدون «شناسه در کلید».
سیاهههای مربوط به نمونه برداری: پیام های تکراری محدود ؛ فعال کردن 'DEBUG' تنها محدوده و در زمان (پرچم ویژگی).
Idempotency: «idempotency _ key» را برای سرکوب رویدادهای تکراری توسط مصرف کنندگان وارد کنید.

5) حریم خصوصی و امنیت

ماسک PII/secrets on agents (Fluent Bit/Vector): کارت های مخفی کردن کلید («ایمیل»، «کارت»، «نشانه»، «مجوز»).
«user _ key» هش، فقط زمینه مورد نیاز (کشور، سطح KYC، سطح VIP) را نگه می دارد.
انبارهای جداگانه: گرم (جستجوی آنلاین) و سرد (آرشیو بدون PII/با یک زمینه خالی).
حسابرسی - فقط اضافه کردن، ذخیره سازی WORM، دسترسی تنها بر اساس اصل حداقل امتیاز.

6) ردیابی: استانداردها و زمینه

زمینه ردیابی W3C: هدر های «traceparent »/« tracestate»، به علاوه چمدان برای کلیدهای امن (به عنوان مثال 'tenant _ id', 'region').
معیارهای لینک و آثار: نمونه - عبور 'trace _ id' به نقاط نمونه برداری از هیستوگرام (شتاب RCA).
نمونه برداری: نمونه برداری اولیه 1-5٪ + پویا «در خطا/آهسته p95» تا 100٪ برای نمایش داده شد مشکل.
لینک ها: برای صف های ناهمزمان/ساگا، پیوند از طریق «لینک ها»، نه فقط «پدر و مادر».

7) جمع آوری و مسیریابی

عامل: بیت/بردار روان برای سیاهههای مربوط ؛ OTLP به OpenTelemetry Collector صادر می شود.
جمع کننده: دروازه مرکزی (دسته/تبدیل/فیلتر/مسیریابی).

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 گره. جی اس (پینو + 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 جاوا (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 پایتون (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 است.

هشدارها در مورد نرخ الگو: "5xx by/withdraw> 0. 5٪ در هر 10m"، "fraud_flag سنبله> + 200٪ از پایه"

اقدامات خودکار: اگر log '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 + (آرشیو، ممیزی) - فشرده سازی، کلاس های ارزان، احتمالا بدون جستجوی کامل متن.
نمایه سازی: کلید ثابت ('سرویس، ENV، سطح، رویداد، trace_id، کاربر. tenant_id')، ممنوعیت شاخص «همه چیز در یک ردیف».
محدودیت اندازه رویداد (به عنوان مثال، ≤ 32KB)، تر و تمیز/پایین: «اضافی در ذخیره سازی دشمن MTTR است».

11) حسابرسی و تغییر ناپذیری

رویدادهای حسابرسی را در یک جریان جداگانه با امضا/هش، زمان سرور، «چه کسی/چه/چه زمانی/چرا»، یک لینک به بلیط بنویسید.
«چه کسی شامل پرچم جایزه 100٪ در DE ؟» پاسخ باید در 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'، 'رخ داده در'، 'بازیگر'، 'موضوع'، 'مقدار'، 'ارز'، 'وضعیت'، 'idemotency _ key'.
• از Outbox و «حداقل یک بار» با مصرف کنندگان بی نظیر استفاده کنید.

13) Kubernetes و سیاهههای مربوط به خط لوله

عوامل Sidecar/DaemonSet با بافر به دیسک (در طول وقفه های شبکه).
حاشیه نویسی از پد برای مسیریابی ("ورود به سیستم. تایپ کنید «،» نگهداری. ردیف ').
جمع آوری سیاهههای مربوط از کنترل K8s به طور جداگانه (شاخص خوشه).

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

14) ضد الگوهای

«در صورت لزوم»، عدم وجود «trace _ id».
PII/اسرار در سیاهههای مربوط، تخلیه محموله در تمامیت خود.
میلیون ها کلید منحصر به فرد → نمایه سازی «منفجر شد».
DEBUG در فروش 24/7.
ترکیب ممیزی، امنیت و تکنولوژیست به یک شاخص.
هیچ سیاست نگهداری و هیچ تست بازیابی پشتیبان وجود ندارد.

15) چک لیست پیاده سازی (0-45 روز)

0-10 روز

فعال کردن زمینه ردیابی W3C در دروازه/مشتریان، حمل و نقل هدر.
ترجمه سیاهههای مربوط برنامه به JSON، اضافه کردن 'trace _ id '/' span _ id'.
PII/اسرار را انکار کنید (پوشش روی عامل)، لیست فیلدها را تأیید کنید.

11-25 روز

جریانهای جداگانه: tech/biz/audit/security/infra، تنظیم نگهداری و ACL.
فعال کردن OTel Collector، خطاهای نمونه برداری دم/نمایش داده شد آهسته.
داشبورد «نرخ ورود/خطا از طریق مسیر» + پرش به ردیابی (نمونه).

26-45 روز

هشدار الگوی رویداد و همبستگی با SLO.
بایگانی/بازیابی (تست DR) برای سیاهههای مربوط به سرد.
Linter از نمودار ورود به سیستم در CI، قرارداد برای رویدادهای کسب و کار.

16) معیارهای بلوغ

پوشش ردیابی _ شناسایی مجدد ≥ 95٪.
سهم JSON 99٪ ≥.
رخدادهای یافتشده از طریق «پرش به ردیابی» <15 min (p50).
0 موارد PII در سیاهههای مربوط (اسکنر نشت).
نگهداری برای تمام جریان ها مشاهده می شود (ما حسابرسی را به طور خودکار ثابت می کنیم).

17) برنامه های کاربردی: قطعه های کوچک

نسل ردیاب W3C (شبه)

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 ساختاری، یک «ردیابی _ id»، پردازش PII امن، مسیریابی و نگهداری از جریان، و همچنین ارتباط نزدیک با SLO، هشدار و عقب نشینی. انتقال از «تخلیه متون» به قراردادهای رویداد و آهنگ ها، و تشخیص حوادث تولید سریع، قابل پیش بینی و قابل تایید خواهد بود.