Logging Observability

---

name: logging-observability model: standard description: Structured logging, distributed tracing, and metrics collection patterns for building observable systems. Use when implementing logging infrastructure, setting up distributed tracing with OpenTelemetry, designing metrics collection (RED/USE methods), configuring alerting and dashboards, or reviewing observability practices. Covers structured JSON logging, context propagation, trace sampling, Prometheus/Grafana stack, alert design, and PII/secret scrubbing. version: 1.0.0

---

Logging & Observability

Patterns for building observable systems across the three pillars: logs, metrics, and traces.

Three Pillars

| Pillar | Purpose | Question It Answers | Example | |--------|---------|---------------------|---------| | Logs | What happened | Why did this request fail? | {"level":"error","msg":"payment declined","user_id":"u_82"} | | Metrics | How much / how fast | Is latency increasing? | http_request_duration_seconds{route="/api/orders"} 0.342 | | Traces | Request flow | Where is the bottleneck? | Span: api-gateway → auth → order-service → db |

Each pillar is strongest when correlated. Embed trace_id in every log line to jump from a log entry to the full distributed trace.

---

Structured Logging

Always emit logs as structured JSON — never free-text strings.

Required Fields

| Field | Purpose | Required | |-------|---------|----------| | timestamp | ISO-8601 with milliseconds | Yes | | level | Severity (DEBUG … FATAL) | Yes | | service | Originating service name | Yes | | message | Human-readable description | Yes | | trace_id | Distributed trace correlation | Yes | | span_id | Current span within trace | Yes | | correlation_id | Business-level correlation (order ID) | When applicable | | error | Structured error object | On errors | | context | Request-specific metadata | Recommended |

Context Enrichment

Attach context at the middleware level so downstream logs inherit automatically:

app.use((req, res, next) => {
  const ctx = {
    trace_id: req.headers['x-trace-id'] || crypto.randomUUID(),
    request_id: crypto.randomUUID(),
    user_id: req.user?.id,
    method: req.method,
    path: req.path,
  };
  asyncLocalStorage.run(ctx, () => next());
});

Library Recommendations

| Library | Language | Strengths | Perf | |---------|----------|-----------|------| | Pino | Node.js | Fastest Node logger, low overhead | Excellent | | structlog | Python | Composable processors, context binding | Good | | zerolog | Go | Zero-allocation JSON logging | Excellent | | zap | Go | High performance, typed fields | Excellent | | tracing | Rust | Spans + events, async-aware | Excellent |

Choose a logger that outputs structured JSON natively. Avoid loggers requiring post-processing.

---

Log Levels

| Level | When to Use | Example | |-------|-------------|---------| | FATAL | App cannot continue, process will exit | Database connection pool exhausted | | ERROR | Operation failed, needs attention | Payment charge failed: CARD_DECLINED | | WARN | Unexpected but recoverable | Retry 2/3 for upstream timeout | | INFO | Normal business events | Order ORD-1234 placed successfully | | DEBUG | Developer troubleshooting | Cache miss for key user:82:preferences | | TRACE | Very fine-grained (rarely in prod) | Entering validateAddress with payload |

Rules: Production default = INFO and above. If you log an ERROR, someone should act on it. Every FATAL should trigger an alert.

---

Distributed Tracing

OpenTelemetry Setup

Always prefer OpenTelemetry over vendor-specific SDKs:

import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
const sdk = new NodeSDK({
  serviceName: 'order-service',
  traceExporter: new OTLPTraceExporter({
    url: 'http://otel-collector:4318/v1/traces',
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();

Span Creation

const tracer = trace.getTracer('order-service');
async function processOrder(order: Order) {
  return tracer.startActiveSpan('processOrder', async (span) => {
    try {
      span.setAttribute('order.id', order.id);
      span.setAttribute('order.total_cents', order.totalCents);
      await validateInventory(order);
      await chargePayment(order);
      span.setStatus({ code: SpanStatusCode.OK });
    } catch (err) {
      span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
      span.recordException(err);
      throw err;
    } finally {
      span.end();
    }
  });
}

Context Propagation

Use W3C Trace Context (traceparent header) — default in OTel

Propagate across HTTP, gRPC, and message queues

For async workers: serialise traceparent into the job payload

Trace Sampling

| Strategy | Use When | |----------|----------| | Always On | Low-traffic services, debugging | | Probabilistic (N%) | General production use | | Rate-limited (N/sec) | High-throughput services | | Tail-based | When you need all error traces |

Always sample 100% of error traces regardless of strategy.

---

Metrics Collection

RED Method (Request-Driven)

Monitor these three for every service endpoint:

| Metric | What It Measures | Prometheus Example | |--------|-----------------|-------------------| | Rate | Requests/sec | rate(http_requests_total[5m]) | | Errors | Failed request ratio | rate(http_requests_total{status=~"5.."}[5m]) | | Duration | Response time | histogram_quantile(0.99, http_request_duration_seconds) |

USE Method (Resource-Driven)

For infrastructure components (CPU, memory, disk, network):

| Metric | What It Measures | Example | |--------|-----------------|---------| | Utilization | % resource busy | CPU usage at 78% | | Saturation | Work queued/waiting | 12 requests queued in thread pool | | Errors | Error events on resource | 3 disk I/O errors in last minute |

---

Monitoring Stack

| Tool | Category | Best For | |------|----------|----------| | Prometheus | Metrics | Pull-based metrics, alerting rules | | Grafana | Visualisation | Dashboards for metrics, logs, traces | | Jaeger | Tracing | Distributed trace visualisation | | Loki | Logs | Log aggregation (pairs with Grafana) | | OpenTelemetry | Collection | Vendor-neutral telemetry collection |

Recommendation: Start with OTel Collector → Prometheus + Grafana + Loki + Jaeger. Migrate to SaaS only when operational overhead justifies cost.

---

Alert Design

Severity Levels

| Severity | Response Time | Example | |----------|---------------|---------| | P1 | Immediate | Service fully down, data loss | | P2 | < 30 min | Error rate > 5%, latency p99 > 5s | | P3 | Business hours | Disk > 80%, cert expiring in 7 days | | P4 | Best effort | Non-critical deprecation warning |

Alert Fatigue Prevention

Alert on symptoms, not causes — "error rate > 5%" not "pod restarted"

Multi-window, multi-burn-rate — catch both sudden spikes and slow burns

Require runbook links — every alert must link to diagnosis and remediation

Review monthly — delete or tune alerts that never fire or always fire

Group related alerts — use inhibition rules to suppress child alerts

Set appropriate thresholds — if alert fires daily and is ignored, raise threshold or delete

---

Dashboard Patterns

Overview Dashboard ("War Room")

Total requests/sec across all services

Global error rate (%) with trendline

p50 / p95 / p99 latency

Active alerts count by severity

Deployment markers overlaid on graphs

Service Dashboard (Per-Service)

RED metrics for each endpoint

Dependency health (upstream/downstream success rates)

Resource utilisation (CPU, memory, connections)

Top errors table with count and last seen

---

Observability Checklist

Every service must have:

[ ] Structured JSON logging with consistent schema

[ ] Correlation / trace IDs propagated on all requests

[ ] RED metrics exposed for every external endpoint

[ ] Health check endpoints (/healthz and /readyz)

[ ] Distributed tracing with OpenTelemetry

[ ] Dashboards for RED metrics and resource utilisation

[ ] Alerts for error rate, latency, and saturation with runbook links

[ ] Log level configurable at runtime without redeployment

[ ] PII scrubbing verified and tested

[ ] Retention policies defined for logs, metrics, and traces

Anti-Patterns

| Anti-Pattern | Problem | Fix | |-------------|---------|-----| | Logging PII | Privacy/compliance violation | Mask or exclude PII; use token references | | Excessive logging | Storage costs balloon, signal drowns | Log business events, not data flow | | Unstructured logs | Cannot query or alert on fields | Use structured JSON with consistent schema | | String interpolation | Breaks structured fields, injection risk | Pass fields as metadata, not in message | | Missing correlation IDs | Cannot trace across services | Generate and propagate trace_id everywhere | | Alert storms | On-call fatigue, real issues buried | Use grouping, inhibition, deduplication | | Metrics with high cardinality | Prometheus OOM, dashboard timeouts | Never use user ID or request ID as label |

NEVER Do

1. NEVER log passwords, tokens, API keys, or secrets — even at DEBUG level 2. NEVER use console.log / print in production — use a structured logger 3. NEVER use user IDs, emails, or request IDs as metric labels — cardinality will explode 4. NEVER create alerts without a runbook link — unactionable alerts erode trust 5. NEVER rely on logs alone — you need metrics and traces for full observability 6. NEVER log request/response bodies by default — opt-in only, with PII redaction 7. NEVER ignore log volume — set budgets and alert when a service exceeds daily quota 8. NEVER skip context propagation in async flows — broken traces are worse than no traces