@clinebot/core 0.0.18 → 0.0.21

package/src/telemetry/OpenTelemetryProvider.ts

@@ -1,322 +0,0 @@
-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

@@ -1,134 +0,0 @@
-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

@@ -1,141 +0,0 @@
-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 } : {}),
-		};
-	}
-}