@clinebot/core 0.0.37 → 0.0.38

package/src/services/telemetry/OpenTelemetryProvider.ts

@@ -1,415 +0,0 @@
-import type {
-	BasicLogger,
-	ITelemetryService,
-	OpenTelemetryClientConfig,
-	TelemetryMetadata,
-} from "@clinebot/shared";
-import { metrics, type Tracer, trace } 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 { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
-import { resourceFromAttributes } from "@opentelemetry/resources";
-import {
-	BatchLogRecordProcessor,
-	ConsoleLogRecordExporter,
-	LoggerProvider,
-	type LogRecordExporter,
-} from "@opentelemetry/sdk-logs";
-import {
-	ConsoleMetricExporter,
-	MeterProvider,
-	type MetricReader,
-	PeriodicExportingMetricReader,
-} from "@opentelemetry/sdk-metrics";
-import {
-	BatchSpanProcessor,
-	ConsoleSpanExporter,
-	SimpleSpanProcessor,
-	type SpanProcessor,
-} from "@opentelemetry/sdk-trace-base";
-import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
-import {
-	ATTR_SERVICE_NAME,
-	ATTR_SERVICE_VERSION,
-} from "@opentelemetry/semantic-conventions";
-import { resolveCoreDistinctId } from "./distinct-id";
-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" | "tracesExporter"
-	> {
-	serviceName?: string;
-	serviceVersion?: string;
-	enabled?: boolean;
-	logsExporter?: string | OpenTelemetryExporterKind[];
-	metricsExporter?: string | OpenTelemetryExporterKind[];
-	tracesExporter?: 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;
-	readonly tracerProvider: NodeTracerProvider | null;
-	private readonly options: OpenTelemetryProviderOptions;
-
-	constructor(options: OpenTelemetryProviderOptions = {}) {
-		this.options = options;
-		const resource = resourceFromAttributes({
-			[ATTR_SERVICE_NAME]: options.serviceName ?? "cline",
-			...(options.serviceVersion
-				? { [ATTR_SERVICE_VERSION]: options.serviceVersion }
-				: {}),
-		});
-
-		this.meterProvider = this.createMeterProvider(resource);
-		this.loggerProvider = this.createLoggerProvider(resource);
-		this.tracerProvider = this.createTracerProvider(resource);
-
-		if (this.meterProvider) {
-			metrics.setGlobalMeterProvider(this.meterProvider);
-		}
-		if (this.loggerProvider) {
-			logs.setGlobalLoggerProvider(this.loggerProvider);
-		}
-		if (this.tracerProvider) {
-			this.tracerProvider.register();
-		}
-	}
-
-	/**
-	 * Returns a tracer for manual spans. Requires {@link OpenTelemetryProviderOptions.tracesExporter}
-	 * so that a {@link NodeTracerProvider} is registered.
-	 */
-	getTracer(name = "cline", version?: string): Tracer {
-		return trace.getTracer(name, version ?? this.options.serviceVersion);
-	}
-
-	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({
-			...options,
-			adapters: [adapter],
-			distinctId: resolveCoreDistinctId(options.distinctId),
-		});
-	}
-
-	async forceFlush(): Promise<void> {
-		await Promise.all([
-			this.meterProvider?.forceFlush?.(),
-			this.loggerProvider?.forceFlush?.(),
-			this.tracerProvider?.forceFlush?.(),
-		]);
-	}
-
-	async dispose(): Promise<void> {
-		await Promise.all([
-			this.meterProvider?.shutdown?.(),
-			this.loggerProvider?.shutdown?.(),
-			this.tracerProvider?.shutdown?.(),
-		]);
-	}
-
-	private createMeterProvider(
-		resource: ReturnType<typeof resourceFromAttributes>,
-	): 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 createTracerProvider(
-		resource: ReturnType<typeof resourceFromAttributes>,
-	): NodeTracerProvider | null {
-		const exporters = normalizeExporters(this.options.tracesExporter);
-		if (exporters.length === 0) {
-			return null;
-		}
-
-		const traceEndpoint =
-			this.options.otlpTracesEndpoint ?? this.options.otlpEndpoint;
-		const traceHeaders =
-			this.options.otlpTracesHeaders ?? this.options.otlpHeaders;
-
-		const processors: SpanProcessor[] = [];
-		for (const exporter of exporters) {
-			const processor = createSpanProcessor(exporter, {
-				endpoint: traceEndpoint,
-				headers: traceHeaders,
-				insecure: this.options.otlpInsecure ?? false,
-				protocol: "http/json",
-			});
-			if (processor) {
-				processors.push(processor);
-			}
-		}
-		if (processors.length === 0) {
-			return null;
-		}
-
-		return new NodeTracerProvider({ resource, spanProcessors: processors });
-	}
-
-	private createLoggerProvider(
-		resource: ReturnType<typeof resourceFromAttributes>,
-	): LoggerProvider | null {
-		const exporters = normalizeExporters(this.options.logsExporter);
-		if (exporters.length === 0) {
-			return null;
-		}
-
-		const processors = exporters
-			.map((exporter) => {
-				const logExporter = createLogExporter(exporter, {
-					endpoint: this.options.otlpEndpoint,
-					headers: this.options.otlpHeaders,
-					insecure: this.options.otlpInsecure ?? false,
-					protocol: "http/json",
-				});
-				if (!logExporter) {
-					return null;
-				}
-				return new BatchLogRecordProcessor(logExporter, {
-					maxQueueSize: this.options.logMaxQueueSize ?? 2048,
-					maxExportBatchSize: this.options.logBatchSize ?? 512,
-					scheduledDelayMillis:
-						this.options.logBatchTimeoutMs ??
-						this.options.logBatchTimeout ??
-						5000,
-				});
-			})
-			.filter((p): p is BatchLogRecordProcessor => p !== null);
-		if (processors.length === 0) {
-			return null;
-		}
-		return new LoggerProvider({ resource, processors });
-	}
-}
-
-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,
-		tracesExporter: Array.isArray(options.tracesExporter)
-			? options.tracesExporter.join(",")
-			: options.tracesExporter,
-		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({
-				...options,
-				distinctId: resolveCoreDistinctId(options.distinctId),
-			}),
-		};
-	}
-
-	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 createSpanProcessor(
-	exporter: OpenTelemetryExporterKind,
-	options: {
-		endpoint?: string;
-		headers?: Record<string, string>;
-		insecure: boolean;
-		protocol: OpenTelemetryProtocol;
-	},
-): SpanProcessor | null {
-	if (exporter === "console") {
-		return new SimpleSpanProcessor(new ConsoleSpanExporter());
-	}
-	if (!options.endpoint) {
-		return null;
-	}
-
-	const endpoint = ensurePathSuffix(options.endpoint, "/v1/traces");
-	return new BatchSpanProcessor(
-		new OTLPTraceExporter({
-			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/services/telemetry/TelemetryLoggerSink.ts

@@ -1,121 +0,0 @@
-import type { BasicLogger } from "@clinebot/shared";
-import type {
-	ITelemetryAdapter,
-	TelemetryProperties,
-} from "./ITelemetryAdapter";
-
-/**
- * {@link ITelemetryAdapter} implementation that forwards telemetry to a {@link BasicLogger}.
- *
- * This is intentionally named *Sink* (not "adapter") to distinguish it from host logging bridges
- * such as the CLI Pino bundle: it consumes telemetry events and writes them to the injected logger.
- */
-export interface TelemetryLoggerSinkOptions {
-	logger?: BasicLogger;
-	name?: string;
-	enabled?: boolean | (() => boolean);
-}
-
-export class TelemetryLoggerSink implements ITelemetryAdapter {
-	readonly name: string;
-
-	private readonly logger?: BasicLogger;
-	private readonly enabled: boolean | (() => boolean);
-
-	constructor(options: TelemetryLoggerSinkOptions = {}) {
-		this.name = options.name ?? "TelemetryLoggerSink";
-		this.logger = options.logger;
-		this.enabled = options.enabled ?? true;
-	}
-
-	emit(event: string, properties?: TelemetryProperties): void {
-		if (!this.isEnabled()) {
-			return;
-		}
-		this.logger?.log("telemetry.event", {
-			telemetrySink: this.name,
-			event,
-			properties,
-		});
-	}
-
-	emitRequired(event: string, properties?: TelemetryProperties): void {
-		this.logger?.log("telemetry.required_event", {
-			telemetrySink: this.name,
-			severity: "warn",
-			event,
-			properties,
-		});
-	}
-
-	recordCounter(
-		name: string,
-		value: number,
-		attributes?: TelemetryProperties,
-		description?: string,
-		required?: boolean,
-	): void {
-		if (!required && !this.isEnabled()) {
-			return;
-		}
-		this.logger?.debug("telemetry.metric", {
-			telemetrySink: 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", {
-			telemetrySink: 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", {
-			telemetrySink: 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/services/telemetry/TelemetryService.ts

@@ -1,139 +0,0 @@
-import type {
-	BasicLogger,
-	ITelemetryService,
-	TelemetryMetadata,
-	TelemetryProperties,
-} from "@clinebot/shared";
-import type { ITelemetryAdapter } from "./ITelemetryAdapter";
-import { TelemetryLoggerSink } from "./TelemetryLoggerSink";
-
-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 TelemetryLoggerSink({ 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 } : {}),
-		};
-	}
-}