@clinebot/core 0.0.5 → 0.0.6

package/src/telemetry/OpenTelemetryProvider.test.ts

@@ -0,0 +1,113 @@
+import type { BasicLogger } from "@clinebot/shared";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+	createConfiguredTelemetryService,
+	createOpenTelemetryTelemetryService,
+	OpenTelemetryProvider,
+} from "./OpenTelemetryProvider";
+import { TelemetryService } from "./TelemetryService";
+
+describe("createOpenTelemetryTelemetryService", () => {
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("logs a provider creation event during bootstrap", async () => {
+		const captureRequired = vi
+			.spyOn(TelemetryService.prototype, "captureRequired")
+			.mockImplementation(() => {});
+
+		const { provider } = createOpenTelemetryTelemetryService({
+			metadata: {
+				extension_version: "1.2.3",
+				cline_type: "cli",
+				platform: "terminal",
+				platform_version: process.version,
+				os_type: process.platform,
+				os_version: "unknown",
+			},
+			enabled: true,
+			logsExporter: "console",
+			metricsExporter: "otlp",
+			otlpProtocol: "http/json",
+			otlpEndpoint: "http://localhost:4318",
+			serviceName: "cline-cli",
+			serviceVersion: "1.2.3",
+		});
+
+		expect(captureRequired).toHaveBeenCalledWith(
+			"telemetry.provider_created",
+			expect.objectContaining({
+				provider: "opentelemetry",
+				enabled: true,
+				logsExporter: "console",
+				metricsExporter: "otlp",
+				otlpProtocol: "http/json",
+				hasOtlpEndpoint: true,
+				serviceName: "cline-cli",
+				serviceVersion: "1.2.3",
+			}),
+		);
+
+		await provider.dispose();
+	});
+
+	it("does not create an OTEL provider when disabled", () => {
+		const providerSpy = vi.spyOn(
+			OpenTelemetryProvider.prototype,
+			"createTelemetryService",
+		);
+
+		const { telemetry, provider } = createConfiguredTelemetryService({
+			metadata: {
+				extension_version: "1.2.3",
+				cline_type: "cli",
+				platform: "terminal",
+				platform_version: process.version,
+				os_type: process.platform,
+				os_version: "unknown",
+			},
+			enabled: false,
+		});
+
+		expect(provider).toBeUndefined();
+		expect(providerSpy).not.toHaveBeenCalled();
+		expect(telemetry).toBeInstanceOf(TelemetryService);
+	});
+
+	it("attaches the logger adapter when creating configured telemetry", () => {
+		const logger: BasicLogger = {
+			debug: vi.fn(),
+			info: vi.fn(),
+			warn: vi.fn(),
+			error: vi.fn(),
+		};
+		const { telemetry, provider } = createConfiguredTelemetryService({
+			metadata: {
+				extension_version: "1.2.3",
+				cline_type: "cli",
+				platform: "terminal",
+				platform_version: process.version,
+				os_type: process.platform,
+				os_version: "unknown",
+			},
+			enabled: true,
+			logsExporter: "console",
+			logger,
+		});
+
+		telemetry.capture({
+			event: "session.started",
+			properties: { sessionId: "session-1" },
+		});
+
+		expect(logger.info).toHaveBeenCalledWith(
+			"telemetry.event",
+			expect.objectContaining({
+				event: "session.started",
+			}),
+		);
+
+		return provider?.dispose();
+	});
+});

package/src/telemetry/OpenTelemetryProvider.ts

@@ -0,0 +1,322 @@
+import type {
+	BasicLogger,
+	ITelemetryService,
+	OpenTelemetryClientConfig,
+	TelemetryMetadata,
+} from "@clinebot/shared";
+import { metrics } from "@opentelemetry/api";
+import { logs } from "@opentelemetry/api-logs";
+import { OTLPLogExporter as OTLPLogExporterHttp } from "@opentelemetry/exporter-logs-otlp-http";
+import { OTLPMetricExporter as OTLPMetricExporterHttp } from "@opentelemetry/exporter-metrics-otlp-http";
+import { Resource } from "@opentelemetry/resources";
+import {
+	BatchLogRecordProcessor,
+	ConsoleLogRecordExporter,
+	LoggerProvider,
+	type LogRecordExporter,
+} from "@opentelemetry/sdk-logs";
+import {
+	ConsoleMetricExporter,
+	MeterProvider,
+	type MetricReader,
+	PeriodicExportingMetricReader,
+} from "@opentelemetry/sdk-metrics";
+import {
+	ATTR_SERVICE_NAME,
+	ATTR_SERVICE_VERSION,
+} from "@opentelemetry/semantic-conventions";
+import {
+	OpenTelemetryAdapter,
+	type OpenTelemetryAdapterOptions,
+} from "./OpenTelemetryAdapter";
+import { TelemetryService } from "./TelemetryService";
+
+type OpenTelemetryExporterKind = "console" | "otlp";
+type OpenTelemetryProtocol = "http/json";
+
+export interface OpenTelemetryProviderOptions
+	extends Omit<
+		OpenTelemetryClientConfig,
+		"enabled" | "logsExporter" | "metricsExporter"
+	> {
+	serviceName?: string;
+	serviceVersion?: string;
+	enabled?: boolean;
+	logsExporter?: string | OpenTelemetryExporterKind[];
+	metricsExporter?: string | OpenTelemetryExporterKind[];
+	metricExportIntervalMs?: number;
+	logMaxQueueSize?: number;
+	logBatchSize?: number;
+	logBatchTimeoutMs?: number;
+}
+
+export interface CreateOpenTelemetryTelemetryServiceOptions
+	extends OpenTelemetryProviderOptions,
+		Pick<
+			OpenTelemetryAdapterOptions,
+			"name" | "distinctId" | "commonProperties"
+		> {
+	metadata: TelemetryMetadata;
+	logger?: BasicLogger;
+}
+
+export class OpenTelemetryProvider {
+	readonly meterProvider: MeterProvider | null;
+	readonly loggerProvider: LoggerProvider | null;
+	private readonly options: OpenTelemetryProviderOptions;
+
+	constructor(options: OpenTelemetryProviderOptions = {}) {
+		this.options = options;
+		const resource = new Resource({
+			[ATTR_SERVICE_NAME]: options.serviceName ?? "cline",
+			...(options.serviceVersion
+				? { [ATTR_SERVICE_VERSION]: options.serviceVersion }
+				: {}),
+		});
+
+		this.meterProvider = this.createMeterProvider(resource);
+		this.loggerProvider = this.createLoggerProvider(resource);
+
+		if (this.meterProvider) {
+			metrics.setGlobalMeterProvider(this.meterProvider);
+		}
+		if (this.loggerProvider) {
+			logs.setGlobalLoggerProvider(this.loggerProvider);
+		}
+	}
+
+	createAdapter(
+		options: Omit<
+			OpenTelemetryAdapterOptions,
+			"meterProvider" | "loggerProvider"
+		>,
+	): OpenTelemetryAdapter {
+		return new OpenTelemetryAdapter({
+			...options,
+			meterProvider: this.meterProvider,
+			loggerProvider: this.loggerProvider,
+		});
+	}
+
+	createTelemetryService(
+		options: Omit<
+			CreateOpenTelemetryTelemetryServiceOptions,
+			keyof OpenTelemetryProviderOptions
+		>,
+	): ITelemetryService {
+		const adapter = this.createAdapter({
+			name: options.name,
+			enabled: this.options.enabled,
+			metadata: options.metadata,
+		});
+		return new TelemetryService({
+			adapters: [adapter],
+			distinctId: options.distinctId,
+			commonProperties: options.commonProperties,
+			logger: options.logger,
+		});
+	}
+
+	async forceFlush(): 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 createMeterProvider(resource: Resource): MeterProvider | null {
+		const exporters = normalizeExporters(this.options.metricsExporter);
+		if (exporters.length === 0) {
+			return null;
+		}
+
+		const interval = Math.max(
+			1_000,
+			this.options.metricExportIntervalMs ??
+				this.options.metricExportInterval ??
+				60_000,
+		);
+		const timeout = Math.min(30_000, Math.floor(interval * 0.8));
+		const readers = exporters
+			.map((exporter) =>
+				createMetricReader(exporter, {
+					endpoint: this.options.otlpEndpoint,
+					headers: this.options.otlpHeaders,
+					insecure: this.options.otlpInsecure ?? false,
+					protocol: "http/json",
+					interval,
+					timeout,
+				}),
+			)
+			.filter((reader): reader is MetricReader => reader !== null);
+
+		if (readers.length === 0) {
+			return null;
+		}
+
+		return new MeterProvider({
+			resource,
+			readers,
+		});
+	}
+
+	private createLoggerProvider(resource: Resource): LoggerProvider | null {
+		const exporters = normalizeExporters(this.options.logsExporter);
+		if (exporters.length === 0) {
+			return null;
+		}
+
+		const provider = new LoggerProvider({ resource });
+		for (const exporter of exporters) {
+			const logExporter = createLogExporter(exporter, {
+				endpoint: this.options.otlpEndpoint,
+				headers: this.options.otlpHeaders,
+				insecure: this.options.otlpInsecure ?? false,
+				protocol: "http/json",
+			});
+			if (!logExporter) {
+				continue;
+			}
+			provider.addLogRecordProcessor(
+				new BatchLogRecordProcessor(logExporter, {
+					maxQueueSize: this.options.logMaxQueueSize ?? 2048,
+					maxExportBatchSize: this.options.logBatchSize ?? 512,
+					scheduledDelayMillis:
+						this.options.logBatchTimeoutMs ??
+						this.options.logBatchTimeout ??
+						5000,
+				}),
+			);
+		}
+		return provider;
+	}
+}
+
+export function createOpenTelemetryTelemetryService(
+	options: CreateOpenTelemetryTelemetryServiceOptions,
+): { provider: OpenTelemetryProvider; telemetry: ITelemetryService } {
+	const provider = new OpenTelemetryProvider(options);
+	const telemetry = provider.createTelemetryService(options);
+	telemetry.captureRequired("telemetry.provider_created", {
+		provider: "opentelemetry",
+		enabled: options.enabled ?? true,
+		logsExporter: Array.isArray(options.logsExporter)
+			? options.logsExporter.join(",")
+			: options.logsExporter,
+		metricsExporter: Array.isArray(options.metricsExporter)
+			? options.metricsExporter.join(",")
+			: options.metricsExporter,
+		otlpProtocol: options.otlpProtocol,
+		hasOtlpEndpoint: Boolean(options.otlpEndpoint),
+		serviceName: options.serviceName,
+		serviceVersion: options.serviceVersion,
+	});
+	return {
+		provider,
+		telemetry,
+	};
+}
+
+export function createConfiguredTelemetryService(
+	options: CreateOpenTelemetryTelemetryServiceOptions,
+): {
+	provider?: OpenTelemetryProvider;
+	telemetry: ITelemetryService;
+} {
+	if (options.enabled !== true) {
+		return {
+			telemetry: new TelemetryService(),
+		};
+	}
+
+	return createOpenTelemetryTelemetryService(options);
+}
+
+function normalizeExporters(
+	exporters: OpenTelemetryProviderOptions["logsExporter"],
+): OpenTelemetryExporterKind[] {
+	if (!exporters) {
+		return [];
+	}
+	const values = Array.isArray(exporters) ? exporters : exporters.split(",");
+	return values
+		.map((value) => value.trim())
+		.filter(
+			(value): value is OpenTelemetryExporterKind =>
+				value === "console" || value === "otlp",
+		);
+}
+
+function createLogExporter(
+	exporter: OpenTelemetryExporterKind,
+	options: {
+		endpoint?: string;
+		headers?: Record<string, string>;
+		insecure: boolean;
+		protocol: OpenTelemetryProtocol;
+	},
+): LogRecordExporter | null {
+	if (exporter === "console") {
+		return new ConsoleLogRecordExporter();
+	}
+	if (!options.endpoint) {
+		return null;
+	}
+
+	const endpoint = ensurePathSuffix(options.endpoint, "/v1/logs");
+	return new OTLPLogExporterHttp({
+		url: endpoint,
+		headers: options.headers,
+	});
+}
+
+function createMetricReader(
+	exporter: OpenTelemetryExporterKind,
+	options: {
+		endpoint?: string;
+		headers?: Record<string, string>;
+		insecure: boolean;
+		protocol: OpenTelemetryProtocol;
+		interval: number;
+		timeout: number;
+	},
+): MetricReader | null {
+	if (exporter === "console") {
+		return new PeriodicExportingMetricReader({
+			exporter: new ConsoleMetricExporter(),
+			exportIntervalMillis: options.interval,
+			exportTimeoutMillis: options.timeout,
+		});
+	}
+	if (!options.endpoint) {
+		return null;
+	}
+
+	const endpoint = ensurePathSuffix(options.endpoint, "/v1/metrics");
+	return new PeriodicExportingMetricReader({
+		exporter: new OTLPMetricExporterHttp({
+			url: endpoint,
+			headers: options.headers,
+		}),
+		exportIntervalMillis: options.interval,
+		exportTimeoutMillis: options.timeout,
+	});
+}
+
+function ensurePathSuffix(endpoint: string, suffix: string): string {
+	const url = new URL(endpoint);
+	const normalized = url.pathname.endsWith("/")
+		? url.pathname.slice(0, -1)
+		: url.pathname;
+	url.pathname = normalized.endsWith(suffix)
+		? normalized
+		: `${normalized}${suffix}`;
+	return url.toString();
+}

package/src/telemetry/TelemetryService.test.ts

@@ -0,0 +1,134 @@
+import type { BasicLogger } from "@clinebot/shared";
+import { describe, expect, it, vi } from "vitest";
+import type { ITelemetryAdapter } from "./ITelemetryAdapter";
+import { TelemetryService } from "./TelemetryService";
+
+describe("TelemetryService", () => {
+	it("merges metadata and forwards calls to adapters", async () => {
+		const { adapter, emit, recordCounter } = createAdapter();
+		const service = new TelemetryService({
+			adapters: [adapter],
+			metadata: {
+				extension_version: "1.2.3",
+				cline_type: "cli",
+			},
+			distinctId: "distinct-1",
+			commonProperties: {
+				organization_id: "org-1",
+			},
+		});
+
+		service.capture({
+			event: "session.started",
+			properties: { sessionId: "session-1" },
+		});
+		service.recordCounter("cline.session.starts.total", 1, {
+			sessionId: "session-1",
+		});
+		await service.flush();
+		await service.dispose();
+
+		expect(emit).toHaveBeenCalledWith(
+			"session.started",
+			expect.objectContaining({
+				sessionId: "session-1",
+				organization_id: "org-1",
+				extension_version: "1.2.3",
+				cline_type: "cli",
+				distinct_id: "distinct-1",
+			}),
+		);
+		expect(recordCounter).toHaveBeenCalledWith(
+			"cline.session.starts.total",
+			1,
+			expect.objectContaining({
+				sessionId: "session-1",
+				distinct_id: "distinct-1",
+			}),
+			undefined,
+			false,
+		);
+	});
+
+	it("mirrors telemetry events into the logger when provided", () => {
+		const logger: BasicLogger = {
+			debug: vi.fn(),
+			info: vi.fn(),
+			warn: vi.fn(),
+			error: vi.fn(),
+		};
+		const service = new TelemetryService({
+			logger,
+			metadata: {
+				extension_version: "1.2.3",
+				cline_type: "cli",
+			},
+			distinctId: "distinct-1",
+		});
+
+		service.capture({
+			event: "session.started",
+			properties: { sessionId: "session-1" },
+		});
+		service.captureRequired("user.opt_out", { reason: "manual" });
+		service.recordCounter("cline.session.starts.total", 1, {
+			sessionId: "session-1",
+		});
+
+		expect(logger.info).toHaveBeenCalledWith(
+			"telemetry.event",
+			expect.objectContaining({
+				adapter: "LoggerTelemetryAdapter",
+				event: "session.started",
+				properties: expect.objectContaining({
+					sessionId: "session-1",
+					extension_version: "1.2.3",
+					distinct_id: "distinct-1",
+				}),
+			}),
+		);
+		expect(logger.warn).toHaveBeenCalledWith(
+			"telemetry.required_event",
+			expect.objectContaining({
+				adapter: "LoggerTelemetryAdapter",
+				event: "user.opt_out",
+				properties: expect.objectContaining({
+					reason: "manual",
+					extension_version: "1.2.3",
+				}),
+			}),
+		);
+		expect(logger.debug).toHaveBeenCalledWith(
+			"telemetry.metric",
+			expect.objectContaining({
+				adapter: "LoggerTelemetryAdapter",
+				instrument: "counter",
+				name: "cline.session.starts.total",
+			}),
+		);
+	});
+});
+
+function createAdapter(): {
+	adapter: ITelemetryAdapter;
+	emit: ReturnType<typeof vi.fn>;
+	recordCounter: ReturnType<typeof vi.fn>;
+} {
+	const emit = vi.fn();
+	const recordCounter = vi.fn();
+	return {
+		adapter: {
+			name: "test",
+			emit,
+			emitRequired: vi.fn(),
+			recordCounter,
+			recordHistogram: vi.fn(),
+			recordGauge: vi.fn(),
+			isEnabled: vi.fn(() => true),
+			flush: vi.fn().mockResolvedValue(undefined),
+			dispose: vi.fn().mockResolvedValue(undefined),
+		},
+		emit,
+		recordCounter,
+	};
+}

package/src/telemetry/TelemetryService.ts

@@ -0,0 +1,141 @@
+import type {
+	BasicLogger,
+	ITelemetryService,
+	TelemetryMetadata,
+	TelemetryProperties,
+} from "@clinebot/shared";
+import type { ITelemetryAdapter } from "./ITelemetryAdapter";
+import { LoggerTelemetryAdapter } from "./LoggerTelemetryAdapter";
+
+export interface TelemetryServiceOptions {
+	adapters?: ITelemetryAdapter[];
+	metadata?: Partial<TelemetryMetadata>;
+	distinctId?: string;
+	commonProperties?: TelemetryProperties;
+	logger?: BasicLogger;
+}
+
+export class TelemetryService implements ITelemetryService {
+	private adapters: ITelemetryAdapter[];
+	private metadata: Partial<TelemetryMetadata>;
+	private distinctId?: string;
+	private commonProperties: TelemetryProperties;
+
+	constructor(options: TelemetryServiceOptions = {}) {
+		this.adapters = [...(options.adapters ?? [])];
+		if (options.logger) {
+			this.adapters.push(
+				new LoggerTelemetryAdapter({ logger: options.logger }),
+			);
+		}
+		this.metadata = { ...(options.metadata ?? {}) };
+		this.distinctId = options.distinctId;
+		this.commonProperties = { ...(options.commonProperties ?? {}) };
+	}
+
+	addAdapter(adapter: ITelemetryAdapter): void {
+		this.adapters.push(adapter);
+	}
+
+	setDistinctId(distinctId?: string): void {
+		this.distinctId = distinctId;
+	}
+
+	setMetadata(metadata: Partial<TelemetryMetadata>): void {
+		this.metadata = { ...metadata };
+	}
+
+	updateMetadata(metadata: Partial<TelemetryMetadata>): void {
+		this.metadata = {
+			...this.metadata,
+			...metadata,
+		};
+	}
+
+	setCommonProperties(properties: TelemetryProperties): void {
+		this.commonProperties = { ...properties };
+	}
+
+	updateCommonProperties(properties: TelemetryProperties): void {
+		this.commonProperties = {
+			...this.commonProperties,
+			...properties,
+		};
+	}
+
+	isEnabled(): boolean {
+		return this.adapters.some((adapter) => adapter.isEnabled());
+	}
+
+	capture(input: { event: string; properties?: TelemetryProperties }): void {
+		const properties = this.buildAttributes(input.properties);
+		for (const adapter of this.adapters) {
+			adapter.emit(input.event, properties);
+		}
+	}
+
+	captureRequired(event: string, properties?: TelemetryProperties): void {
+		const merged = this.buildAttributes(properties);
+		for (const adapter of this.adapters) {
+			adapter.emitRequired(event, merged);
+		}
+	}
+
+	recordCounter(
+		name: string,
+		value: number,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required = false,
+	): void {
+		const merged = this.buildAttributes(attributes);
+		for (const adapter of this.adapters) {
+			adapter.recordCounter(name, value, merged, description, required);
+		}
+	}
+
+	recordHistogram(
+		name: string,
+		value: number,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required = false,
+	): void {
+		const merged = this.buildAttributes(attributes);
+		for (const adapter of this.adapters) {
+			adapter.recordHistogram(name, value, merged, description, required);
+		}
+	}
+
+	recordGauge(
+		name: string,
+		value: number | null,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required = false,
+	): void {
+		const merged = this.buildAttributes(attributes);
+		for (const adapter of this.adapters) {
+			adapter.recordGauge(name, value, merged, description, required);
+		}
+	}
+
+	async flush(): Promise<void> {
+		await Promise.all(this.adapters.map((adapter) => adapter.flush()));
+	}
+
+	async dispose(): Promise<void> {
+		await Promise.all(this.adapters.map((adapter) => adapter.dispose()));
+	}
+
+	private buildAttributes(
+		properties?: TelemetryProperties,
+	): TelemetryProperties {
+		return {
+			...this.commonProperties,
+			...properties,
+			...this.metadata,
+			...(this.distinctId ? { distinct_id: this.distinctId } : {}),
+		};
+	}
+}