Architecture Overview

​

Introduction

​

Core Components

​

Server Architecture

• WebSocket Server: Listens on port 2077 for binary time series data
• HTTP Routes: / (WebSocket upgrade), /health (health check)
• Concurrent Processing: Uses the zio runtime for async I/O with configurable channel capacity (8192 * 2 events)

const Server = struct {
    const max_queries = 16;
    allocator: std.mem.Allocator,
    connections: Connections,
    channel: *Channel(ChannelData),
    tree: *TsmTree,
    // ... series indexes and query state
};

​

Data Flow

1. Ingestion: Binary messages arrive via WebSocket in format:
   [timestamp:i64][value:f64][series_len:u16][tag_count:u16][series][tags...]
   
2. Series Key Resolution: Tags are hashed and interned for efficient lookups (main.zig:107-138)
3. Storage: Data flows through:
   • Write-optimized in-memory cache (skiplist-based)
   • Automatic flush to disk when cache exceeds 1M data points
   • TSM tree disk entries with columnar storage
4. Query Processing: Real-time queries match against:
   • Active series by measurement
   • Tag filters (AND/OR/NOT operations)
   • Time ranges with relative time support

​

Component Interactions

​

Series Indexing

• Series Key Cache: Interned strings to reduce memory overhead
• Series by Measurement: Fast lookup of all series for a given measurement
• Series by Measurement+Tag: Enables tag-based filtering
• Hash-based Deduplication: Detects series key collisions (main.zig:117-137)

​

Query Engine

OP:SERIES:[TAGS]:[RANGE]

• AVG, MIN, MAX, SUM, COUNT: Aggregation operations
• Tag Filters: [region=us AND NOT muted]
• Time Ranges: [1m,now], [1700000000,1700000100]

• Hot Path: In-memory cache for recent data
• Cold Path: Disk entries with Bloom filter optimization

​

Storage Architecture

​

Workflow System

• u_query_live: Register persistent queries that receive updates
• u_query_history: Execute aggregation queries over historical data
• u_write_event: Inject new time series data from workflows
• u_writeback_http: Send HTTP requests from WASM
• u_writeback_ws: Send WebSocket messages to clients

​

Performance Characteristics

​

Memory Management

• Debug Mode: Uses DebugAllocator for leak detection
• Release Mode: 2GB fixed buffer allocator for zero-allocation operations

​

Concurrency

• Lock-free atomic operations for connection/query ID generation
• Mutex-protected shared state for query events and connections
• Channel-based message passing between ingestion and processing

​

Data Encoding

1. Delta Encoding: Zigzag varint delta encoding for faster queries
2. Gorilla Encoding: Delta-of-delta + XOR compression for better compression ratios

​

Configuration

​

Build-Time Configuration

pub const TsmTree = TsmTreeImpl(
    100_000,  // max_level: Maximum tree depth
    4096,     // page_size: Page size in bytes
    .gorilla  // ts_encoding: Timestamp encoding strategy
);

​

Runtime Configuration

• Channel Capacity: 16,384 events (CHANNEL_CAPACITY = 8192 * 2)
• Cache Flush Threshold: 1,000,000 data points (MAX_CACHE_POINTS)
• Max Concurrent Queries: 16 per server instance

​

Next Steps