feat(telemetry): restructure OTLP export into per-session resource blocks

The writer now opens a new resourceLogs/resourceSpans/resourceMetrics
block whenever the producing event's session context or UTC date changes,
building the resource from that event's context instead of the exporting
session's. This fixes resource attribution for multi-session exports and
removes the three coder.event.* provenance attributes from every record.

Within a block, metric data points are grouped under one metrics[] entry
per (name, unit) as the OTLP proto expects, instead of one single-point
metric per event measurement. Cumulative counter totals and anchors reset
at block boundaries, mirroring how OTel models a process restart.

Zip entries now deflate at level 9; exports run on demand, so CPU cost
is irrelevant next to bundle size.

Author: EhabY

src/instrumentation/CONVENTIONS.md

@@ -115,6 +115,8 @@ Coder's own pipeline, so a bare `cache_source` can't collide with a future OTel
 - **Measurements** are raw numbers. Don't pre-bucket into string labels: both
   export as record attributes, and a query can bucket the raw number at read
   time. `result` and `durationMs` are framework-managed and cannot be set.
+  `durationMs` never reaches OTLP; the export derives span start/end times
+  from it.
 - **Units.** There is no unit field at emit time, so put the unit in the
   measurement key as a `_ms` / `_seconds` / `_mbits` suffix, the same way for
   every event.

src/instrumentation/EVENTS.md

@@ -82,9 +82,8 @@ context.
 On OTLP export the context becomes resource attributes (`service.name:
 coder-vscode-extension`, `service.version`, `service.instance.id`, `host.id`,
 `host.arch`, `os.type`, `os.version`, `vscode.platform.name`,
-`vscode.platform.version`, `coder.deployment.url`) plus per-record provenance
-(`coder.event.extension_version`, `coder.event.session_id`,
-`coder.event.deployment_url`).
+`vscode.platform.version`, `coder.deployment.url`) on the resource block
+holding the producing session's records.
 
 ## Consuming exports
 
@@ -97,7 +96,11 @@ date range in one of two formats:
   ad-hoc processing.
 - **OTLP**: a zip of standard OTLP/JSON envelopes (spans in `traces.json`,
   logs in `logs.json`, metric events as data points in `metrics.json`) plus
-  a `manifest.json` describing the export. Feed these to any OTel-compatible
+  a `manifest.json` describing the export. Each envelope holds one resource
+  block per producing session and UTC date, carrying that session's context
+  as resource attributes; within a block, metric data points are grouped
+  under one `metrics[]` entry per metric name and unit, and cumulative
+  counters restart at the block boundary. Feed these to any OTel-compatible
   tool that ingests OTLP/JSON, such as an OpenTelemetry Collector pipeline or
   your observability backend's import tooling.
 

src/telemetry/export/writers/otlp/envelope.ts

@@ -2,17 +2,24 @@ import { createWriteStream } from "node:fs";
 
 import { wrapError } from "../../../../error/errorUtils";
 
-/** `append` is not re-entrant. */
+/** `openBlock` and `append` are not re-entrant. */
 export interface EnvelopeFile {
+	/** Opens a new block, closing the previous one with the block suffix. */
+	openBlock(prefix: string): Promise<void>;
+	/** Appends one record to the open block; rejects if no block is open. */
 	append(value: unknown): Promise<void>;
 	close(): Promise<void>;
 }
 
-/** Streams `<prefix>v1,v2,...<suffix>` JSON into `filePath`. */
+/**
+ * Streams `<filePrefix>block,block,...<fileSuffix>` JSON into `filePath`,
+ * where each block is `<prefix>v1,v2,...<blockSuffix>`.
+ */
 export async function openEnvelopeFile(
 	filePath: string,
-	prefix: string,
-	suffix: string,
+	filePrefix: string,
+	blockSuffix: string,
+	fileSuffix: string,
 ): Promise<EnvelopeFile> {
 	const stream = createWriteStream(filePath, { encoding: "utf8" });
 	// Open failures (ENOENT/EACCES) surface as 'error' events, not write
@@ -42,15 +49,28 @@ export async function openEnvelopeFile(
 		awaitOp((cb) => stream.write(chunk, "utf8", cb));
 
 	try {
-		await writeChunk(prefix);
+		await writeChunk(filePrefix);
 	} catch (err) {
 		stream.destroy();
 		throw wrapError("write", filePath, err);
 	}
+	let blockOpen = false;
 	let written = 0;
 	let closed = false;
 	return {
+		async openBlock(prefix) {
+			try {
+				await writeChunk((blockOpen ? blockSuffix + "," : "") + prefix);
+			} catch (err) {
+				throw wrapError("write", filePath, err);
+			}
+			blockOpen = true;
+			written = 0;
+		},
 		async append(value) {
+			if (!blockOpen) {
+				throw new Error(`No open block to append to in ${filePath}`);
+			}
 			try {
 				await writeChunk((written === 0 ? "" : ",") + JSON.stringify(value));
 			} catch (err) {
@@ -64,7 +84,7 @@ export async function openEnvelopeFile(
 			}
 			closed = true;
 			try {
-				await writeChunk(suffix);
+				await writeChunk((blockOpen ? blockSuffix : "") + fileSuffix);
 				await awaitOp((cb) => stream.end(cb));
 			} catch (err) {
 				// destroy() never throws synchronously, so it can't mask the

src/telemetry/export/writers/otlp/metricBlockBuffer.ts

@@ -0,0 +1,53 @@
+import type { OtlpGaugePoint, OtlpMetric, OtlpSumPoint } from "./types";
+
+interface BufferedMetricSeries {
+	/** First record seen for the series; carries name/description/unit and sum metadata. */
+	readonly template: OtlpMetric;
+	readonly gaugePoints: OtlpGaugePoint[];
+	readonly sumPoints: OtlpSumPoint[];
+}
+
+/**
+ * Groups single-point metric records into one `metrics[]` entry per
+ * (name, unit, kind), as the OTLP metrics proto expects. The writer drains
+ * the buffer at block boundaries and at a point cap, bounding memory.
+ */
+export class MetricBlockBuffer {
+	readonly #series = new Map<string, BufferedMetricSeries>();
+	#points = 0;
+
+	/** Buffered data point count across all series. */
+	get points(): number {
+		return this.#points;
+	}
+
+	add(records: readonly OtlpMetric[]): void {
+		for (const record of records) {
+			const kind = record.gauge !== undefined ? "gauge" : "sum";
+			const key = `${record.name}\x00${record.unit}\x00${kind}`;
+			let series = this.#series.get(key);
+			if (series === undefined) {
+				series = { template: record, gaugePoints: [], sumPoints: [] };
+				this.#series.set(key, series);
+			}
+			series.gaugePoints.push(...(record.gauge?.dataPoints ?? []));
+			series.sumPoints.push(...(record.sum?.dataPoints ?? []));
+			this.#points +=
+				(record.gauge?.dataPoints.length ?? 0) +
+				(record.sum?.dataPoints.length ?? 0);
+		}
+	}
+
+	/** Returns the grouped metrics in first-seen order and clears the buffer. */
+	drain(): OtlpMetric[] {
+		const drained = [...this.#series.values()].map(
+			({ template, gaugePoints, sumPoints }): OtlpMetric =>
+				template.sum !== undefined
+					? { ...template, sum: { ...template.sum, dataPoints: sumPoints } }
+					: { ...template, gauge: { dataPoints: gaugePoints } },
+		);
+		this.#series.clear();
+		this.#points = 0;
+		return drained;
+	}
+}

src/telemetry/export/writers/otlp/records.ts

@@ -45,7 +45,10 @@ export const ENVELOPES = {
 } as const satisfies Record<Signal, EnvelopeSpec>;
 
 const OTLP_SCHEMA_URL = "https://opentelemetry.io/schemas/1.24.0";
-export const ENVELOPE_SUFFIX = "]}]}]}\n";
+/** Closes one resource block: records array, scope wrapper, resource wrapper. */
+export const RESOURCE_BLOCK_SUFFIX = "]}]}";
+/** Closes the top-level resource list opened by `envelopeFilePrefix`. */
+export const ENVELOPE_FILE_SUFFIX = "]}\n";
 
 const AGGREGATION_TEMPORALITY_CUMULATIVE = 2;
 // OTLP proto SpanKind reserves 0 for UNSPECIFIED; @opentelemetry/api values
@@ -55,12 +58,18 @@ const OTLP_SPAN_KIND_OFFSET = 1;
 // OtlpStatus.code is a wire-format int, so compare against a numeric alias.
 const OTLP_STATUS_ERROR: number = SpanStatusCode.ERROR;
 
-export function envelopePrefix(
+/** Opens the envelope's top-level resource list (`resourceLogs` etc.). */
+export function envelopeFilePrefix(envelope: EnvelopeSpec): string {
+	return `{"${envelope.resourceKey}":[`;
+}
+
+/** Opens one resource block: resource and scope wrappers up to the records array. */
+export function resourceBlockPrefix(
 	envelope: EnvelopeSpec,
 	resource: string,
 	scope: string,
 ): string {
-	return `{"${envelope.resourceKey}":[{"resource":${resource},"schemaUrl":"${OTLP_SCHEMA_URL}","${envelope.scopeKey}":[{"scope":${scope},"schemaUrl":"${OTLP_SCHEMA_URL}","${envelope.recordsKey}":[`;
+	return `{"resource":${resource},"schemaUrl":"${OTLP_SCHEMA_URL}","${envelope.scopeKey}":[{"scope":${scope},"schemaUrl":"${OTLP_SCHEMA_URL}","${envelope.recordsKey}":[`;
 }
 
 export interface CumulativeState {
@@ -73,9 +82,10 @@ export function newCumulativeState(): CumulativeState {
 }
 
 /**
- * Resource attributes describe the export tool (forwarder), not the original
- * producer. Per-event identity is stamped on each record by
- * `eventContextAttributes` so multi-session exports preserve provenance.
+ * Resource attributes identifying the session that produced a resource
+ * block's records. The writer builds one per block from the producing
+ * event's context, so multi-session exports attribute every record to its
+ * own session.
  */
 export function otlpResource(context: TelemetryContext) {
 	return {
@@ -94,19 +104,6 @@ export function otlpResource(context: TelemetryContext) {
 	};
 }
 
-/**
- * Per-event identity stamped on every record so multi-session exports stay
- * attributable. Spread LAST in attribute maps so caller-supplied properties
- * keyed `coder.event.*` cannot override the canonical provenance.
- */
-function eventContextAttributes(event: TelemetryEvent): Record<string, string> {
-	return {
-		"coder.event.extension_version": event.context.extensionVersion,
-		"coder.event.session_id": event.context.sessionId,
-		"coder.event.deployment_url": event.context.deploymentUrl,
-	};
-}
-
 export function otlpScope(version: string) {
 	return { name: "coder.vscode-coder.telemetry.export", version };
 }
@@ -130,7 +127,6 @@ export function logRecord(event: TelemetryEvent): OtlpLogRecord {
 			...event.properties,
 			...event.measurements,
 			...(event.error && exceptionAttributes(event.error)),
-			...eventContextAttributes(event),
 		}),
 		...(event.traceId !== undefined && { traceId: event.traceId }),
 		...(event.parentEventId !== undefined && { spanId: event.parentEventId }),
@@ -149,7 +145,6 @@ export function spanRecord(
 		...event.properties,
 		...measurements,
 		"coder.event_name": event.eventName,
-		...eventContextAttributes(event),
 	};
 	// OTel wants every error span to carry a low-cardinality error.type, so
 	// backfill the exception type or code, falling back to OTel's _OTHER sentinel.
@@ -231,7 +226,6 @@ export function metricRecords(
 		attributes: keyValues({
 			...event.properties,
 			"coder.event_name": event.eventName,
-			...eventContextAttributes(event),
 		}),
 		timeNano,
 		windowStartNano,