@vfarcic/dot-ai 0.125.0 → 0.126.0

package/dist/core/tracing/k8s-tracing.js

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * Kubernetes Client Tracing Utilities
+ *
+ * Generic tracing wrappers for Kubernetes operations:
+ * 1. Transparent proxy for @kubernetes/client-node API clients
+ * 2. Wrapper for kubectl CLI command execution
+ *
+ * Uses CLIENT span kind with k8s.* semantic conventions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTracedK8sClient = createTracedK8sClient;
+exports.withKubectlTracing = withKubectlTracing;
+const api_1 = require("@opentelemetry/api");
+/**
+ * Create traced Kubernetes API client using JavaScript Proxy
+ *
+ * Transparently wraps ANY Kubernetes API client method with tracing.
+ * No code changes needed in calling code - just wrap the client once.
+ *
+ * @param apiClient Original K8s API client instance
+ * @param apiType API client type (e.g., 'CoreV1Api', 'AppsV1Api')
+ * @returns Proxied client with automatic tracing for all methods
+ *
+ * @example
+ * const coreApi = createTracedK8sClient(
+ *   kc.makeApiClient(k8s.CoreV1Api),
+ *   'CoreV1Api'
+ * );
+ * await coreApi.listNamespace(); // Automatically traced as "k8s.listNamespace"
+ */
+function createTracedK8sClient(apiClient, apiType) {
+    const tracer = api_1.trace.getTracer('dot-ai-mcp');
+    return new Proxy(apiClient, {
+        get(target, prop, receiver) {
+            const original = Reflect.get(target, prop, receiver);
+            // Only wrap functions (API methods), not properties
+            if (typeof original !== 'function') {
+                return original;
+            }
+            // Return wrapped function with tracing
+            return function (...args) {
+                const methodName = String(prop);
+                const spanName = `k8s.${methodName}`;
+                return tracer.startActiveSpan(spanName, {
+                    kind: api_1.SpanKind.CLIENT,
+                    attributes: {
+                        'k8s.client': 'kubernetes-client-node',
+                        'k8s.api': apiType,
+                        'k8s.method': methodName,
+                    },
+                }, async (span) => {
+                    try {
+                        // Execute the original K8s API method
+                        const result = await original.apply(target, args);
+                        // Add response metadata if available
+                        if (result?.response?.statusCode) {
+                            span.setAttribute('http.response.status_code', result.response.statusCode);
+                        }
+                        span.setStatus({ code: api_1.SpanStatusCode.OK });
+                        return result;
+                    }
+                    catch (error) {
+                        // Record K8s API error
+                        span.recordException(error);
+                        span.setStatus({
+                            code: api_1.SpanStatusCode.ERROR,
+                            message: error instanceof Error ? error.message : String(error),
+                        });
+                        // Add K8s-specific error attributes
+                        if (error instanceof Error && 'statusCode' in error) {
+                            span.setAttribute('k8s.error.status_code', error.statusCode);
+                        }
+                        throw error;
+                    }
+                    finally {
+                        span.end();
+                    }
+                });
+            };
+        },
+    });
+}
+/**
+ * Tracing wrapper for kubectl CLI command execution
+ *
+ * Wraps kubectl command execution with OpenTelemetry tracing spans.
+ * Captures command details, operation type, and execution results.
+ *
+ * @param args kubectl command arguments (e.g., ['get', 'pods', '-n', 'default'])
+ * @param config kubectl execution configuration
+ * @param handler Function that executes the actual kubectl command
+ * @returns kubectl command output
+ *
+ * @example
+ * const output = await withKubectlTracing(
+ *   ['get', 'crd', '-o', 'json'],
+ *   { kubeconfig: '/path/to/config' },
+ *   async () => execAsync('kubectl get crd -o json')
+ * );
+ */
+async function withKubectlTracing(args, config, handler) {
+    const tracer = api_1.trace.getTracer('dot-ai-mcp');
+    // Parse operation and resource from args
+    const operation = args[0] || 'unknown'; // 'get', 'apply', 'delete', etc.
+    const resource = args[1] || 'unknown'; // 'pods', 'crd', 'deployments', etc.
+    const spanName = `kubectl ${operation} ${resource}`;
+    return await tracer.startActiveSpan(spanName, {
+        kind: api_1.SpanKind.CLIENT,
+        attributes: {
+            'k8s.client': 'kubectl',
+            'k8s.command': 'kubectl',
+            'k8s.operation': operation,
+            'k8s.resource': resource,
+            'k8s.args': args.join(' '),
+            ...(config?.namespace && { 'k8s.namespace': config.namespace }),
+            ...(config?.context && { 'k8s.context': config.context }),
+            ...(config?.kubeconfig && { 'k8s.kubeconfig': config.kubeconfig }),
+        },
+    }, async (span) => {
+        const startTime = Date.now();
+        try {
+            // Execute the kubectl command
+            const result = await api_1.context.with(api_1.trace.setSpan(api_1.context.active(), span), handler);
+            // Add execution metrics
+            span.setAttribute('k8s.duration_ms', Date.now() - startTime);
+            span.setAttribute('k8s.output_size_bytes', result.length);
+            span.setStatus({ code: api_1.SpanStatusCode.OK });
+            return result;
+        }
+        catch (error) {
+            // Record kubectl error with details
+            span.recordException(error);
+            span.setStatus({
+                code: api_1.SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            // Parse kubectl error for additional context
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            if (errorMessage.includes('not found')) {
+                span.setAttribute('k8s.error.type', 'NotFound');
+            }
+            else if (errorMessage.includes('forbidden')) {
+                span.setAttribute('k8s.error.type', 'Forbidden');
+            }
+            else if (errorMessage.includes('timeout')) {
+                span.setAttribute('k8s.error.type', 'Timeout');
+            }
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+}

package/dist/core/tracing/qdrant-tracing.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Qdrant Vector Database Tracing
+ *
+ * Provides distributed tracing instrumentation for Qdrant vector database operations.
+ * Creates CLIENT spans with database semantic conventions and vector-specific attributes.
+ */
+/**
+ * Vector database operation types
+ */
+export type VectorDBOperation = 'collection.create' | 'collection.get' | 'collection.list' | 'collection.delete' | 'collection.initialize' | 'vector.upsert' | 'vector.search' | 'vector.search_keywords' | 'vector.retrieve' | 'vector.delete' | 'vector.delete_all' | 'vector.list' | 'health_check';
+/**
+ * Qdrant operation metadata for tracing
+ */
+export interface QdrantOperationContext {
+    /** Operation type */
+    operation: VectorDBOperation;
+    /** Collection name */
+    collectionName: string;
+    /** Vector dimensions (for upsert, search operations) */
+    vectorSize?: number;
+    /** Search limit (for search operations) */
+    limit?: number;
+    /** Score threshold (for similarity search) */
+    scoreThreshold?: number;
+    /** Number of keywords (for keyword search) */
+    keywordCount?: number;
+    /** Document ID (for single document operations) */
+    documentId?: string;
+    /** Qdrant server URL */
+    serverUrl?: string;
+}
+/**
+ * Generic Qdrant operation tracing wrapper
+ *
+ * @param operationContext - Qdrant operation metadata
+ * @param handler - Async operation to trace
+ * @returns Result from handler
+ *
+ * @example
+ * ```typescript
+ * // Trace vector search
+ * const results = await withQdrantTracing(
+ *   {
+ *     operation: 'vector.search',
+ *     collectionName: 'capabilities',
+ *     vectorSize: 1536,
+ *     limit: 10,
+ *     scoreThreshold: 0.5,
+ *     serverUrl: 'http://localhost:6333'
+ *   },
+ *   async () => await this.client.search(...)
+ * );
+ *
+ * // Trace document upsert
+ * await withQdrantTracing(
+ *   {
+ *     operation: 'vector.upsert',
+ *     collectionName: 'patterns',
+ *     documentId: 'pattern-123',
+ *     vectorSize: 384,
+ *     serverUrl: 'http://localhost:6333'
+ *   },
+ *   async () => await this.client.upsert(...)
+ * );
+ * ```
+ */
+export declare function withQdrantTracing<T>(operationContext: QdrantOperationContext, handler: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=qdrant-tracing.d.ts.map

package/dist/core/tracing/qdrant-tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qdrant-tracing.d.ts","sourceRoot":"","sources":["../../../src/core/tracing/qdrant-tracing.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;GAEG;AACH,MAAM,MAAM,iBAAiB,GACzB,mBAAmB,GACnB,gBAAgB,GAChB,iBAAiB,GACjB,mBAAmB,GACnB,uBAAuB,GACvB,eAAe,GACf,eAAe,GACf,wBAAwB,GACxB,iBAAiB,GACjB,eAAe,GACf,mBAAmB,GACnB,aAAa,GACb,cAAc,CAAC;AAEnB;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,qBAAqB;IACrB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,sBAAsB;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wBAAwB;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,gBAAgB,EAAE,sBAAsB,EACxC,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,CAAC,CAAC,CAgEZ"}

package/dist/core/tracing/qdrant-tracing.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Qdrant Vector Database Tracing
+ *
+ * Provides distributed tracing instrumentation for Qdrant vector database operations.
+ * Creates CLIENT spans with database semantic conventions and vector-specific attributes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withQdrantTracing = withQdrantTracing;
+const api_1 = require("@opentelemetry/api");
+const tracer = api_1.trace.getTracer('dot-ai-mcp-qdrant');
+/**
+ * Generic Qdrant operation tracing wrapper
+ *
+ * @param operationContext - Qdrant operation metadata
+ * @param handler - Async operation to trace
+ * @returns Result from handler
+ *
+ * @example
+ * ```typescript
+ * // Trace vector search
+ * const results = await withQdrantTracing(
+ *   {
+ *     operation: 'vector.search',
+ *     collectionName: 'capabilities',
+ *     vectorSize: 1536,
+ *     limit: 10,
+ *     scoreThreshold: 0.5,
+ *     serverUrl: 'http://localhost:6333'
+ *   },
+ *   async () => await this.client.search(...)
+ * );
+ *
+ * // Trace document upsert
+ * await withQdrantTracing(
+ *   {
+ *     operation: 'vector.upsert',
+ *     collectionName: 'patterns',
+ *     documentId: 'pattern-123',
+ *     vectorSize: 384,
+ *     serverUrl: 'http://localhost:6333'
+ *   },
+ *   async () => await this.client.upsert(...)
+ * );
+ * ```
+ */
+async function withQdrantTracing(operationContext, handler) {
+    const { operation, collectionName, ...metadata } = operationContext;
+    // Create span name: "qdrant.{operation} {collection}"
+    // Examples: "qdrant.vector.search capabilities", "qdrant.vector.upsert patterns"
+    const spanName = `qdrant.${operation} ${collectionName}`;
+    return tracer.startActiveSpan(spanName, {
+        kind: 2, // CLIENT span
+        attributes: {
+            // Database semantic conventions
+            'db.system': 'qdrant',
+            'db.operation.name': operation,
+            'db.collection.name': collectionName,
+            // Vector-specific attributes
+            ...(metadata.vectorSize && { 'db.vector.dimensions': metadata.vectorSize }),
+            ...(metadata.limit && { 'db.query.limit': metadata.limit }),
+            ...(metadata.scoreThreshold && { 'db.vector.score_threshold': metadata.scoreThreshold }),
+            ...(metadata.keywordCount && { 'db.query.keyword_count': metadata.keywordCount }),
+            ...(metadata.documentId && { 'db.document.id': metadata.documentId }),
+            ...(metadata.serverUrl && { 'server.address': metadata.serverUrl })
+        }
+    }, async (span) => {
+        try {
+            // Execute operation
+            const result = await handler();
+            // Add result metadata for search operations
+            if (operation === 'vector.search' || operation === 'vector.search_keywords') {
+                if (Array.isArray(result)) {
+                    span.setAttribute('db.query.result_count', result.length);
+                    // For search results with scores, track top score
+                    if (result.length > 0 && 'score' in result[0]) {
+                        span.setAttribute('db.vector.top_score', result[0].score);
+                    }
+                }
+            }
+            // Add result metadata for list operations
+            if (operation === 'vector.list' && Array.isArray(result)) {
+                span.setAttribute('db.query.result_count', result.length);
+            }
+            // Mark span as successful
+            span.setStatus({ code: api_1.SpanStatusCode.OK });
+            return result;
+        }
+        catch (error) {
+            // Record error in span
+            span.setStatus({
+                code: api_1.SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error)
+            });
+            span.recordException(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+}

package/dist/core/tracing/tool-tracing.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Tool Execution Tracing for MCP Tools
+ *
+ * Provides generic tracing wrapper for all MCP tool executions,
+ * creating INTERNAL spans with GenAI semantic conventions.
+ *
+ * Supports both STDIO (MCP) and HTTP (REST) transports transparently.
+ */
+/**
+ * Wraps a tool handler with OpenTelemetry tracing
+ *
+ * Creates an INTERNAL span for tool execution with:
+ * - Tool name and input arguments
+ * - Execution duration and success status
+ * - Exception tracking for errors
+ * - GenAI semantic conventions (gen_ai.tool.*)
+ *
+ * @param toolName - Name of the MCP tool being executed
+ * @param args - Tool input arguments (will be serialized to JSON)
+ * @param handler - Async function that implements the tool logic
+ * @returns Promise resolving to the tool handler result
+ *
+ * @example
+ * ```typescript
+ * const result = await withToolTracing('recommend', { intent: 'deploy postgres' }, async (args) => {
+ *   return await handleRecommendTool(args);
+ * });
+ * ```
+ */
+export declare function withToolTracing<T>(toolName: string, args: any, handler: (args: any) => Promise<T>): Promise<T>;
+//# sourceMappingURL=tool-tracing.d.ts.map

package/dist/core/tracing/tool-tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-tracing.d.ts","sourceRoot":"","sources":["../../../src/core/tracing/tool-tracing.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,GAAG,EACT,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,GACjC,OAAO,CAAC,CAAC,CAAC,CAgDZ"}

package/dist/core/tracing/tool-tracing.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * Tool Execution Tracing for MCP Tools
+ *
+ * Provides generic tracing wrapper for all MCP tool executions,
+ * creating INTERNAL spans with GenAI semantic conventions.
+ *
+ * Supports both STDIO (MCP) and HTTP (REST) transports transparently.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withToolTracing = withToolTracing;
+const api_1 = require("@opentelemetry/api");
+/**
+ * Wraps a tool handler with OpenTelemetry tracing
+ *
+ * Creates an INTERNAL span for tool execution with:
+ * - Tool name and input arguments
+ * - Execution duration and success status
+ * - Exception tracking for errors
+ * - GenAI semantic conventions (gen_ai.tool.*)
+ *
+ * @param toolName - Name of the MCP tool being executed
+ * @param args - Tool input arguments (will be serialized to JSON)
+ * @param handler - Async function that implements the tool logic
+ * @returns Promise resolving to the tool handler result
+ *
+ * @example
+ * ```typescript
+ * const result = await withToolTracing('recommend', { intent: 'deploy postgres' }, async (args) => {
+ *   return await handleRecommendTool(args);
+ * });
+ * ```
+ */
+async function withToolTracing(toolName, args, handler) {
+    const tracer = api_1.trace.getTracer('dot-ai-mcp');
+    // Create INTERNAL span for tool execution
+    // Using INTERNAL kind since this is business logic within the server process
+    const span = tracer.startSpan(`execute_tool ${toolName}`, {
+        kind: api_1.SpanKind.INTERNAL,
+        attributes: {
+            // GenAI semantic conventions for tool execution
+            'gen_ai.tool.name': toolName,
+            'gen_ai.tool.input': JSON.stringify(args, null, 2),
+        },
+    });
+    // Execute handler within active span context
+    // This ensures any child spans (AI calls, K8s operations) become children of this span
+    return await api_1.context.with(api_1.trace.setSpan(api_1.context.active(), span), async () => {
+        try {
+            const startTime = Date.now();
+            const result = await handler(args);
+            const duration = Date.now() - startTime;
+            // Record success metrics
+            span.setAttributes({
+                'gen_ai.tool.duration_ms': duration,
+                'gen_ai.tool.success': true,
+            });
+            span.setStatus({ code: api_1.SpanStatusCode.OK });
+            return result;
+        }
+        catch (error) {
+            // Record error details without disrupting original error flow
+            span.recordException(error);
+            span.setStatus({
+                code: api_1.SpanStatusCode.ERROR,
+                message: error.message,
+            });
+            // Re-throw to preserve original error handling behavior
+            throw error;
+        }
+        finally {
+            // Always end span regardless of success/failure
+            span.end();
+        }
+    });
+}

package/dist/core/tracing/tracer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * OpenTelemetry Tracer Service
+ *
+ * Provides lazy initialization and management of distributed tracing.
+ * Follows OpenTelemetry best practices with support for multiple exporters.
+ */
+import { SpanOptions } from '@opentelemetry/api';
+import { TracedSpan, TracerService } from './types';
+/**
+ * Get or create the global tracer instance
+ */
+export declare function getTracer(): TracerService;
+/**
+ * Shutdown the global tracer instance
+ */
+export declare function shutdownTracer(): Promise<void>;
+/**
+ * Helper function to wrap async operations with tracing
+ */
+export declare function withSpan<T>(name: string, fn: (span: TracedSpan) => Promise<T>, options?: SpanOptions): Promise<T>;
+//# sourceMappingURL=tracer.d.ts.map

package/dist/core/tracing/tracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../../src/core/tracing/tracer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,OAAO,EAKL,WAAW,EAEZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAiB,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAiMnE;;GAEG;AACH,wBAAgB,SAAS,IAAI,aAAa,CAMzC;AAED;;GAEG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAKpD;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,EACpC,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,CAAC,CAAC,CAYZ"}

package/dist/core/tracing/tracer.js

@@ -0,0 +1,215 @@
+"use strict";
+/**
+ * OpenTelemetry Tracer Service
+ *
+ * Provides lazy initialization and management of distributed tracing.
+ * Follows OpenTelemetry best practices with support for multiple exporters.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTracer = getTracer;
+exports.shutdownTracer = shutdownTracer;
+exports.withSpan = withSpan;
+const sdk_node_1 = require("@opentelemetry/sdk-node");
+const resources_1 = require("@opentelemetry/resources");
+const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
+const sdk_trace_node_1 = require("@opentelemetry/sdk-trace-node");
+const exporter_trace_otlp_http_1 = require("@opentelemetry/exporter-trace-otlp-http");
+const api_1 = require("@opentelemetry/api");
+const config_1 = require("./config");
+/**
+ * Global tracer instance (singleton pattern with lazy initialization)
+ */
+let tracerInstance = null;
+/**
+ * OpenTelemetry Tracer implementation
+ */
+class OpenTelemetryTracer {
+    sdk = null;
+    config;
+    initialized = false;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Initialize the OpenTelemetry SDK (called lazily on first use)
+     */
+    initialize() {
+        if (this.initialized) {
+            return; // Already initialized
+        }
+        if (!this.config.enabled) {
+            if (this.config.debug) {
+                console.log('[Tracing] Tracing is disabled, skipping initialization');
+            }
+            return;
+        }
+        try {
+            // Validate configuration
+            (0, config_1.validateTracingConfig)(this.config);
+            // Create resource with service identification
+            const serviceResource = (0, resources_1.resourceFromAttributes)({
+                [semantic_conventions_1.ATTR_SERVICE_NAME]: this.config.serviceName,
+                [semantic_conventions_1.ATTR_SERVICE_VERSION]: this.config.serviceVersion,
+            });
+            const resource = (0, resources_1.defaultResource)().merge(serviceResource);
+            // Create exporter based on configuration
+            const traceExporter = this.createExporter();
+            // Initialize Node SDK without auto-instrumentation
+            // All operations are manually instrumented with descriptive spans
+            this.sdk = new sdk_node_1.NodeSDK({
+                resource,
+                traceExporter,
+                instrumentations: [], // No auto-instrumentation needed
+            });
+            // Start the SDK
+            this.sdk.start();
+            this.initialized = true;
+            if (this.config.debug) {
+                console.log('[Tracing] OpenTelemetry initialized successfully', {
+                    serviceName: this.config.serviceName,
+                    serviceVersion: this.config.serviceVersion,
+                    exporterType: this.config.exporterType,
+                });
+            }
+        }
+        catch (error) {
+            console.error('[Tracing] Failed to initialize OpenTelemetry:', error);
+            throw error;
+        }
+    }
+    /**
+     * Create exporter based on configuration
+     */
+    createExporter() {
+        switch (this.config.exporterType) {
+            case 'console':
+                if (this.config.debug) {
+                    console.log('[Tracing] Using console exporter (outputs to stderr)');
+                }
+                return new sdk_trace_node_1.ConsoleSpanExporter();
+            case 'otlp':
+                if (this.config.debug) {
+                    console.log('[Tracing] Using OTLP exporter', {
+                        endpoint: this.config.otlpEndpoint || 'http://localhost:4318/v1/traces'
+                    });
+                }
+                return new exporter_trace_otlp_http_1.OTLPTraceExporter({
+                    url: this.config.otlpEndpoint || 'http://localhost:4318/v1/traces',
+                });
+            case 'jaeger':
+                // Jaeger exporter will be added in Phase 3
+                throw new Error('Jaeger exporter not yet implemented - coming in Phase 3');
+            case 'zipkin':
+                // Zipkin exporter will be added in Phase 3
+                throw new Error('Zipkin exporter not yet implemented - coming in Phase 3');
+            default:
+                throw new Error(`Unknown exporter type: ${this.config.exporterType}`);
+        }
+    }
+    /**
+     * Check if tracing is enabled
+     */
+    isEnabled() {
+        return this.config.enabled;
+    }
+    /**
+     * Create a new span with utility methods
+     */
+    startSpan(name, options, parentContext) {
+        if (!this.config.enabled) {
+            // Return a no-op span if tracing is disabled
+            return this.createNoOpSpan();
+        }
+        // Lazy initialization on first span creation
+        if (!this.initialized) {
+            this.initialize();
+        }
+        const tracer = api_1.trace.getTracer(this.config.serviceName, this.config.serviceVersion);
+        const ctx = parentContext || api_1.context.active();
+        const span = tracer.startSpan(name, options, ctx);
+        return this.wrapSpan(span);
+    }
+    /**
+     * Wrap an OpenTelemetry span with utility methods
+     */
+    wrapSpan(span) {
+        return {
+            span,
+            end() {
+                span.setStatus({ code: api_1.SpanStatusCode.OK });
+                span.end();
+            },
+            endWithError(error) {
+                span.recordException(error);
+                span.setStatus({
+                    code: api_1.SpanStatusCode.ERROR,
+                    message: error.message,
+                });
+                span.end();
+            },
+            setAttributes(attributes) {
+                span.setAttributes(attributes);
+            },
+            addEvent(name, attributes) {
+                span.addEvent(name, attributes);
+            },
+        };
+    }
+    /**
+     * Create a no-op span for when tracing is disabled
+     */
+    createNoOpSpan() {
+        const noopSpan = api_1.trace.getTracer('noop').startSpan('noop');
+        return this.wrapSpan(noopSpan);
+    }
+    /**
+     * Shutdown the tracer gracefully
+     */
+    async shutdown() {
+        if (this.sdk && this.initialized) {
+            if (this.config.debug) {
+                console.log('[Tracing] Shutting down OpenTelemetry SDK...');
+            }
+            await this.sdk.shutdown();
+            this.initialized = false;
+            if (this.config.debug) {
+                console.log('[Tracing] OpenTelemetry SDK shut down successfully');
+            }
+        }
+    }
+}
+/**
+ * Get or create the global tracer instance
+ */
+function getTracer() {
+    if (!tracerInstance) {
+        const config = (0, config_1.loadTracingConfig)();
+        tracerInstance = new OpenTelemetryTracer(config);
+    }
+    return tracerInstance;
+}
+/**
+ * Shutdown the global tracer instance
+ */
+async function shutdownTracer() {
+    if (tracerInstance) {
+        await tracerInstance.shutdown();
+        tracerInstance = null;
+    }
+}
+/**
+ * Helper function to wrap async operations with tracing
+ */
+async function withSpan(name, fn, options) {
+    const tracer = getTracer();
+    const span = tracer.startSpan(name, options);
+    try {
+        const result = await fn(span);
+        span.end();
+        return result;
+    }
+    catch (error) {
+        span.endWithError(error);
+        throw error;
+    }
+}