@clinebot/core 0.0.5 → 0.0.6

package/src/telemetry/LoggerTelemetryAdapter.ts

@@ -0,0 +1,114 @@
+import type { BasicLogger } from "@clinebot/shared";
+import type {
+	ITelemetryAdapter,
+	TelemetryProperties,
+} from "./ITelemetryAdapter";
+
+export interface LoggerTelemetryAdapterOptions {
+	logger?: BasicLogger;
+	name?: string;
+	enabled?: boolean | (() => boolean);
+}
+
+export class LoggerTelemetryAdapter implements ITelemetryAdapter {
+	readonly name: string;
+
+	private readonly logger?: BasicLogger;
+	private readonly enabled: boolean | (() => boolean);
+
+	constructor(options: LoggerTelemetryAdapterOptions = {}) {
+		this.name = options.name ?? "LoggerTelemetryAdapter";
+		this.logger = options.logger;
+		this.enabled = options.enabled ?? true;
+	}
+
+	emit(event: string, properties?: TelemetryProperties): void {
+		if (!this.isEnabled()) {
+			return;
+		}
+		this.logger?.info?.("telemetry.event", {
+			adapter: this.name,
+			event,
+			properties,
+		});
+	}
+
+	emitRequired(event: string, properties?: TelemetryProperties): void {
+		this.logger?.warn?.("telemetry.required_event", {
+			adapter: this.name,
+			event,
+			properties,
+		});
+	}
+
+	recordCounter(
+		name: string,
+		value: number,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required?: boolean,
+	): void {
+		if (!required && !this.isEnabled()) {
+			return;
+		}
+		this.logger?.debug?.("telemetry.metric", {
+			adapter: this.name,
+			instrument: "counter",
+			name,
+			value,
+			attributes,
+			description,
+			required: required === true,
+		});
+	}
+
+	recordHistogram(
+		name: string,
+		value: number,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required?: boolean,
+	): void {
+		if (!required && !this.isEnabled()) {
+			return;
+		}
+		this.logger?.debug?.("telemetry.metric", {
+			adapter: this.name,
+			instrument: "histogram",
+			name,
+			value,
+			attributes,
+			description,
+			required: required === true,
+		});
+	}
+
+	recordGauge(
+		name: string,
+		value: number | null,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required?: boolean,
+	): void {
+		if (!required && !this.isEnabled()) {
+			return;
+		}
+		this.logger?.debug?.("telemetry.metric", {
+			adapter: this.name,
+			instrument: "gauge",
+			name,
+			value,
+			attributes,
+			description,
+			required: required === true,
+		});
+	}
+
+	isEnabled(): boolean {
+		return typeof this.enabled === "function" ? this.enabled() : this.enabled;
+	}
+
+	async flush(): Promise<void> {}
+
+	async dispose(): Promise<void> {}
+}

package/src/telemetry/OpenTelemetryAdapter.test.ts

@@ -0,0 +1,157 @@
+import type { LoggerProvider } from "@opentelemetry/sdk-logs";
+import type { MeterProvider } from "@opentelemetry/sdk-metrics";
+import { describe, expect, it, vi } from "vitest";
+import { OpenTelemetryAdapter } from "./OpenTelemetryAdapter";
+
+describe("OpenTelemetryAdapter", () => {
+	it("emits events in the telemetry service log format", () => {
+		const emit = vi.fn();
+		const adapter = new OpenTelemetryAdapter({
+			metadata: makeMetadata(),
+			distinctId: "user-123",
+			commonProperties: {
+				organization_id: "org-1",
+			},
+			loggerProvider: {
+				getLogger: () => ({ emit }),
+			} as unknown as LoggerProvider,
+		});
+
+		adapter.emit("task.created", {
+			ulid: "01HXYZ",
+			nested: {
+				mode: "act",
+			},
+			items: ["a", "b"],
+			nullable: null,
+		});
+
+		expect(emit).toHaveBeenCalledWith({
+			severityText: "INFO",
+			body: "task.created",
+			attributes: expect.objectContaining({
+				ulid: "01HXYZ",
+				"nested.mode": "act",
+				items: JSON.stringify(["a", "b"]),
+				nullable: "null",
+				distinct_id: "user-123",
+				organization_id: "org-1",
+				extension_version: "1.2.3",
+				cline_type: "cli",
+				platform: "terminal",
+			}),
+		});
+	});
+
+	it("marks required events with the expected flag", () => {
+		const emit = vi.fn();
+		const adapter = new OpenTelemetryAdapter({
+			metadata: makeMetadata(),
+			loggerProvider: {
+				getLogger: () => ({ emit }),
+			} as unknown as LoggerProvider,
+			enabled: false,
+		});
+
+		adapter.emitRequired("user.opt_out");
+
+		expect(emit).toHaveBeenCalledWith({
+			severityText: "INFO",
+			body: "user.opt_out",
+			attributes: expect.objectContaining({
+				_required: true,
+			}),
+		});
+	});
+
+	it("records metrics with merged telemetry attributes and retires gauge series", () => {
+		const counterAdd = vi.fn();
+		const histogramRecord = vi.fn();
+		let gaugeCallback:
+			| ((result: {
+					observe: (
+						value: number,
+						attributes?: Record<string, string | number | boolean>,
+					) => void;
+			  }) => void)
+			| undefined;
+
+		const forceFlush = vi.fn().mockResolvedValue(undefined);
+		const shutdown = vi.fn().mockResolvedValue(undefined);
+
+		const adapter = new OpenTelemetryAdapter({
+			metadata: makeMetadata(),
+			distinctId: "user-123",
+			meterProvider: {
+				getMeter: () =>
+					({
+						createCounter: () => ({ add: counterAdd }),
+						createHistogram: () => ({ record: histogramRecord }),
+						createObservableGauge: () => ({
+							addCallback: (callback: typeof gaugeCallback) => {
+								gaugeCallback = callback;
+							},
+						}),
+					}) as never,
+				forceFlush,
+				shutdown,
+			} as unknown as MeterProvider,
+		});
+
+		adapter.recordCounter("cline.turns.total", 2, { ulid: "01HXYZ" });
+		adapter.recordHistogram("cline.api.duration.seconds", 1.5, {
+			ulid: "01HXYZ",
+		});
+		adapter.recordGauge("cline.workspace.active_roots", 3, { workspace: "a" });
+
+		expect(counterAdd).toHaveBeenCalledWith(
+			2,
+			expect.objectContaining({
+				ulid: "01HXYZ",
+				distinct_id: "user-123",
+				extension_version: "1.2.3",
+			}),
+		);
+		expect(histogramRecord).toHaveBeenCalledWith(
+			1.5,
+			expect.objectContaining({
+				ulid: "01HXYZ",
+				distinct_id: "user-123",
+			}),
+		);
+
+		const observe = vi.fn();
+		gaugeCallback?.({ observe });
+		expect(observe).toHaveBeenCalledWith(
+			3,
+			expect.objectContaining({
+				workspace: "a",
+				distinct_id: "user-123",
+			}),
+		);
+
+		adapter.recordGauge("cline.workspace.active_roots", null, {
+			workspace: "a",
+		});
+		const observeAfterRetire = vi.fn();
+		gaugeCallback?.({ observe: observeAfterRetire });
+		expect(observeAfterRetire).not.toHaveBeenCalled();
+
+		return Promise.all([adapter.flush(), adapter.dispose()]).then(() => {
+			expect(forceFlush).toHaveBeenCalledTimes(1);
+			expect(shutdown).toHaveBeenCalledTimes(1);
+		});
+	});
+});
+
+function makeMetadata() {
+	return {
+		extension_version: "1.2.3",
+		cline_type: "cli",
+		platform: "terminal",
+		platform_version: "1.0.0",
+		os_type: "darwin",
+		os_version: "24.0.0",
+		is_dev: "true",
+	};
+}

package/src/telemetry/OpenTelemetryAdapter.ts

@@ -0,0 +1,348 @@
+import type { Meter } from "@opentelemetry/api";
+import type { Logger as OpenTelemetryLogger } from "@opentelemetry/api-logs";
+import type { LoggerProvider } from "@opentelemetry/sdk-logs";
+import type { MeterProvider } from "@opentelemetry/sdk-metrics";
+import type {
+	ITelemetryAdapter,
+	TelemetryMetadata,
+	TelemetryPrimitive,
+	TelemetryProperties,
+} from "./ITelemetryAdapter";
+
+type FlatTelemetryAttributes = Record<string, string | number | boolean>;
+
+export interface OpenTelemetryAdapterOptions {
+	readonly metadata: TelemetryMetadata;
+	readonly meterProvider?: MeterProvider | null;
+	readonly loggerProvider?: LoggerProvider | null;
+	readonly name?: string;
+	readonly enabled?: boolean | (() => boolean);
+	readonly distinctId?: string;
+	readonly commonProperties?: TelemetryProperties;
+}
+
+export class OpenTelemetryAdapter implements ITelemetryAdapter {
+	readonly name: string;
+
+	private readonly metadata: TelemetryMetadata;
+	private readonly meter: Meter | null;
+	private readonly logger: OpenTelemetryLogger | null;
+	private readonly enabled: boolean | (() => boolean);
+	private distinctId?: string;
+	private commonProperties: TelemetryProperties;
+	private counters = new Map<string, ReturnType<Meter["createCounter"]>>();
+	private histograms = new Map<string, ReturnType<Meter["createHistogram"]>>();
+	private gauges = new Map<
+		string,
+		ReturnType<Meter["createObservableGauge"]>
+	>();
+	private gaugeValues = new Map<
+		string,
+		Map<string, { value: number; attributes?: TelemetryProperties }>
+	>();
+	private readonly meterProvider?: MeterProvider | null;
+	private readonly loggerProvider?: LoggerProvider | null;
+
+	constructor(options: OpenTelemetryAdapterOptions) {
+		this.name = options.name ?? "OpenTelemetryAdapter";
+		this.metadata = { ...options.metadata };
+		this.meterProvider = options.meterProvider;
+		this.loggerProvider = options.loggerProvider;
+		this.meter = options.meterProvider?.getMeter("cline") ?? null;
+		this.logger = options.loggerProvider?.getLogger("cline") ?? null;
+		this.enabled = options.enabled ?? true;
+		this.distinctId = options.distinctId;
+		this.commonProperties = options.commonProperties
+			? { ...options.commonProperties }
+			: {};
+	}
+
+	emit(event: string, properties?: TelemetryProperties): void {
+		if (!this.isEnabled()) {
+			return;
+		}
+		this.emitLog(event, properties, false);
+	}
+
+	emitRequired(event: string, properties?: TelemetryProperties): void {
+		this.emitLog(event, properties, true);
+	}
+
+	recordCounter(
+		name: string,
+		value: number,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required = false,
+	): void {
+		if (!this.meter || (!required && !this.isEnabled())) {
+			return;
+		}
+
+		let counter = this.counters.get(name);
+		if (!counter) {
+			counter = this.meter.createCounter(
+				name,
+				description ? { description } : undefined,
+			);
+			this.counters.set(name, counter);
+		}
+
+		counter.add(
+			value,
+			this.flattenProperties(this.buildAttributes(attributes)),
+		);
+	}
+
+	recordHistogram(
+		name: string,
+		value: number,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required = false,
+	): void {
+		if (!this.meter || (!required && !this.isEnabled())) {
+			return;
+		}
+
+		let histogram = this.histograms.get(name);
+		if (!histogram) {
+			histogram = this.meter.createHistogram(
+				name,
+				description ? { description } : undefined,
+			);
+			this.histograms.set(name, histogram);
+		}
+
+		histogram.record(
+			value,
+			this.flattenProperties(this.buildAttributes(attributes)),
+		);
+	}
+
+	recordGauge(
+		name: string,
+		value: number | null,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required = false,
+	): void {
+		if (!this.meter || (!required && !this.isEnabled())) {
+			return;
+		}
+
+		const mergedAttributes = this.buildAttributes(attributes);
+		const attrKey = JSON.stringify(mergedAttributes);
+		const existingSeries = this.gaugeValues.get(name);
+
+		if (value === null) {
+			if (existingSeries) {
+				existingSeries.delete(attrKey);
+				if (existingSeries.size === 0) {
+					this.gaugeValues.delete(name);
+					this.gauges.delete(name);
+				}
+			}
+			return;
+		}
+
+		let series = existingSeries;
+		if (!series) {
+			series = new Map();
+			this.gaugeValues.set(name, series);
+		}
+
+		if (!this.gauges.has(name)) {
+			const gauge = this.meter.createObservableGauge(
+				name,
+				description ? { description } : undefined,
+			);
+			gauge.addCallback((observableResult) => {
+				for (const data of this.snapshotGaugeSeries(name)) {
+					observableResult.observe(
+						data.value,
+						this.flattenProperties(data.attributes),
+					);
+				}
+			});
+			this.gauges.set(name, gauge);
+		}
+
+		series.set(attrKey, { value, attributes: mergedAttributes });
+	}
+
+	isEnabled(): boolean {
+		return typeof this.enabled === "function" ? this.enabled() : this.enabled;
+	}
+
+	setDistinctId(distinctId?: string): void {
+		this.distinctId = distinctId;
+	}
+
+	setCommonProperties(properties: TelemetryProperties): void {
+		this.commonProperties = { ...properties };
+	}
+
+	updateCommonProperties(properties: TelemetryProperties): void {
+		this.commonProperties = {
+			...this.commonProperties,
+			...properties,
+		};
+	}
+
+	async flush(): Promise<void> {
+		await Promise.all([
+			this.meterProvider?.forceFlush?.(),
+			this.loggerProvider?.forceFlush?.(),
+		]);
+	}
+
+	async dispose(): Promise<void> {
+		await Promise.all([
+			this.meterProvider?.shutdown?.(),
+			this.loggerProvider?.shutdown?.(),
+		]);
+	}
+
+	private emitLog(
+		event: string,
+		properties: TelemetryProperties | undefined,
+		required: boolean,
+	): void {
+		if (!this.logger) {
+			return;
+		}
+
+		const attributes = this.flattenProperties(
+			this.buildAttributes(properties, required),
+		);
+		this.logger.emit({
+			severityText: "INFO",
+			body: event,
+			attributes,
+		});
+	}
+
+	private buildAttributes(
+		properties?: TelemetryProperties,
+		required = false,
+	): TelemetryProperties {
+		return {
+			...this.commonProperties,
+			...properties,
+			...this.metadata,
+			...(this.distinctId ? { distinct_id: this.distinctId } : {}),
+			...(required ? { _required: true } : {}),
+		};
+	}
+
+	private snapshotGaugeSeries(
+		name: string,
+	): Array<{ value: number; attributes?: TelemetryProperties }> {
+		const series = this.gaugeValues.get(name);
+		if (!series) {
+			return [];
+		}
+		return Array.from(series.values(), (entry) => ({
+			value: entry.value,
+			attributes: entry.attributes ? { ...entry.attributes } : undefined,
+		}));
+	}
+
+	private flattenProperties(
+		properties?: TelemetryProperties,
+		prefix = "",
+		seen: WeakSet<object> = new WeakSet(),
+		depth = 0,
+	): FlatTelemetryAttributes {
+		if (!properties) {
+			return {};
+		}
+
+		const flattened: FlatTelemetryAttributes = {};
+		const maxArraySize = 100;
+		const maxDepth = 10;
+
+		for (const [key, value] of Object.entries(properties)) {
+			if (key === "__proto__" || key === "constructor" || key === "prototype") {
+				continue;
+			}
+
+			const fullKey = prefix ? `${prefix}.${key}` : key;
+
+			if (value === null || value === undefined) {
+				flattened[fullKey] = String(value);
+				continue;
+			}
+
+			if (Array.isArray(value)) {
+				const limited =
+					value.length > maxArraySize ? value.slice(0, maxArraySize) : value;
+				try {
+					flattened[fullKey] = JSON.stringify(limited);
+				} catch {
+					flattened[fullKey] = "[UnserializableArray]";
+				}
+				if (value.length > maxArraySize) {
+					flattened[`${fullKey}_truncated`] = true;
+					flattened[`${fullKey}_original_length`] = value.length;
+				}
+				continue;
+			}
+
+			if (typeof value === "object") {
+				if (value instanceof Date) {
+					flattened[fullKey] = value.toISOString();
+					continue;
+				}
+				if (value instanceof Error) {
+					flattened[fullKey] = value.message;
+					continue;
+				}
+				if (seen.has(value)) {
+					flattened[fullKey] = "[Circular]";
+					continue;
+				}
+				if (depth >= maxDepth) {
+					flattened[fullKey] = "[MaxDepthExceeded]";
+					continue;
+				}
+
+				seen.add(value);
+				Object.assign(
+					flattened,
+					this.flattenProperties(
+						value as TelemetryProperties,
+						fullKey,
+						seen,
+						depth + 1,
+					),
+				);
+				continue;
+			}
+
+			if (isTelemetryPrimitive(value)) {
+				flattened[fullKey] = value;
+				continue;
+			}
+
+			try {
+				flattened[fullKey] = JSON.stringify(value);
+			} catch {
+				flattened[fullKey] = String(value);
+			}
+		}
+
+		return flattened;
+	}
+}
+
+function isTelemetryPrimitive(
+	value: unknown,
+): value is Exclude<TelemetryPrimitive, null | undefined> {
+	return (
+		typeof value === "string" ||
+		typeof value === "number" ||
+		typeof value === "boolean"
+	);
+}