Logging

Basic Usage

Creating a Logger

Each service file should create a logger with a descriptive context:

import { Logger } from "@repo/logger";

const logger = new Logger({ context: "meta-bot" });

Logging Messages

// Error with exception
logger.error("Failed to process message", error, { messageId, userId });

// Warning for recoverable issues
logger.warn("Rate limit approaching", { currentRate, limit });

// Info for important business events
logger.info("User completed onboarding", { userId, organizationId });

// Debug for development details
logger.debug("Processing webhook payload", { payload });

Method Signatures

logger.error(message: string, errorOrMeta?: unknown, meta?: Record<string, unknown>): void
logger.warn(message: string, errorOrMeta?: unknown, meta?: Record<string, unknown>): void
logger.info(message: string, errorOrMeta?: unknown, meta?: Record<string, unknown>): void
logger.http(message: string, errorOrMeta?: unknown, meta?: Record<string, unknown>): void
logger.debug(message: string, errorOrMeta?: unknown, meta?: Record<string, unknown>): void

Child Loggers

Create child loggers for sub-contexts:

const logger = new Logger({ context: "meta-bot" });
const aiLogger = logger.child("ai"); // Context: "meta-bot:ai"
const flowLogger = logger.child("flow"); // Context: "meta-bot:flow"

aiLogger.info("Generating response"); // [meta-bot:ai] Generating response

Request Context

Request context (requestId, userId, organizationId) is automatically included via AsyncLocalStorage:

// In middleware - context is set automatically
// In service code - context is included in logs automatically

logger.info("Processing request");
// Output includes: { requestId: "abc-123", userId: "user_1", ... }

Manual Context Updates

import { updateContext } from "@repo/logger";

// Add user context after authentication
updateContext({
  userId: user.id,
  organizationId: session.activeOrganizationId,
});

Error Logging Patterns

With Error Object

try {
  await processMessage(message);
} catch (error) {
  logger.error("Failed to process message", error, {
    messageId: message.id,
    conversationId,
  });
  throw error;
}

Without Error Object

if (!user) {
  logger.error("User not found", undefined, { userId });
  throw new TRPCError({ code: "NOT_FOUND" });
}

With Cause Chain

Errors with .cause are automatically serialized with the full chain.

Performance Timing

import { timeAsync, PerformanceMarker } from "@repo/logger";

// Simple timing
const result = await timeAsync(
  "ai-generation",
  async () => generateResponse(prompt),
  logger
);

// Multi-step timing
const marker = new PerformanceMarker("flow-execution");
marker.mark("start");

await executeNode(node);
marker.mark("node-executed");

await sendMessage(response);
marker.mark("message-sent");

logger.info("Flow completed", { timing: marker.getSummary() });

Output Formats

Development (Pretty)