Turn your agent data into actionable insights. Analytics Engine is a time-series database optimized for storing and querying metrics at massive scale. Perfect for tracking agent performance, user engagement, billing data, trading data, and generating real-time dashboards.

Key Features

• Time-Series Optimized: Built for high-frequency metric ingestion with 90 day retention
• SQL Querying: Use familiar SQL to analyze your data
• Real-Time Analytics: Query data as soon as it's written
• Cost Effective: Pay only for data points written, not storage
• Global Distribution: Data available worldwide with low latency

NOTE: If you are looking for longer storage retention, consider SQL Database combined with caching techniques to achieve similar results.

Getting Started

Wrangler Configuration

First, add analytics in your wrangler.json:

Agent Integration

Access analytics through your agent's environment and start tracking basic metrics:

Basic Query Example

Query your analytics data using SQL to extract meaningful insights:

MCP Integration

TypeScript API Reference

You can access the analytics API via the env of the Agent or MCP Tool:

Data Writing Methods

writeDataPoint(dataset: string, data: AnalyticsDataPoint): Promise<void>
Writes a single data point to the specified dataset. Use for individual events or metrics.

writeDataPoints(dataset: string, data: AnalyticsDataPoint[]): Promise<void>
Writes multiple data points in a single batch operation. More efficient for bulk data ingestion.

Query Methods

query(sql: string): Promise<AnalyticsQueryResult>
Executes a SQL query against your analytics data. Returns structured results with metadata.

getMetrics(dataset: string, options: MetricsOptions): Promise<MetricsResult>
Predefined query helper for common metric aggregations with time ranges and grouping.

getTimeSeries(dataset: string, metric: string, options: TimeSeriesOptions): Promise<TimeSeriesResult>
Specialized query for time-series data with automatic interval bucketing.

Data Structures

Examples

Each example demonstrates different analytics patterns for monitoring agent performance, billing tracking, A/B testing, and real-time system monitoring.

Performance Monitoring Agent

Comprehensive agent performance tracking with error handling and user satisfaction metrics:

Usage-Based Billing Agent

Track detailed resource usage and implement billing alerts for cost management:

A/B Testing Analytics Agent

Run experiments and analyze statistical significance of different agent variants:

Real-Time Monitoring Agent

Monitor system health with automatic anomaly detection and alerting:

Best Practices

Follow these patterns for optimal analytics performance and maintainability. Use consistent naming conventions and batch operations when possible.

Efficient Data Modeling

Choose appropriate dimension cardinality and use consistent naming conventions to optimize query performance and storage costs.

Query Optimization

Write efficient SQL queries that filter early and use appropriate aggregations to minimize data transfer and processing time.

Error Handling

Implement graceful error handling to ensure analytics failures don't break your main application flow.

Limitations & Considerations

• Data Point Size: Maximum 25 fields per data point
• String Length: Maximum 256 characters per string field
• Write Rate: Up to 25,000 data points per minute per dataset
• Retention: Data retained for 3 months by default
• Query Complexity: Limited to 1000 result rows per query

Related Services

• Memory Store (KV) - Store analytics configurations and cache query results
• Queues - Buffer high-volume analytics data
• Logs - Detailed debugging information to complement metrics