Message Format
Each WebSocket frame contains a single metric encoded as:Field Breakdown
| Field | Type | Size | Description |
|---|---|---|---|
timestamp | i64 | 8 bytes | Unix epoch timestamp in microseconds |
value | f64 | 8 bytes | IEEE 754 double-precision metric value |
series_len | u16 | 2 bytes | Length of series name in bytes |
tag_count | u16 | 2 bytes | Number of tags |
series | UTF-8 | Variable | Series name (max 65535 bytes) |
tags | Variable | Variable | Repeated tag entries |
Tag Encoding
Each tag is encoded as:tag_len(u16, 2 bytes): Length of tag string in bytestag_utf8(variable): UTF-8 encoded tag (format:key=value)
tag_count times.
Protocol Implementation
The server decodes messages using the following logic (extracted fromsrc/main.zig:424-469):
Encoding Example
For a metric with:- Timestamp:
1709481600000000(microseconds) - Value:
23.5 - Series:
"temp" - Tags:
["sensor=1", "env=dev"]
-
Header (20 bytes):
- Timestamp:
0x00 0x50 0xB8 0x8E 0x0E 0x18 0x06 0x00(i64 LE) - Value:
0x00 0x00 0x00 0x00 0x00 0x80 0x37 0x40(f64 LE) - Series length:
0x04 0x00(4 bytes) - Tag count:
0x02 0x00(2 tags)
- Timestamp:
-
Series (4 bytes):
"temp":0x74 0x65 0x6D 0x70
-
Tags:
- Tag 1 length:
0x08 0x00(8 bytes) - Tag 1:
"sensor=1":0x73 0x65 0x6E 0x73 0x6F 0x72 0x3D 0x31 - Tag 2 length:
0x07 0x00(7 bytes) - Tag 2:
"env=dev":0x65 0x6E 0x76 0x3D 0x64 0x65 0x76
- Tag 1 length:
Validation Rules
The server enforces these validation rules:- Minimum message size: Must be at least 20 bytes (header)
- Complete frames: Message length must exactly match declared sizes
- UTF-8 encoding: Series and tags must be valid UTF-8
- Size limits:
- Series name: max 65535 bytes
- Tag count: max 65535 tags
- Individual tag: max 65535 bytes
InvalidMessage error and close the connection.
Connection Lifecycle
- Connect: Establish WebSocket connection to
ws://host:2077 - Send: Send binary frames containing encoded metrics
- Stream: Connection remains open for continuous streaming
- Close: Gracefully close with status code 1000
Performance Characteristics
- Minimal overhead: Fixed 20-byte header + UTF-8 string data
- Zero-copy parsing: Server parses directly from WebSocket frames
- High throughput: Supports 100K+ events/second on single connection
- Low latency: Sub-millisecond processing time per message
Next Steps
Client SDKs
Use official SDKs that handle protocol encoding automatically