---

name: logging description: Guide structured logging using @repo/logger package with Winston. Use when adding logs, debugging, or understanding log patterns. allowed-tools: Read, Glob, Grep

Logging Guide

This skill provides guidance for structured logging using the @repo/logger package in the YouTube Channel Analyzer project.

Package Overview

The @repo/logger package provides Winston-based structured logging with request correlation and context propagation.

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

const logger = new Logger({ context: "feature-name" });

Log Levels

Basic Usage

Creating a Logger

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

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

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

Logging Messages

Copy// 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

Copylogger.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:

Copyconst 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:

Copy// 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

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

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

Error Logging Patterns

With Error Object

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

Without Error Object

Copyif (!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

Copyimport { 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)

Copy10:30:45.123 INFO  [meta-bot] Processing message (abc12345) {"conversationId":"conv_1"}

Production (JSON)

Copy{
  "level": "info",
  "message": "Processing message",
  "timestamp": "2024-01-16T10:30:45.123Z",
  "context": "meta-bot",
  "requestId": "abc-123",
  "conversationId": "conv_1"
}

Best Practices

1. Use appropriate log levels - Don't log everything as error
2. Include context - Always add relevant IDs and metadata
3. Log important business events with info level
4. Don't log sensitive data - Never log passwords, tokens, or PII
5. Use child loggers for sub-components within a feature
6. Keep messages concise - Context goes in metadata, not message
7. Log at boundaries - Log when entering/exiting important operations

Common Patterns

Service Method Logging

Copyexport async function processConversation(conversationId: string) {
  logger.info("Processing conversation", { conversationId });

  try {
    const result = await doWork();
    logger.info("Conversation processed successfully", {
      conversationId,
      resultCount: result.length,
    });
    return result;
  } catch (error) {
    logger.error("Failed to process conversation", error, { conversationId });
    throw error;
  }
}

Webhook Handler Logging

Copyexport async function handleWebhook(payload: WebhookPayload) {
  logger.info("Received webhook", {
    type: payload.type,
    objectId: payload.object.id,
  });

  // Process...

  logger.info("Webhook processed", { type: payload.type });
}

Background Job Logging

Copyexport async function processScheduledJob(jobId: string) {
  logger.info("Starting scheduled job", { jobId });

  const processed = 0;
  for (const item of items) {
    // Process item
    processed++;
  }

  logger.info("Scheduled job completed", { jobId, processed });
}

Migration from console.*

When migrating from console.*:

Copy// Before
console.error("[meta-bot] Failed to process:", error);

// After
logger.error("Failed to process", error);
// Context "[meta-bot]" comes from logger instance