Cobalt Docs — Cloud-Native Telemetry & Schema Specification
Unified binary-safe telemetry envelope, batch ingestion semantics, and deterministic trace correlation for distributed microservice meshes.
Zero-Copy Framing
Length-prefixed frame parsing designed for HTTP/2 and HTTP/3 multiplexed streams.
Deterministic Schema
Strict backward-compatible protobuf & JSON wire encoding across minor releases.
Backpressure Aware
Adaptive sliding window controls prevent downstream collector queue saturation.
Pipeline Architecture
Collectors emit structured metric batches over persistent TLS 1.3 channels. Edge aggregators validate envelope checksums and route partitions by tenant hash before committing to cold storage.
Event Envelope Fields
| Field | Type | Description |
|---|---|---|
trace_id | string (128-bit hex) | Globally unique distributed trace identifier. |
span_ns | uint64 | Monotonic nanosecond timestamp at span origin. |
payload_crc32 | uint32 | IEEE CRC32 integrity verification over compressed frame body. |
compression | enum | Negotiated codec: none, zstd, or lz4. |
Ingestion Endpoints
POST /v2/telemetry/ingest HTTP/2
Host: cobaltdocs.org
Content-Type: application/x-cobalt-batch
X-Schema-Version: 2.4.0
{
"service": "edge-aggregator",
"partition": "us-west-02",
"samples": 128,
"checksum": "0x94af12c0"
}
Quick SDK Integration
from cobalt_telemetry import Client, BatchConfig
client = Client(
endpoint="https://cobaltdocs.org",
config=BatchConfig(max_frame_bytes=65536, compression="zstd")
)
client.emit("worker.heartbeat", {"status": "healthy", "latency_ms": 12.4})