Cobalt Docs v2.4 Spec

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

FieldTypeDescription
trace_idstring (128-bit hex)Globally unique distributed trace identifier.
span_nsuint64Monotonic nanosecond timestamp at span origin.
payload_crc32uint32IEEE CRC32 integrity verification over compressed frame body.
compressionenumNegotiated 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})