whisper

Whisper implements a fixed-size round-robin database that pre-allocates disk space for time-series metrics and overwrites oldest data when capacity is reached, eliminating dynamic allocation overhead. Data is written sequentially by the Carbon ingestion service into pre-defined storage slots indexed by timestamp, enabling predictable disk usage and O(1) write performance regardless of dataset age. The circular buffer design trades retention flexibility for guaranteed storage footprint and consistent write latency.

Whisper supports creating multiple aggregation levels (e.g., 1-minute raw data, 10-minute averages, 1-hour summaries) within a single database file, enabling efficient long-term storage by downsampling older data while preserving high-resolution recent data. Each retention tier is a separate round-robin buffer with different time granularity and aggregation function (average, sum, last, etc.), allowing queries to select appropriate resolution based on time range. This hierarchical approach reduces storage for historical data while maintaining query flexibility without requiring separate database files.

Whisper integrates with the Carbon service through a write API that accepts timestamped metric data and routes writes to appropriate storage slots based on metric name and timestamp. Carbon handles network protocol parsing (plaintext, pickle, AMQP) and metric name validation, then delegates to Whisper for storage, which maps timestamps to fixed storage offsets using modulo arithmetic on the circular buffer. This separation enables Carbon to handle protocol complexity while Whisper focuses on efficient storage, with no direct user-facing API — all writes flow through Carbon.

Whisper provides a read interface consumed by Graphite-web to retrieve time-series data for graph rendering and API responses. Queries specify metric name and time range, and Whisper maps the time range to storage offsets in the circular buffer, reading only the relevant data without scanning the entire file. Graphite-web handles query parsing, metric pattern matching, and result formatting (PNG, CSV, JSON, XML), while Whisper provides the low-level storage retrieval. This separation enables Graphite-web to support complex queries (wildcards, functions, aggregations) without Whisper needing to understand query semantics.

Whisper requires upfront schema definition specifying retention policies (how long to keep data at each resolution) and aggregation functions (how to downsample data between tiers). Schema is typically defined in a configuration file (storage-schemas.conf) that maps metric name patterns to retention/aggregation rules, which Carbon uses to create Whisper database files with matching structure. Once created, schema is immutable — changing retention or aggregation requires recreating the database file and losing historical data. This design trades flexibility for predictability: storage footprint and query performance are determined at schema definition time.

Whisper stores each metric as a single binary file on disk containing a header (metadata about retention tiers and aggregation) followed by pre-allocated round-robin buffers. Files are created at metric creation time with full size allocated upfront, eliminating fragmentation and enabling direct offset calculation for reads/writes. The binary format is compact and uncompressed, optimized for sequential access patterns typical of time-series workloads. No indexing structures are maintained — metric discovery relies on filesystem directory scanning, making Whisper suitable for systems with moderate metric cardinality (thousands to tens of thousands) but not billions of unique metrics.