Logs
Logs
Debug and monitor your agents like a pro. Cloudflare Logs provides structured, searchable logging capabilities that help you understand agent behavior, debug issues, and monitor performance across your entire agent fleet. With real-time streaming, structured data, and powerful filtering, you'll never lose track of what your agents are doing.
Key Features
- Structured Logging: JSON-formatted logs with searchable fields and metadata
- Real-Time Streaming: Live log streaming for immediate debugging and monitoring
- Global Collection: Logs from all edge locations aggregated in real-time
- Retention Control: Configurable log retention periods and storage policies
- Integration Ready: Works seamlessly with external monitoring and alerting systems
TypeScript API Reference
Basic Logging Methods
info(message: string, metadata?: LogMetadata): void
Logs informational messages about normal agent operations. Use for tracking user interactions, successful operations, and general agent activity.
warn(message: string, metadata?: LogMetadata): void
Logs warning messages for recoverable issues or unexpected conditions. Use when agents encounter problems but can continue operating.
error(message: string, error?: Error, metadata?: LogMetadata): void
Logs error messages for failures and exceptions. Automatically captures stack traces when an Error object is provided.
debug(message: string, metadata?: LogMetadata): void
Logs detailed debugging information. Only appears in development/debug environments unless explicitly enabled in production.
Advanced Logging
trace(operationName: string, duration: number, metadata?: LogMetadata): void
Logs performance traces for timing operations. Useful for tracking agent response times and identifying bottlenecks.
audit(action: string, userId: string, metadata?: LogMetadata): void
Logs audit events for compliance and security monitoring. Tracks important user actions and system changes.
metric(name: string, value: number, tags?: Record<string, string>): void
Logs custom metrics that can be used for monitoring and alerting. Integrates with analytics dashboards.
Structured Logging
withContext(context: LogContext): Logger
Creates a logger instance with persistent context that's added to all subsequent log entries. Useful for request tracking and user context.
withTags(tags: Record<string, string>): Logger
Creates a logger with persistent tags for categorizing and filtering log entries. Perfect for environment, feature, or team-based filtering.
Agent Examples
Request Tracing Agent
User Activity Monitoring Agent
Error Tracking and Recovery Agent
Performance Monitoring Agent
Best Practices
Structured Logging
Log Levels
Performance Logging
Context and Tags
Configuration
Wrangler Configuration
Log Levels
- debug: Detailed information for development and troubleshooting
- info: General information about agent operations
- warn: Warning messages for potential issues
- error: Error conditions that need attention
- audit: Security and compliance events
Integration
External Monitoring
Limitations
- Log Size: Maximum 1MB per log entry
- Rate Limits: 1,000 log entries per second per worker
- Retention: Default 30-day retention (configurable)
- Structured Data: Maximum 100 fields per log entry
Related Services
- Analytics Storage - Metrics and time-series data
- Memory Store - Temporary state storage
- Environment Variables - Configuration management