SESSION 080 — Structured Logging

CONCEPTS.UNLOCKED

📋

Structured Logging

Logs as JSON, not strings. Instead of "User 42 uploaded image" → { level: "info", userId: 42, action: "upload", timestamp: "..." }. Machine-readable, searchable, parseable.

🚦

Log Levels

DEBUG → INFO → WARN → ERROR → FATAL. In development, show everything. In production, show WARN and above. Filter by severity to find what matters fast.

🔧

Winston & Pino

Production-grade Node.js loggers. Winston: flexible, widely used. Pino: blazing fast (5× faster), JSON-native. Both support transports: file, console, external services.

🔗

Request Tracing

correlationId ties logs to a single request. Generate a UUID per request, attach to every log within that request. When debugging, filter by correlationId to see the full request lifecycle.

🛡️

Centralized Error Handling

One place to catch all errors. Express error middleware catches everything. Log the error with full context (userId, route, requestId, stack trace), then send a clean response to the client.

👀

Log Viewer

Internal dashboard for browsing logs. Read JSON log files, parse them, filter by level/userId/action, search by keyword. Your own mini Datadog — built from scratch.

HANDS-ON.TASKS

Set Up Pino Logger

▶

npm install pino pino-pretty

// logger.js
const pino = require('pino');

const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  transport:
    process.env.NODE_ENV === 'development'
    ? {
        target: 'pino-pretty',
        options: {
          colorize: true,
          translateTime: 'HH:MM:ss',
        }
      }
    : undefined, // JSON in production
});

module.exports = logger;

Request Tracing Middleware

▶

const { randomUUID } = require('crypto');
const logger = require('./logger');

function requestLogger(req, res, next) {
  // Generate unique request ID
  req.requestId = randomUUID();
  req.startTime = Date.now();

  // Create child logger with context
  req.log = logger.child({
    requestId: req.requestId,
    method: req.method,
    path: req.path,
    userId: req.userId || 'anonymous',
  });

  req.log.info('Request started');

  // Log when response finishes
  res.on('finish', () => {
    const duration =
      Date.now() - req.startTime;
    req.log.info({
      statusCode: res.statusCode,
      duration: `${duration}ms`,
    }, 'Request completed');
  });

  next();
}

app.use(requestLogger);

pino.child() creates a logger that automatically includes the parent's context in every log. Every log from this request will include the requestId, method, path, and userId.

Centralized Error Handler

▶

// Must be LAST middleware
app.use((err, req, res, next) => {
  const statusCode =
    err.statusCode || 500;

  // Log error with full context
  req.log.error({
    error: err.message,
    stack: err.stack,
    statusCode,
  }, 'Unhandled error');

  // Clean response to client
  res.status(statusCode).json({
    error: statusCode === 500
      ? 'Internal server error'
      : err.message,
    requestId: req.requestId,
    // ^ user can reference this
    //   when contacting support
  });
});

Replace console.log Everywhere

▶

// ❌ BEFORE (useless in production)
console.log('upload started');
console.log(user);
console.log('error:', err);

// ✅ AFTER (searchable, traceable)
req.log.info({
  action: 'upload_started',
  fileSize: req.file.size,
  mimeType: req.file.mimetype,
}, 'Image upload initiated');

req.log.error({
  action: 'upload_failed',
  error: err.message,
}, 'Image upload failed');

Build Internal Log Viewer

▶

Build a React page at /admin/logs: read JSON log files from the server, parse each line, display in a table with columns: timestamp, level, userId, action, message. Add filters for log level and search by requestId.

Close the Ticket

▶

git switch -c feature/PIXELCRAFT-067-structured-logging
git add server/ src/
git commit -m "Replace console.log with Pino structured logging (PIXELCRAFT-067)"
git push origin feature/PIXELCRAFT-067-structured-logging
# PR → Review → Merge → Close ticket ✅

CS.DEEP-DIVE

Observability is how you understand production systems.

Logging is one of three "pillars of observability" — the tools that let you understand what your system is doing without stopping it.

// The three pillars:

Logs
  What happened (discrete events)
  "User 42 uploaded image at 14:32"

Metrics
  How much is happening (aggregates)
  "95th percentile latency: 120ms"

Traces
  How requests flow through services
  "API → Queue → Worker → DB → S3"

// Tools at scale:
ELK Stack (Elasticsearch + Logstash
  + Kibana) — self-hosted log search
Datadog  — managed observability
Grafana  — dashboards + alerts

// "If you can't measure it,
// you can't improve it." — Kelvin

REF.MATERIAL

ARTICLE

Pino — Super Fast Node.js Logger

Pino Team

Official Pino documentation: transports, child loggers, redaction, serializers, and benchmarks. 5× faster than Winston in production.

PINOOFFICIALESSENTIAL

VIDEO

Structured Logging — Hussein Nasser

Hussein Nasser

Why structured logging matters in production. JSON vs plaintext, log aggregation, and how companies debug at scale.

LOGGINGARCHITECTURE

ARTICLE

OpenTelemetry Documentation

OpenTelemetry

The standard for distributed tracing: spans, traces, and context propagation. The future of observability across microservices.

TRACINGOFFICIAL

ARTICLE

Logs — The Twelve-Factor App

Adam Wiggins

Treat logs as event streams. Don't write to files — write to stdout and let the platform handle routing. The cloud-native logging philosophy.

12-FACTORARCHITECTURE

VIDEO

Node.js Logging Best Practices — Fireship

Fireship

Quick tour of Node.js logging: Winston vs Pino, log levels, transports, and production patterns. Practical and concise.

LOGGINGQUICK

STRUCTURED LOGGING