Copy page

Logging & Observability

Logger

The Logger interface provides structured logging capabilities throughout your Zuplo Gateway. The logger is accessible via the context.log property and supports multiple log levels.

Interface

Code
interface Logger {
  debug(...messages: unknown[]): void;
  info(...messages: unknown[]): void;
  warn(...messages: unknown[]): void;
  error(...messages: unknown[]): void;
  log(...messages: unknown[]): void;
}

Log Levels

The logger supports the following levels (from least to most severe):

• debug - Detailed information for debugging
• info - General informational messages
• warn - Warning messages for potentially problematic situations
• error - Error messages for failures and exceptions
• log - Alias for info level

Usage

The logger is available on the ZuploContext object:

Code
import { ZuploContext, ZuploRequest } from "@zuplo/runtime";

export default async function handler(
  request: ZuploRequest,
  context: ZuploContext,
) {
  // Log at different levels
  context.log.debug("Detailed debug information");
  context.log.info("Request received", { path: request.url });
  context.log.warn("Deprecated endpoint accessed");
  context.log.error("Failed to process request", { error: "Invalid input" });

  return new Response("OK");
}

Structured Logging

The logger accepts multiple arguments and automatically serializes objects:

Code
// Log simple strings
context.log.info("User authenticated");

// Log objects
context.log.info({
  userId: "user-123",
  action: "login",
  timestamp: Date.now(),
});

// Log multiple arguments
context.log.info(
  "Processing request",
  {
    method: request.method,
    path: request.url,
  },
  "additional info",
);

// Log arrays
context.log.debug(["step1", "step2", "step3"]);

// Log errors
try {
  await riskyOperation();
} catch (error) {
  context.log.error("Operation failed", {
    error: error.message,
    stack: error.stack,
  });
}

Automatic Request ID

The logger automatically includes the request ID with every log entry:

Code
context.log.info("Processing payment");
// Output includes: { "message": "Processing payment", "requestId": "req_abc123..." }

Environment Configuration

Log levels vary by environment:

• Development/Preview: Typically set to debug or info level
• Production: Typically set to error level only

Best Practices

1. Use Appropriate Log Levels

Code
// Debug - detailed information for troubleshooting
context.log.debug("Cache lookup", { key: cacheKey, ttl: 300 });

// Info - general application flow
context.log.info("Order created", { orderId: "order-123", total: 99.99 });

// Warn - concerning but not critical
context.log.warn("Rate limit approaching", { current: 95, limit: 100 });

// Error - failures and exceptions
context.log.error("Payment failed", {
  orderId: "order-123",
  errorCode: "INSUFFICIENT_FUNDS",
});

2. Include Contextual Information

Code
export default async function handler(
  request: ZuploRequest,
  context: ZuploContext,
) {
  const startTime = Date.now();
  const userId = request.user?.sub;

  context.log.info("Request started", {
    userId,
    method: request.method,
    path: new URL(request.url).pathname,
    userAgent: request.headers.get("user-agent"),
  });

  try {
    const result = await processRequest(request);

    context.log.info("Request completed", {
      userId,
      duration: Date.now() - startTime,
      status: "success",
    });

    return new Response(JSON.stringify(result));
  } catch (error) {
    context.log.error("Request failed", {
      userId,
      duration: Date.now() - startTime,
      error: error.message,
      stack: error.stack,
    });

    throw error;
  }
}

3. Avoid Logging Sensitive Data

Code
// DON'T log sensitive information
context.log.info("User login", {
  email: user.email,
  password: user.password, // Never log passwords!
});

// DO log safe identifiers
context.log.info("User login", {
  userId: user.id,
  email: user.email.replace(/(.{2}).*(@.*)/, "$1***$2"), // Partially masked
});

4. Use Structured Data for Better Querying

Code
// Good - structured data that can be queried
context.log.info("API call completed", {
  service: "payment-processor",
  operation: "charge",
  duration: 1234,
  status: "success",
  amount: 99.99,
  currency: "USD",
});

// Less useful - unstructured string
context.log.info(`Payment of $99.99 USD processed in 1234ms`);

Integration with Log Management

Logs are automatically forwarded to your configured log management solution (Datadog, Loki, etc.). The structured format makes it easy to:

• Search and filter logs
• Create alerts based on log patterns
• Generate metrics from log data
• Trace requests across services

Performance Considerations

• Logging has minimal performance impact
• Logs are processed asynchronously
• In production, use error level to reduce log volume
• Avoid logging large objects or sensitive data

See Also

• ZuploContext - The context object that provides the logger
• Logging - General logging documentation
• Log Export - Exporting logs to external services