Logar e traçar eventos

Logar e traçar eventos

1) Alvo e moldura

Logs e trailers são as fundações da observabilidade.
Os logs respondem a «o que aconteceu» e «com que contexto».
Os trailers respondem a «onde e porquê devagar/erradamente» no caminho distribuído da consulta.

• Structured by default (JSON); Trace-first: Cada logo no caminho quente é ligado a 'trace _ id '/' span _ id'.
• Mínimo ruído, máximo de sinal, nível, sampling, anti-cardealidade.
• Segurança e privacidade: camuflagem, edição, separação de acesso.
• Circuitos de logs e eventos versionizados.

2) Taxonomia de eventos

1. Logs técnicos (runtime, erros, temporizações de rede, retais).

2. Eventos de negócios (registro, depósito, taxa, conclusão, fase KYC) - adequados para analistas de alimentos e incidentes por caminhos «em dinheiro».

3. A auditoria (quem/quando mudou o quê: configs, acessos, bandeiras, limites) é um registro imutável.

4. Segurança (autenticação, elevação de privilégios, sanção/bandeiras de RER).

5. Infraestrutura (K8s events, autoscaling, HPA/VPA, nódulos/disco/rede).

Para cada fluxo, as regras de retenção, indexação e acesso são individuais.

3) Logos estruturais (referência 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 + anexos por domínio, campos obrigatórios ('ts, level, service, end, trace _ id, msg'), números, números, não linhas.

4) Níveis, cardealidade e volume

Os níveis são 'DEBUG', 'INFO', 'WARN', 'ERRO', 'FATAL'.
Cardinalício: evite chaves arbitrárias/label 'ov dinâmico. Nada de identificação.
Sampling logs: rate-limit mensagens repetidas; inclua 'DEBUG' apenas scoped e por tempo (função flag).
Idempotidade: Logue 'idempotency _ key' para suprimir os eventos duplicados pelos consumidores.

5) Privacidade e segurança

Disfarce PII/segredos em agentes: cartões de camuflagem por chave ('email', 'card', 'token', 'autorization').
Hasteie 'user _ key' e mantenha apenas o contexto necessário (país, nível KYC, VIP-tier).
Divida o armazenamento: quente (busca em linha) e frio (arquivo sem PII/C em contexto cortado).
Auditoria - append-only, armazenamento WORM, acesso somente least privege.

6) Rastreamento: padrões e contexto

W3C Trace Context: Títulos 'traceparent '/' tracestate', além de baggage para chaves seguras (por exemplo, 'tenant _ id', 'region').
Conexão entre métricas e trailers: Excempars - transfira 'trace _ id' para os pontos de histograma sampleados (acelera RCA).
Sampling: sampling básico 1-5% + dinâmico «com erros/p95 lento» a 100% para consultas problemáticas.
Links: Para as filas asinhrônicas/sagas, ligue spans através de 'links', não apenas através de 'parent'.

7) Coleta e rotação

Agentes: Fluent Bit/Vector para logs; Exportação OTLP para o OpenTelemetry Colector.
Captor: gateway central (batch/transfer/filter/roting).

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) Ferramentas: exemplos 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 → traçar cabeçalhos

nginx proxy_set_header traceparent $http_traceparent;
proxy_set_header tracestate $http_tracestate;

9) Logs como sinal para alertas e ação automática

As patternes erradas ('psp _ decline', 'fraud _ flag') agregam e correlacionem com o SLO.
Alerts em pattern-rate: "5xx por/withdraw> 0. 5% por 10m", "fraud _ flag spike> + 200% da base".
Ação automática: Quando o logs 'withdrawals _ manual _ modo = true', inclua o kill-switch através da plataforma de bandeiras.

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

10) Retenschn, indexação, armazenamento

Quente, 7-14 dias (investigação rápida).
Quente: 30-90 dias (tendências, RCA).
Frio: 180-365 + (arquivo, auditoria) - Compactação, classes baratas, talvez sem pesquisa de texto completo.
Indexação: chaves fixas ('service, end, level, event, trace _ id, user. tenant _ id '), proibição do índice de «tudo».
Limites para o tamanho do evento (por exemplo, ≤ 32KB), trim/inferior: «Excesso de armazenamento - inimigo MTTR».

11) Auditoria e imutabilidade

Os eventos de auditoria escrevem em um fluxo separado com assinaturas/hash, tempo de servidor, 'who/what/when/why', referindo-se ao tíquete.
«Quem incluiu 100% da bandeira de bónus em DE?» - a resposta deve estar em 1-2 solicitações.

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 de negócios e modelo de dados

• `event_type`, `event_id`, `occurred_at`, `actor`, `subject`, `amount`, `currency`, `status`, `idempotency_key`.
• Use o Outbox e o «at-least-once» com consumidores idempotados.

13) Kubernetes e logs pipeline

Sidecar/DaemonSet agentes com buffer para disco (em intervalos de rede).
Anotações de substrato de rotação ('not. type`, `retention. tier`).
Colecione os logs dos controladores K8s separadamente (índice de cluster).

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

14) Anti-pattern

Logs de linha «como for necessário», falta de «trace _ id».
PII/segredos em logs, dampas payload inteira.
Milhões de chaves únicas. Uma indenização «detonada».
DEBUG em venda 24/7.
Mistura auditoria, segurança e técnico em um único índice.
Não há política de retenção ou teste de recuperação do arquivo.

15) Folha de cheque de implementação (0-45 dias)

0-10 dias

Incluir o W3C Trace Context em gateway/clientes, o espaço de cabeçalho.
Traduzir logs de anexos para JSON, adicionar 'trace _ id '/' span _ id'.
Proibir PII/segredos (camuflar no agente), aprovar a lista de campos.

11-25 dias

Execute os fluxos: tech/biz/auditoria/segurança/infra, defina retalhos e LCA.
Incluir OTel Colector, fazer tail-sampling erros/consultas lentas.
Dashboards «Greg Rate/Erro by road» + Jump-to-trace (Excemplars).

26-45 dias

Alertas de padrão de evento e correlação com SLO.
Arquivo/recuperação (DR.-teste) para logs frios.
Linter esquemas de logs em CI, contrato para eventos de negócios.

16) Métricas de maturidade

A cobertura de solicitação 'trace _ id' ≥ 95%.
Os logs da JSON ≥ 99%.
Os incidentes encontrados via jump-to-trace foram resolvidos <15 minas (p50).
0 casos de PII em logs (scanner de vazamento).
O Retenshn foi cumprido em todos os fluxos (a auditoria é automática).

17) Aplicativos: minipappets

W3C traceparent geração (pseudo)

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

PromQL - ligação de logs e SLO (exemplo)

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 - Títulos coreanos

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

18) Conclusão

Um forte traçado de loging e rastreamento são acordos + disciplina: logs JSON estruturais, um único 'trace _ id', processamento seguro do PII, rotação e retenção de fluxo, e estreita ligação com o SLO, alerting e reversíveis. Faça uma transição de «sucata de textos» para os contratos de eventos e pistas, e o diagnóstico de incidentes de prod será rápido, previsível e verificável.