Working with Logging

Implement Working with Logging

Use structured logging with Pino throughout your application. Covers log levels, context, and workflow-safe logging patterns.

See:

• Resource: using-logging in Fullstack Recipes
• URL: https://fullstackrecipes.com/recipes/using-logging

---

Basic Logging

Import the logger and use it throughout your application:

import { logger } from "@/lib/common/logger";

// Info level for normal operations
logger.info("Server started", { port: 3000 });

// Warn level for recoverable issues
logger.warn("Rate limit reached", { endpoint: "/api/chat" });

// Error level with Error objects
logger.error(err, "Failed to process request");

// Debug level for development troubleshooting
logger.debug("Cache miss", { key: "user:123" });

Structured Logging

Always include context as the first argument for structured logs:

// Context object first, message second
logger.info({ userId: "123", action: "login" }, "User logged in");

// For errors, pass the error first
logger.error({ err, userId: "123", endpoint: "/api/chat" }, "Request failed");

Log Levels

Use appropriate levels for different scenarios:

Level	When to Use
trace	Detailed debugging (rarely used)
debug	Development troubleshooting
info	Normal operations, business events
warn	Recoverable issues, deprecation warnings
error	Failures that need attention
fatal	Critical failures, app cannot continue

Configuring Log Level

Set the PINO_LOG_LEVEL environment variable:

# Show all logs including debug
PINO_LOG_LEVEL="debug"

# Production: only warnings and errors
PINO_LOG_LEVEL="warn"

Default is info if not set.

Logging in API Routes

import { logger } from "@/lib/common/logger";

export async function POST(request: Request) {
  const start = Date.now();

  try {
    const result = await processRequest(request);

    logger.info(
      { duration: Date.now() - start, status: 200 },
      "Request completed",
    );

    return Response.json(result);
  } catch (err) {
    logger.error({ err, duration: Date.now() - start }, "Request failed");

    return Response.json({ error: "Internal error" }, { status: 500 });
  }
}

Logging in Workflows

Workflow functions run in a restricted environment. Use the logger step wrapper:

// src/workflows/chat/steps/logger.ts
import { logger } from "@/lib/common/logger";

export async function log(
  level: "info" | "warn" | "error" | "debug",
  message: string,
  data?: Record<string, unknown>,
): Promise<void> {
  "use step";

  if (data) {
    logger[level](data, message);
  } else {
    logger[level](message);
  }
}

Then use it in workflows:

import { log } from "./steps/logger";

export async function chatWorkflow({ chatId }) {
  "use workflow";

  await log("info", "Workflow started", { chatId });
}

---

References

• Pino Documentation
• Pino Log Levels