pn-observability

Observability

When to use

• Instrumenting a new service with traces, metrics, and structured logs
• Adding Sentry for error tracking and performance monitoring
• Setting up OpenTelemetry with a collector (Datadog, Grafana Tempo, OTLP)
• Implementing health-check endpoints (/health, /ready)
• Defining SLOs and alert thresholds
• Diagnosing a performance regression or production incident

Three pillars

Structured logging with Pino

import pino from "pino";

export const logger = pino({
  level: process.env.LOG_LEVEL ?? "info",
  // pretty-print in dev, JSON in prod
  transport: process.env.NODE_ENV === "development"
    ? { target: "pino-pretty", options: { colorize: true } }
    : undefined,
  redact: ["req.headers.authorization", "body.password", "body.token"],
  base: { service: "api", version: process.env.APP_VERSION },
});

// Usage — always log structured fields, not interpolated strings
logger.info({ userId, orderId }, "Order placed");
logger.error({ err, requestId }, "Payment failed");

// Request logger middleware (Fastify auto-logs; Express manual)
app.use((req, res, next) => {
  req.log = logger.child({ requestId: req.headers["x-request-id"] });
  req.log.info({ method: req.method, url: req.url }, "Request received");
  next();
});

Rules:

• Log as JSON in production — log aggregators parse JSON, not strings.
• Always include requestId / traceId in every log line for correlation.
• Redact sensitive fields — never log tokens, passwords, or full PII.
• Use log levels correctly: debug for dev details, info for business events, warn for degraded state, error for failures.

OpenTelemetry