@rivetkit/traces 2.1.0-rc.1

package/dist/tsup/v1-DovAIc7f.d.ts

@@ -0,0 +1,118 @@
+type u32 = number;
+type u64 = bigint;
+type Cbor = ArrayBuffer;
+type TraceId = ArrayBuffer;
+type SpanId = ArrayBuffer;
+type StringId = u32;
+type KeyValue = {
+    readonly key: StringId;
+    readonly value: Cbor;
+};
+type Attributes = readonly KeyValue[];
+declare enum SpanStatusCode {
+    UNSET = "UNSET",
+    OK = "OK",
+    ERROR = "ERROR"
+}
+type SpanStatus = {
+    readonly code: SpanStatusCode;
+    readonly message: string | null;
+};
+type SpanLink = {
+    readonly traceId: TraceId;
+    readonly spanId: SpanId;
+    readonly traceState: string | null;
+    readonly attributes: Attributes;
+    readonly droppedAttributesCount: u32;
+};
+type SpanStart = {
+    readonly traceId: TraceId;
+    readonly spanId: SpanId;
+    readonly parentSpanId: SpanId | null;
+    readonly name: StringId;
+    readonly kind: u32;
+    readonly traceState: string | null;
+    readonly flags: u32;
+    readonly attributes: Attributes;
+    readonly droppedAttributesCount: u32;
+    readonly links: readonly SpanLink[];
+    readonly droppedLinksCount: u32;
+};
+type SpanUpdate = {
+    readonly spanId: SpanId;
+    readonly attributes: Attributes;
+    readonly droppedAttributesCount: u32;
+    readonly status: SpanStatus | null;
+};
+type SpanEvent = {
+    readonly spanId: SpanId;
+    readonly name: StringId;
+    readonly attributes: Attributes;
+    readonly droppedAttributesCount: u32;
+};
+type SpanEnd = {
+    readonly spanId: SpanId;
+    readonly status: SpanStatus | null;
+};
+type SpanSnapshot = {
+    readonly traceId: TraceId;
+    readonly spanId: SpanId;
+    readonly parentSpanId: SpanId | null;
+    readonly name: StringId;
+    readonly kind: u32;
+    readonly startTimeUnixNs: u64;
+    readonly traceState: string | null;
+    readonly flags: u32;
+    readonly attributes: Attributes;
+    readonly droppedAttributesCount: u32;
+    readonly links: readonly SpanLink[];
+    readonly droppedLinksCount: u32;
+    readonly status: SpanStatus | null;
+};
+type RecordBody = {
+    readonly tag: "SpanStart";
+    readonly val: SpanStart;
+} | {
+    readonly tag: "SpanEvent";
+    readonly val: SpanEvent;
+} | {
+    readonly tag: "SpanUpdate";
+    readonly val: SpanUpdate;
+} | {
+    readonly tag: "SpanEnd";
+    readonly val: SpanEnd;
+} | {
+    readonly tag: "SpanSnapshot";
+    readonly val: SpanSnapshot;
+};
+type Record = {
+    readonly timeOffsetNs: u64;
+    readonly body: RecordBody;
+};
+type SpanRecordKey = {
+    readonly prefix: u32;
+    readonly bucketStartSec: u64;
+    readonly chunkId: u32;
+    readonly recordIndex: u32;
+};
+type ActiveSpanRef = {
+    readonly spanId: SpanId;
+    readonly startKey: SpanRecordKey;
+    readonly latestSnapshotKey: SpanRecordKey | null;
+};
+type Chunk = {
+    readonly baseUnixNs: u64;
+    readonly strings: readonly string[];
+    readonly records: readonly Record[];
+    readonly activeSpans: readonly ActiveSpanRef[];
+};
+type ReadRangeWire = {
+    readonly startTimeMs: u64;
+    readonly endTimeMs: u64;
+    readonly limit: u32;
+    readonly clamped: boolean;
+    readonly baseChunks: readonly Chunk[];
+    readonly chunks: readonly Chunk[];
+};
+
+export type { ReadRangeWire as R };

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@rivetkit/traces",
+  "version": "2.1.0-rc.1",
+  "description": "Generic tracing storage and OTLP export for RivetKit",
+  "license": "Apache-2.0",
+  "type": "module",
+  "files": [
+    "dist",
+    "src",
+    "schemas",
+    "package.json"
+  ],
+  "exports": {
+    ".": {
+      "browser": {
+        "types": "./dist/tsup/index.browser.d.ts",
+        "import": "./dist/tsup/index.browser.js",
+        "require": "./dist/tsup/index.browser.cjs"
+      },
+      "import": {
+        "types": "./dist/tsup/index.d.ts",
+        "default": "./dist/tsup/index.js"
+      },
+      "require": {
+        "types": "./dist/tsup/index.d.cts",
+        "default": "./dist/tsup/index.cjs"
+      }
+    },
+    "./encoding": {
+      "import": {
+        "types": "./dist/tsup/encoding.d.ts",
+        "default": "./dist/tsup/encoding.js"
+      },
+      "require": {
+        "types": "./dist/tsup/encoding.d.cts",
+        "default": "./dist/tsup/encoding.cjs"
+      }
+    },
+    "./otlp": {
+      "import": {
+        "types": "./dist/tsup/otlp-entry.d.ts",
+        "default": "./dist/tsup/otlp-entry.js"
+      },
+      "require": {
+        "types": "./dist/tsup/otlp-entry.d.cts",
+        "default": "./dist/tsup/otlp-entry.cjs"
+      }
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@rivetkit/bare-ts": "^0.6.2",
+    "fdb-tuple": "^1.0.0",
+    "cbor-x": "^1.6.0",
+    "vbare": "^0.0.4"
+  },
+  "devDependencies": {
+    "@bare-ts/tools": "^0.13.0",
+    "@types/node": "^22.13.1",
+    "commander": "^12.0.0",
+    "tsx": "^4.7.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.1.1"
+  },
+  "scripts": {
+    "build": "pnpm run compile:bare && tsup src/index.ts src/index.browser.ts src/encoding.ts src/otlp-entry.ts",
+    "compile:bare": "tsx scripts/compile-bare.ts compile schemas/v1.bare -o dist/schemas/v1.ts",
+    "check-types": "pnpm run compile:bare && tsc --noEmit",
+    "test": "pnpm run compile:bare && vitest run"
+  }
+}

package/schemas/v1.bare

@@ -0,0 +1,177 @@
+# Traces BARE Schema v1
+#
+# Internal storage format for @rivetkit/traces. Records are stored as an
+# append-only Span[] stream and exported to OTLP v1 JSON on read.
+#
+# OTLP spec: https://opentelemetry.io/docs/specs/otlp/
+# OTel trace data model: https://opentelemetry.io/docs/specs/otel/trace/api/
+# OTLP proto: https://github.com/open-telemetry/opentelemetry-proto
+
+# Opaque CBOR bytes for attribute values
+# See cbor-x for encoding/decoding
+# https://github.com/kriszyp/cbor-x
+#
+# NOTE: AnyValue conversion happens at export time.
+#
+# BARE type for raw bytes
+#
+# type Cbor data
+
+# Raw bytes types
+
+type Cbor data
+
+type TraceId data
+
+type SpanId data
+
+# String table index
+
+type StringId u32
+
+# KeyValue (attribute)
+
+type KeyValue struct {
+	key: StringId
+	value: Cbor
+}
+
+type Attributes list<KeyValue>
+
+# Status
+
+type SpanStatusCode enum {
+	UNSET
+	OK
+	ERROR
+}
+
+type SpanStatus struct {
+	code: SpanStatusCode
+	message: optional<str>
+}
+
+# Link
+
+type SpanLink struct {
+	traceId: TraceId
+	spanId: SpanId
+	traceState: optional<str>
+	attributes: Attributes
+	droppedAttributesCount: u32
+}
+
+# Start
+
+type SpanStart struct {
+	traceId: TraceId
+	spanId: SpanId
+	parentSpanId: optional<SpanId>
+	name: StringId
+	kind: u32
+	traceState: optional<str>
+	flags: u32
+	attributes: Attributes
+	droppedAttributesCount: u32
+	links: list<SpanLink>
+	droppedLinksCount: u32
+}
+
+# Update
+
+type SpanUpdate struct {
+	spanId: SpanId
+	attributes: Attributes
+	droppedAttributesCount: u32
+	status: optional<SpanStatus>
+}
+
+# Event
+
+type SpanEvent struct {
+	spanId: SpanId
+	name: StringId
+	attributes: Attributes
+	droppedAttributesCount: u32
+}
+
+# End
+
+type SpanEnd struct {
+	spanId: SpanId
+	status: optional<SpanStatus>
+}
+
+# Snapshot
+
+type SpanSnapshot struct {
+	traceId: TraceId
+	spanId: SpanId
+	parentSpanId: optional<SpanId>
+	name: StringId
+	kind: u32
+	startTimeUnixNs: u64
+	traceState: optional<str>
+	flags: u32
+	attributes: Attributes
+	droppedAttributesCount: u32
+	links: list<SpanLink>
+	droppedLinksCount: u32
+	status: optional<SpanStatus>
+}
+
+# Record
+
+type RecordBody union {
+	SpanStart |
+	SpanEvent |
+	SpanUpdate |
+	SpanEnd |
+	SpanSnapshot
+}
+
+type Record struct {
+	timeOffsetNs: u64
+	body: RecordBody
+}
+
+# Record pointer
+
+type SpanRecordKey struct {
+	prefix: u32
+	bucketStartSec: u64
+	chunkId: u32
+	recordIndex: u32
+}
+
+# Active span reference (stored in every chunk)
+
+type ActiveSpanRef struct {
+	spanId: SpanId
+	startKey: SpanRecordKey
+	latestSnapshotKey: optional<SpanRecordKey>
+}
+
+# Chunk container
+
+type Chunk struct {
+	baseUnixNs: u64
+	strings: list<str>
+	records: list<Record>
+	activeSpans: list<ActiveSpanRef>
+}
+
+# Read range response wire format.
+# This reuses existing chunk structs for compactness.
+#
+# baseChunks contains the minimal records needed to hydrate spans that
+# started before the query range (e.g., start or snapshot records).
+
+type ReadRangeWire struct {
+	startTimeMs: u64
+	endTimeMs: u64
+	limit: u32
+	clamped: bool
+	baseChunks: list<Chunk>
+	chunks: list<Chunk>
+}

package/schemas/versioned.ts

@@ -0,0 +1,99 @@
+import * as bare from "@rivetkit/bare-ts";
+import { createVersionedDataHandler } from "vbare";
+import * as v1 from "../dist/schemas/v1";
+
+export const CURRENT_VERSION = 1;
+
+export type {
+	ActiveSpanRef,
+	Attributes,
+	Chunk,
+	KeyValue,
+	ReadRangeWire,
+	Record,
+	RecordBody,
+	SpanEnd,
+	SpanEvent,
+	SpanId,
+	SpanLink,
+	SpanRecordKey,
+	SpanSnapshot,
+	SpanStart,
+	SpanStatus,
+	SpanUpdate,
+	StringId,
+	TraceId,
+} from "../dist/schemas/v1";
+
+export { SpanStatusCode } from "../dist/schemas/v1";
+
+export const CHUNK_VERSIONED = createVersionedDataHandler<v1.Chunk>({
+	deserializeVersion: (bytes, version) => {
+		switch (version) {
+			case 1:
+				return decodeChunk(bytes);
+			default:
+				throw new Error(`Unknown Chunk version ${version}`);
+		}
+	},
+	serializeVersion: (data, version) => {
+		switch (version) {
+			case 1:
+				return encodeChunk(data as v1.Chunk);
+			default:
+				throw new Error(`Unknown Chunk version ${version}`);
+		}
+	},
+	deserializeConverters: () => [],
+	serializeConverters: () => [],
+});
+
+export const READ_RANGE_VERSIONED =
+	createVersionedDataHandler<v1.ReadRangeWire>({
+		deserializeVersion: (bytes, version) => {
+			switch (version) {
+				case 1:
+					return v1.decodeReadRangeWire(bytes);
+				default:
+					throw new Error(`Unknown ReadRangeWire version ${version}`);
+			}
+		},
+		serializeVersion: (data, version) => {
+			switch (version) {
+				case 1:
+					return v1.encodeReadRangeWire(data as v1.ReadRangeWire);
+				default:
+					throw new Error(`Unknown ReadRangeWire version ${version}`);
+			}
+		},
+		deserializeConverters: () => [],
+		serializeConverters: () => [],
+	});
+
+export { decodeReadRangeWire, encodeReadRangeWire } from "../dist/schemas/v1";
+
+const recordConfig = bare.Config({});
+const chunkConfig = bare.Config({});
+
+export function encodeChunk(chunk: v1.Chunk): Uint8Array {
+	const bc = new bare.ByteCursor(
+		new Uint8Array(chunkConfig.initialBufferLength),
+		chunkConfig,
+	);
+	v1.writeChunk(bc, chunk);
+	return new Uint8Array(bc.view.buffer, bc.view.byteOffset, bc.offset);
+}
+
+export function decodeChunk(bytes: Uint8Array): v1.Chunk {
+	const bc = new bare.ByteCursor(bytes, chunkConfig);
+	return v1.readChunk(bc);
+}
+
+export function encodeRecord(record: v1.Record): Uint8Array {
+	const bc = new bare.ByteCursor(
+		new Uint8Array(recordConfig.initialBufferLength),
+		recordConfig,
+	);
+	v1.writeRecord(bc, record);
+	return new Uint8Array(bc.view.buffer, bc.view.byteOffset, bc.offset);
+}

package/src/encoding.ts

@@ -0,0 +1,18 @@
+import {
+	CURRENT_VERSION,
+	READ_RANGE_VERSIONED,
+	type ReadRangeWire,
+} from "../schemas/versioned.js";
+
+export type { ReadRangeWire };
+
+export function encodeReadRangeWire(wire: ReadRangeWire): Uint8Array {
+	return READ_RANGE_VERSIONED.serializeWithEmbeddedVersion(
+		wire,
+		CURRENT_VERSION,
+	);
+}
+
+export function decodeReadRangeWire(bytes: Uint8Array): ReadRangeWire {
+	return READ_RANGE_VERSIONED.deserializeWithEmbeddedVersion(bytes);
+}

package/src/index.browser.ts

@@ -0,0 +1,13 @@
+export { createNoopTraces } from "./noop.js";
+
+// Browser stub: createTraces is server-only (uses node:async_hooks, node:crypto,
+// fdb-tuple). This module is selected via the "browser" export condition so that
+// bundlers like Vite never pull in the real implementation when resolving
+// @rivetkit/traces in a browser context.  The function is never actually called
+// in the browser; it only exists because tsup chunk-splitting may place the
+// import in a shared chunk also reached by client code.
+export function createTraces(): never {
+	throw new Error(
+		"createTraces is not available in the browser. This is a server-only API.",
+	);
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+export {
+	createTraces,
+} from "./traces.js";
+export { createNoopTraces } from "./noop.js";
+export type {
+	EndSpanOptions,
+	EventOptions,
+	ReadRangeOptions,
+	ReadRangeResult,
+	ReadRangeWire,
+	SpanHandle,
+	SpanStatusInput,
+	StartSpanOptions,
+	Traces,
+	TracesDriver,
+	TracesOptions,
+	UpdateSpanOptions,
+} from "./types.js";
+export type {
+	OtlpAnyValue,
+	OtlpExportTraceServiceRequestJson,
+	OtlpInstrumentationScope,
+	OtlpKeyValue,
+	OtlpResource,
+	OtlpResourceSpans,
+	OtlpScopeSpans,
+	OtlpSpan,
+	OtlpSpanEvent,
+	OtlpSpanLink,
+	OtlpSpanStatus,
+} from "./otlp.js";

package/src/noop.ts

@@ -0,0 +1,81 @@
+import type { OtlpExportTraceServiceRequestJson } from "./otlp.js";
+import type {
+	EndSpanOptions,
+	EventOptions,
+	ReadRangeOptions,
+	ReadRangeResult,
+	ReadRangeWire,
+	SpanHandle,
+	SpanStatusInput,
+	StartSpanOptions,
+	Traces,
+	UpdateSpanOptions,
+} from "./types.js";
+
+const U32_MAX = 0xffff_ffff;
+
+const NOOP_SPAN: SpanHandle = {
+	spanId: new Uint8Array(8),
+	traceId: new Uint8Array(16),
+	isActive: () => false,
+};
+
+function createEmptyOtlpExport(): OtlpExportTraceServiceRequestJson {
+	return {
+		resourceSpans: [
+			{
+				scopeSpans: [{ spans: [] }],
+			},
+		],
+	};
+}
+
+/**
+ * Implements the Traces contract without persisting or exporting trace data.
+ */
+export function createNoopTraces(): Traces<OtlpExportTraceServiceRequestJson> {
+	return {
+		startSpan(_name: string, _options?: StartSpanOptions): SpanHandle {
+			return NOOP_SPAN;
+		},
+		updateSpan(_handle: SpanHandle, _options: UpdateSpanOptions): void {},
+		setAttributes(
+			_handle: SpanHandle,
+			_attributes: Record<string, unknown>,
+		): void {},
+		setStatus(_handle: SpanHandle, _status: SpanStatusInput): void {},
+		endSpan(_handle: SpanHandle, _options?: EndSpanOptions): void {},
+		emitEvent(
+			_handle: SpanHandle,
+			_name: string,
+			_options?: EventOptions,
+		): void {},
+		withSpan<T>(_handle: SpanHandle, fn: () => T): T {
+			return fn();
+		},
+		getCurrentSpan(): SpanHandle | null {
+			return null;
+		},
+		async flush(): Promise<boolean> {
+			return false;
+		},
+		async readRange(
+			_options: ReadRangeOptions,
+		): Promise<ReadRangeResult<OtlpExportTraceServiceRequestJson>> {
+			return {
+				otlp: createEmptyOtlpExport(),
+				clamped: false,
+			};
+		},
+		async readRangeWire(options: ReadRangeOptions): Promise<ReadRangeWire> {
+			return {
+				startTimeMs: BigInt(options.startMs),
+				endTimeMs: BigInt(options.endMs),
+				limit: Math.max(0, Math.min(U32_MAX, Math.floor(options.limit))),
+				clamped: false,
+				baseChunks: [],
+				chunks: [],
+			};
+		},
+	};
+}

package/src/otlp-entry.ts

@@ -0,0 +1,18 @@
+export { readRangeWireToOtlp } from "./read-range.js";
+export {
+	anyValueFromCborBytes,
+	anyValueFromJs,
+	base64FromBytes,
+	hexFromBytes,
+	type OtlpAnyValue,
+	type OtlpExportTraceServiceRequestJson,
+	type OtlpInstrumentationScope,
+	type OtlpKeyValue,
+	type OtlpResource,
+	type OtlpResourceSpans,
+	type OtlpScopeSpans,
+	type OtlpSpan,
+	type OtlpSpanEvent,
+	type OtlpSpanLink,
+	type OtlpSpanStatus,
+} from "./otlp.js";