Logging Patterns

Deep dive into @outfitter/logging patterns.

Creating a Logger

typescript

import { createLogger, createConsoleSink } from "@outfitter/logging";

const logger = createLogger({
  name: "my-app",
  level: "info",
  sinks: [createConsoleSink()],
  redaction: { enabled: true },
});

Log Levels

Level	Method	Use For
`trace`	`logger.trace()`	Very detailed debugging
`debug`	`logger.debug()`	Development debugging
`info`	`logger.info()`	Normal operations
`warn`	`logger.warn()`	Unexpected but handled
`error`	`logger.error()`	Failures requiring attention
`fatal`	`logger.fatal()`	Unrecoverable failures

Level hierarchy: trace < debug < info < warn < error < fatal

Setting level to info hides trace and debug.

Structured Logging

Always use metadata objects:

typescript

// GOOD: Structured metadata
logger.info("User created", {
  userId: user.id,
  email: user.email,
  duration: performance.now() - start,
});

// BAD: String concatenation
logger.info("User " + user.name + " created in " + duration + "ms");

Child Loggers

Add context that persists across calls:

typescript

import { createChildLogger } from "@outfitter/logging";

const requestLogger = createChildLogger(logger, {
  requestId: ctx.requestId,
  handler: "createUser",
});

// All logs include requestId and handler
requestLogger.info("Processing");           // Has requestId, handler
requestLogger.debug("Validated input");     // Has requestId, handler
requestLogger.info("User created", { userId }); // Has requestId, handler, userId

Redaction

Enable Redaction

typescript

const logger = createLogger({
  name: "my-app",
  level: "info",
  sinks: [createConsoleSink()],
  redaction: { enabled: true },
});

logger.info("Config", {
  apiKey: "secret-123",     // Logged as "[REDACTED]"
  password: "hunter2",      // Logged as "[REDACTED]"
  email: "user@example.com" // Not redacted
});

Default Redaction Patterns

Automatically redacted:

•password, pwd
•apiKey, api_key
•secret, secretKey
•token, accessToken
•auth, authorization
•key (when containing sensitive data)
•credential, credentials

Custom Patterns

typescript

const logger = createLogger({
  name: "my-app",
  redaction: {
    enabled: true,
    patterns: [
      "password",
      "apiKey",
      "myCustomSecret",
      "internalToken",
    ],
  },
});

Deep Redaction

Nested values are also redacted:

typescript

logger.info("Request", {
  headers: {
    authorization: "Bearer token",  // Redacted
  },
  body: {
    user: {
      password: "secret",  // Redacted
    },
  },
});

Sinks

Console Sink

typescript

import { createConsoleSink } from "@outfitter/logging";

const consoleSink = createConsoleSink({
  colorize: true,           // ANSI colors
  prettyPrint: true,        // Formatted output
  timestampFormat: "iso",   // ISO 8601 timestamps
});

File Sink

typescript

import { createFileSink } from "@outfitter/logging";

const fileSink = createFileSink({
  path: "/var/log/myapp/app.log",
  maxSize: 10 * 1024 * 1024,  // 10MB
  maxFiles: 5,                 // Keep 5 rotated files
});

Multiple Sinks

typescript

const logger = createLogger({
  name: "my-app",
  level: "debug",
  sinks: [
    createConsoleSink({ level: "info" }),     // Console: info+
    createFileSink({                           // File: debug+
      path: "/var/log/myapp/debug.log",
      level: "debug",
    }),
  ],
});

Custom Sink

typescript

const customSink = {
  log: (record) => {
    // Send to external service
    externalService.send({
      level: record.level,
      message: record.message,
      metadata: record.metadata,
      timestamp: record.timestamp,
    });
  },
};

const logger = createLogger({
  name: "my-app",
  sinks: [customSink],
});

Environment Configuration

typescript

const logger = createLogger({
  name: "my-app",
  level: process.env.LOG_LEVEL || "info",
  sinks: [
    createConsoleSink({
      colorize: process.stdout.isTTY,
      prettyPrint: process.env.NODE_ENV !== "production",
    }),
  ],
});

Handler Context Integration

typescript

import { createContext } from "@outfitter/contracts";
import { createLogger, createChildLogger } from "@outfitter/logging";

const baseLogger = createLogger({ name: "my-app", level: "info" });

export function createHandlerContext() {
  const ctx = createContext({ logger: baseLogger });

  // Child logger with requestId
  return {
    ...ctx,
    logger: createChildLogger(baseLogger, { requestId: ctx.requestId }),
  };
}

// In handler
const myHandler: Handler<Input, Output, Error> = async (input, ctx) => {
  ctx.logger.info("Processing", { input });  // Includes requestId
  // ...
};

Performance

Conditional Logging

typescript

// Level check before expensive operations
if (logger.isEnabled("debug")) {
  const expensiveData = computeDebugInfo();
  logger.debug("Debug info", { data: expensiveData });
}

Lazy Evaluation

typescript

logger.debug("State", () => ({
  // Only computed if debug level is enabled
  memory: process.memoryUsage(),
  connections: getActiveConnections(),
}));

Best Practices

•Structured metadata — Always use objects, not string concatenation
•Child loggers — Add request context that persists
•Enable redaction — Prevent secrets from leaking
•Level per environment — Debug in dev, info in prod
•Request IDs — Include for tracing across handlers
•Lazy evaluation — Avoid expensive computations at disabled levels

Related Skills

•stack:patterns — Context creation
•stack:outfitter-daemon — Daemon logging
•stack:debug — Troubleshooting logging