Lógica y seguimiento de eventos

Lógica y seguimiento de eventos

1) Objetivo y marco

Los registros y los tracks son la base de la observación.
Los registros responden a «qué pasó» y «con qué contexto».
Los tracks responden a «dónde y por qué es lento/erróneo» en la ruta de consulta distribuida.

• Structured by default (JSON); Trace-first: cada registro de la ruta de acceso está enlazado a 'trace _ id '/' span _ id'.
• Mínimo ruido, máximo de señal: niveles, sempling, anti-cardinalidad.
• Seguridad y privacidad: enmascarar, editar, delimitar el acceso.
• Esquemas versionados de registros y eventos.

2) Taxonomía de eventos

1. Registros técnicos (runtime, errores, temporizadores de red, retraídas).

2. Eventos comerciales (registro, depósito, tasa, retiro, etapa KYC): son adecuados para análisis de productos e incidentes en rutas «monetarias».

3. Auditoría (quién/cuándo cambió algo: confecciones, accesos, banderas, límites) - Registro inmutable.

4. Seguridad (autenticación, escaladas de privilegios, banderas de sanciones/RR).

5. Infraestructura (K8s eventos, autoscaling, HPA/VPA, nodos/disco/red).

Para cada flujo, reglas individuales de retoque, indexación y acceso.

3) Registro estructural (referencia 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" }
}

Requisitos: esquema plano + adjuntos por dominio, campos obligatorios ('ts, level, service, env, trace_id, msg'), valores numéricos - números, no cadenas.

4) Niveles, cardinalidad y volumen

Niveles: 'DEBUG' (no en venta), 'INFO' (hechos empresariales), 'WARN' (anomalías),' ERROR '(errores),' FATAL '(tintes).
Cardinalidad: evite las claves arbitrarias/etiquetas dinámicas. No hay «id-in-key».
Sampling logs: rate-limit mensajes repetitivos; habilite 'DEBUG' sólo scoped y en el tiempo (flag feature).
Idempotencia: lógica 'idempotency _ key' para suprimir los eventos duplicados por los consumidores.

5) Privacidad y seguridad

Enmascarar PII/secretos en agentes (Fluent Bit/Vector): mapas de enmascaramiento por claves ('email', 'card',' token ',' authorization ').
Hash 'user _ key', mantenga sólo el contexto necesario (país, nivel KYC, tier VIP).
Separe el almacenamiento: caliente (búsqueda en línea) y frío (archivo sin PII/c contexto recortado).
Auditoría: append-only, almacenamiento de información WORM, acceso sólo least privilege.

6) Seguimiento: estándares y contexto

W3C Trace Context: encabezados 'traceparent '/' tracestate', más baggage para claves seguras (por ejemplo, 'tenant _ id', 'region').
Asociación de métricas y tracks: Exemplars - Pase 'trace _ id' a puntos de histogramas sampleados (acelera RCA).
Sampling: sempling básico 1-5% + dinámico «en errores/p95 lento» hasta 100% para consultas problemáticas.
Enlaces: para colas/sagas asíncronas, vincule los durmientes a través de 'links', no solo a través de 'parent'.

7) Recogida y enrutamiento

Agentes: Fluent Bit/Vector para registros; Exportación OTLP a OpenTelemetry Collector.
Coleccionista: puerta de enlace central (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) Herramientas: ejemplos de 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 → seguimiento de encabezados

nginx proxy_set_header traceparent $http_traceparent;
proxy_set_header tracestate $http_tracestate;

9) Registros como señal para alertas y acciones automáticas

Los patrones de error ('psp _ decline', 'fraud _ flag') se agregan y correlacionan con SLO.
Alertas en pattern-rate: "5xx por/withdraw> 0. 5% por 10m", "fraud_flag spike> + 200% de la básica".
Acciones automáticas: al iniciar la sesión 'withdrawals _ manual _ mode = true', active kill-switch a través de la plataforma de banderas.

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

10) Retoque, indexación, almacenamiento

Caliente: 7-14 días (investigación rápida).
Cálido: 30-90 días (tendencias, RCA).
Frío: 180-365 + (archivo, auditoría) - compresión, clases baratas, posiblemente sin búsqueda de texto completo.
Indexación: claves fijas ('service, env, level, event, trace_id, user. tenant_id'), la prohibición del índice «todo en fila».
Límites de tamaño de evento (por ejemplo, ≤ 32KB), trim/inferior: «extra en almacenamiento es enemigo de MTTR».

11) Auditoría e inmutabilidad

Los eventos de auditoría escriben en un hilo separado con las firmas/hashes, la hora del servidor, 'who/what/when/why', una referencia al ticket.
«¿Quién ha incluido la bandera de bonificaciones al 100% en el DE?» - la respuesta debe estar en 1-2 solicitudes.

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) Eventos comerciales y modelo de datos

• `event_type`, `event_id`, `occurred_at`, `actor`, `subject`, `amount`, `currency`, `status`, `idempotency_key`.
• Utilice Outbox y «at-least-once» con consumidores idempotentes.

13) Kubernetes y registros pipelinos

Agentes Sidecar/DaemonSet con búfer en disco (con interrupciones de red).
Anotaciones de sub para enrutamiento ('log. type`, `retention. tier`).
Los registros de controladores K8s se recopilan por separado (índice de clúster).

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

14) Anti-patrones

Los registros de cadena son «como tendrás que», la ausencia de 'trace _ id'.
PII/secretos en las guaridas, volcado payload entero.
Millones de claves únicas → indexación «detonada».
DEBUG en venta 24/7.
Mezcla de auditoría, seguridad y tecnólogos en un solo índice.
No hay ninguna política de retiro y prueba de recuperación del archivo.

15) Lista de verificación de implementación (0-45 días)

0-10 días

Activar W3C Trace Context en gateway/clientes, prueba de encabezados.
Traducir registros de aplicaciones a JSON, añadir 'trace _ id '/' span _ id'.
Impedir PII/secretos (enmascarar en el agente), aprobar la lista de campos.

11-25 días

Descomponer hilos: tech/biz/audit/security/infra, especificar retén y ACL.
Habilitar OTel Collector, hacer tail-sampling errores/consultas lentas.
Dashboards «Log Rate/Error by route» + Jump-to-trace (Exemplars).

26-45 días

Alertas por patrones de eventos y correlación con SLO.
Archivo/recuperación (prueba DR) para registros en frío.
Linter de circuitos de registro en CI, un contrato para eventos comerciales.

16) Métricas de madurez

Cobertura de solicitudes 'trace _ id' ≥ 95%.
La proporción de registros JSON ≥ el 99%.
Los incidentes encontrados por la vía «jump-to-trace» han sido resueltos <15 min (p50).
0 casos de PII en logs (escáner de fugas).
La retirada se cumple en todos los hilos (la auditoría se prueba automáticamente).

17) Apéndices: mini-snippets

W3C traceparent generación (pseudo)

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

PromQL - Conjunto de registros y SLO (ejemplo)

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 - encabezados de Corea

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

18) Conclusión

Un fuerte contorno de lógica y rastreo son los acuerdos + disciplina: registros JSON estructurales, un solo 'trace _ id', manejo PII seguro, enrutamiento y retoque por hilos, y un estrecho acoplamiento con SLO, alerting y retrocesos. Haga la transición de «basurero de texto» a contratos de eventos y rutas, y el diagnóstico de incidentes prod será rápido, predecible y verificable.