Logging

Overview

Logging in Raindrop helps you track what your application is doing and debug problems. Every service, actor, observer, and task has access to a built-in logger that records events with structured data.

The logging system automatically captures timestamps and request details, while letting you add custom information relevant to your application. Use it to monitor application health, track business events, and troubleshoot issues.

Prerequisites

• Raindrop framework installed in your project
• Basic understanding of application debugging
• Familiarity with TypeScript

Access

The logger is automatically available in all Raindrop components through the environment. No configuration required - just use this.env.logger in your code.

// In a service
export default class extends Service<Env> {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    this.env.logger.info("User visited homepage");
    return new Response("Hello World");
  }
}

Tip

The logger is provided automatically by Raindrop - no setup required.

Core Interfaces

Logger

Main logging interface with methods for different severity levels:

interface Logger {
  debug(message: string, fields?: LogFields): void;    // Development details
  info(message: string, fields?: LogFields): void;     // Normal events
  warn(message: string, fields?: LogFields): void;     // Potential issues
  error(message: string, fields?: LogFields): void;    // Failures
  error(error: Error, fields?: LogFields): void;       // Error objects
  withFields(fields: LogFields): Logger;               // Add context
}

Basic Usage

Simple Logging

Log messages with different severity levels:

this.env.logger.debug("Checking user permissions");
this.env.logger.info("User logged in successfully");
this.env.logger.warn("API response took 3 seconds");
this.env.logger.error("Database connection failed");

Adding Context

Include additional information to make logs more useful:

this.env.logger.info("User logged in", {
  userId: "123",
  email: "user@example.com",
  loginMethod: "password"
});

this.env.logger.error("Payment failed", {
  orderId: "ORDER-456",
  amount: 99.99,
  errorCode: "CARD_DECLINED"
});

Error Logging

Log error objects to capture stack traces automatically:

try {
  await processPayment(order);
} catch (error) {
  this.env.logger.error(error, {
    orderId: order.id,
    stage: "payment_processing"
  });
  throw error;
}

Context Management

Create child loggers that include common fields in all log entries:

// Create logger with user context
const userLogger = this.env.logger.withFields({
  userId: user.id,
  sessionId: session.id
});

// All logs include user context automatically
userLogger.info("Started checkout");      // Includes userId, sessionId
userLogger.warn("Invalid address");       // Includes userId, sessionId
userLogger.error("Payment declined");     // Includes userId, sessionId

Log Levels

Choose the appropriate level based on the importance of the event:

• debug - Detailed information for development (disabled in production)
• info - Normal application events worth recording
• warn - Unusual conditions that don’t break functionality
• error - Failures that need attention

Viewing Logs

To view logs from your deployed application, use the raindrop tail command from your project root directory:

raindrop tail

This streams live logs from your deployed application, showing all log entries in real-time as they occur.

Automatic Resource Logging

By default, every resource interaction in your application is automatically logged. This provides comprehensive visibility into your application’s behavior without requiring additional code.

Data Capture Scope

The system captures two distinct categories of interactions with different visibility levels. For user-initiated resource interactions visible to customers, we capture complete input/output pairs from all framework modules that users directly interact with. For internal platform operations visible only to engineering teams, we capture the underlying implementation calls that power user-visible services.

User-Visible Resource Interactions:

• Stateless compute: inputs, outputs, user-defined logging via this.env.logger
• SQL databases: queries and result data (with size considerations)
• Vector databases: queries, retrieved vectors, similarity scores, inserts, upserts
• Object store: object references and metadata, not full object copies
• Key-Value store: all CRUD operations with associated data
• Queues: message content and metadata
• Service-to-service calls: complete request/response pairs
• SmartBuckets: input queries and output results
• SmartSQL: queries and results
• Agent Memory: memory operations and state changes
• Model calls: prompts, responses, token usage, model parameters

This automatic logging helps you understand exactly how your application interacts with resources, making debugging and monitoring straightforward without manual instrumentation.