@skillsmith/core 0.4.0 → 0.4.2

package/dist/src/telemetry/tracer-types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Type definitions for Skillsmith Tracer
+ * @module @skillsmith/core/telemetry/tracer-types
+ */
+/**
+ * Local type definitions matching OpenTelemetry interfaces
+ * SMI-755: Allows compilation without @opentelemetry/api installed
+ */
+export interface OTelSpan {
+    setAttributes(attributes: Record<string, unknown>): void;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): void;
+    recordException(error: Error): void;
+    addEvent(name: string, attributes?: Record<string, unknown>): void;
+    end(): void;
+}
+export interface OTelTracer {
+    startSpan(name: string, options?: unknown): OTelSpan;
+}
+export interface OTelSpanOptions {
+    attributes?: Record<string, unknown>;
+    links?: unknown[];
+    startTime?: number;
+    root?: boolean;
+    kind?: number;
+}
+export type Span = OTelSpan;
+export type Tracer = OTelTracer;
+export type SpanOptions = OTelSpanOptions;
+export type SpanStatusCode = number;
+/**
+ * Tracer configuration
+ */
+export interface TracerConfig {
+    /** Service name for spans (default: skillsmith) */
+    serviceName?: string;
+    /** OTLP endpoint URL */
+    endpoint?: string;
+    /** Enable auto-instrumentation (default: true) */
+    autoInstrument?: boolean;
+    /** Enable console exporter for debugging (default: false) */
+    consoleExport?: boolean;
+    /** Sample rate 0-1 (default: 1.0 = 100%) */
+    sampleRate?: number;
+}
+/**
+ * Span attribute types
+ */
+export interface SpanAttributes {
+    [key: string]: string | number | boolean | string[] | number[] | boolean[] | undefined;
+}
+/**
+ * Span wrapper for easier usage
+ */
+export interface SpanWrapper {
+    /** Add attributes to span */
+    setAttributes(attributes: SpanAttributes): void;
+    /** Set span status */
+    setStatus(code: 'ok' | 'error', message?: string): void;
+    /** Record an exception */
+    recordException(error: Error): void;
+    /** Add an event to the span */
+    addEvent(name: string, attributes?: SpanAttributes): void;
+    /** End the span */
+    end(): void;
+    /** Get the underlying OTEL span (if available) */
+    getSpan(): Span | null;
+}
+/**
+ * Type-safe accessors for OTEL modules (SMI-755)
+ * These provide typed access while avoiding compile-time dependency
+ */
+export interface OTelApi {
+    trace: {
+        getTracer(name: string, version?: string): OTelTracer;
+        getActiveSpan(): OTelSpan | undefined;
+    };
+}
+export interface OTelNodeSDK {
+    new (config: unknown): {
+        start(): Promise<void>;
+        shutdown(): Promise<void>;
+    };
+}
+/**
+ * Resource factory function type (v2.x uses resourceFromAttributes instead of class)
+ */
+export type OTelResourceFromAttributes = (attributes: Record<string, string>) => unknown;
+//# sourceMappingURL=tracer-types.d.ts.map

package/dist/src/telemetry/tracer-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer-types.d.ts","sourceRoot":"","sources":["../../../src/telemetry/tracer-types.ts"],"names":[],"mappings":"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"}

package/dist/src/telemetry/tracer-types.js

@@ -0,0 +1,6 @@
+/**
+ * Type definitions for Skillsmith Tracer
+ * @module @skillsmith/core/telemetry/tracer-types
+ */
+export {};
+//# sourceMappingURL=tracer-types.js.map

package/dist/src/telemetry/tracer-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer-types.js","sourceRoot":"","sources":["../../../src/telemetry/tracer-types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/src/telemetry/tracer.d.ts

@@ -2,84 +2,13 @@
  * SMI-739: OpenTelemetry Tracer Setup
  * SMI-755: Graceful fallback when OpenTelemetry unavailable
  *
- * Provides distributed tracing for Skillsmith operations:
- * - MCP tool calls
- * - Database queries
- * - Cache operations
- * - External API calls
+ * Provides distributed tracing for Skillsmith operations.
  *
- * Configuration:
- * - OTEL_EXPORTER_OTLP_ENDPOINT: OTLP endpoint for trace export
- * - OTEL_SERVICE_NAME: Service name (default: skillsmith)
- * - SKILLSMITH_TELEMETRY_ENABLED: Master switch for all telemetry (default: auto)
- * - SKILLSMITH_TRACING_ENABLED: Enable/disable tracing (default: true if endpoint set)
- *
- * Graceful Fallback:
- * - If OpenTelemetry packages are not installed, uses NoOp implementations
- * - Logs warning on fallback (unless SKILLSMITH_TELEMETRY_ENABLED=false)
- * - All tracing APIs remain functional (just don't record)
- */
-/**
- * Local type definitions matching OpenTelemetry interfaces
- * SMI-755: Allows compilation without @opentelemetry/api installed
- */
-interface OTelSpan {
-    setAttributes(attributes: Record<string, unknown>): void;
-    setStatus(status: {
-        code: number;
-        message?: string;
-    }): void;
-    recordException(error: Error): void;
-    addEvent(name: string, attributes?: Record<string, unknown>): void;
-    end(): void;
-}
-interface OTelSpanOptions {
-    attributes?: Record<string, unknown>;
-    links?: unknown[];
-    startTime?: number;
-    root?: boolean;
-    kind?: number;
-}
-type Span = OTelSpan;
-type SpanOptions = OTelSpanOptions;
-/**
- * Tracer configuration
- */
-export interface TracerConfig {
-    /** Service name for spans (default: skillsmith) */
-    serviceName?: string;
-    /** OTLP endpoint URL */
-    endpoint?: string;
-    /** Enable auto-instrumentation (default: true) */
-    autoInstrument?: boolean;
-    /** Enable console exporter for debugging (default: false) */
-    consoleExport?: boolean;
-    /** Sample rate 0-1 (default: 1.0 = 100%) */
-    sampleRate?: number;
-}
-/**
- * Span attribute types
- */
-export interface SpanAttributes {
-    [key: string]: string | number | boolean | string[] | number[] | boolean[] | undefined;
-}
-/**
- * Span wrapper for easier usage
+ * @see tracer-types.ts for type definitions
+ * @see span-utils.ts for span wrapper classes
  */
-export interface SpanWrapper {
-    /** Add attributes to span */
-    setAttributes(attributes: SpanAttributes): void;
-    /** Set span status */
-    setStatus(code: 'ok' | 'error', message?: string): void;
-    /** Record an exception */
-    recordException(error: Error): void;
-    /** Add an event to the span */
-    addEvent(name: string, attributes?: SpanAttributes): void;
-    /** End the span */
-    end(): void;
-    /** Get the underlying OTEL span (if available) */
-    getSpan(): Span | null;
-}
+export type { TracerConfig, SpanAttributes, SpanWrapper, Span, Tracer, SpanOptions, OTelApi, OTelNodeSDK, OTelResourceFromAttributes, } from './tracer-types.js';
+import type { TracerConfig, SpanOptions, SpanWrapper } from './tracer-types.js';
 /**
  * Skillsmith Tracer - Wrapper for OpenTelemetry tracing
  */
@@ -90,62 +19,16 @@ export declare class SkillsmithTracer {
     private config;
     private sdkInstance;
     constructor(config?: TracerConfig);
-    /**
-     * Initialize the tracer
-     * Must be called before creating spans
-     */
     initialize(): Promise<void>;
-    /**
-     * Check if tracing is enabled
-     */
     isEnabled(): boolean;
-    /**
-     * Start a new span
-     *
-     * @param name - Span name (e.g., 'mcp.tool.search', 'db.query')
-     * @param options - Span options
-     * @returns SpanWrapper for manipulating the span
-     */
     startSpan(name: string, options?: SpanOptions): SpanWrapper;
-    /**
-     * Execute a function within a span context
-     *
-     * @param name - Span name
-     * @param fn - Function to execute
-     * @param options - Span options
-     * @returns Result of the function
-     */
     withSpan<T>(name: string, fn: (span: SpanWrapper) => Promise<T>, options?: SpanOptions): Promise<T>;
-    /**
-     * Execute a synchronous function within a span context
-     */
     withSpanSync<T>(name: string, fn: (span: SpanWrapper) => T, options?: SpanOptions): T;
-    /**
-     * Get the current active span (if any)
-     */
     getCurrentSpan(): SpanWrapper;
-    /**
-     * Shutdown the tracer and flush pending spans
-     */
     shutdown(): Promise<void>;
 }
-/**
- * Get the default tracer instance
- */
 export declare function getTracer(): SkillsmithTracer;
-/**
- * Initialize the default tracer
- * Should be called at application startup
- */
 export declare function initializeTracing(config?: TracerConfig): Promise<SkillsmithTracer>;
-/**
- * Shutdown the default tracer
- * Should be called at application shutdown
- */
 export declare function shutdownTracing(): Promise<void>;
-/**
- * Decorator for tracing async methods
- */
 export declare function traced(spanName?: string): <T extends (...args: unknown[]) => Promise<unknown>>(target: unknown, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T>;
-export {};
 //# sourceMappingURL=tracer.d.ts.map

package/dist/src/telemetry/tracer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../../src/telemetry/tracer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../../src/telemetry/tracer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,YAAY,EACV,YAAY,EACZ,cAAc,EACd,WAAW,EACX,IAAI,EACJ,MAAM,EACN,WAAW,EACX,OAAO,EACP,WAAW,EACX,0BAA0B,GAC3B,MAAM,mBAAmB,CAAA;AAG1B,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,WAAW,EAKZ,MAAM,mBAAmB,CAAA;AAwC1B;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,WAAW,CAAqE;gBAE5E,MAAM,GAAE,YAAiB;IAwB/B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA8EjC,SAAS,IAAI,OAAO;IAIpB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,WAAW;IAMrD,QAAQ,CAAC,CAAC,EACd,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EACrC,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,CAAC,CAAC;IAeb,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,CAAC;IAerF,cAAc,IAAI,WAAW;IAQvB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAQhC;AAKD,wBAAgB,SAAS,IAAI,gBAAgB,CAG5C;AAED,wBAAsB,iBAAiB,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAKxF;AAED,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAKrD;AAED,wBAAgB,MAAM,CAAC,QAAQ,CAAC,EAAE,MAAM,IACrB,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,EACjE,QAAQ,OAAO,EACf,aAAa,MAAM,EACnB,YAAY,uBAAuB,CAAC,CAAC,CAAC,KACrC,uBAAuB,CAAC,CAAC,CAAC,CAkB9B"}

package/dist/src/telemetry/tracer.js

@@ -2,50 +2,20 @@
  * SMI-739: OpenTelemetry Tracer Setup
  * SMI-755: Graceful fallback when OpenTelemetry unavailable
  *
- * Provides distributed tracing for Skillsmith operations:
- * - MCP tool calls
- * - Database queries
- * - Cache operations
- * - External API calls
+ * Provides distributed tracing for Skillsmith operations.
  *
- * Configuration:
- * - OTEL_EXPORTER_OTLP_ENDPOINT: OTLP endpoint for trace export
- * - OTEL_SERVICE_NAME: Service name (default: skillsmith)
- * - SKILLSMITH_TELEMETRY_ENABLED: Master switch for all telemetry (default: auto)
- * - SKILLSMITH_TRACING_ENABLED: Enable/disable tracing (default: true if endpoint set)
- *
- * Graceful Fallback:
- * - If OpenTelemetry packages are not installed, uses NoOp implementations
- * - Logs warning on fallback (unless SKILLSMITH_TELEMETRY_ENABLED=false)
- * - All tracing APIs remain functional (just don't record)
+ * @see tracer-types.ts for type definitions
+ * @see span-utils.ts for span wrapper classes
  */
+import { NoOpSpanWrapper, ActiveSpanWrapper } from './span-utils.js';
 // Lazy import to avoid loading OTEL if not needed
-// SMI-755: Use 'unknown' types to avoid compile-time dependency on OTEL packages
 let api = null;
 let sdk = null;
 let resources = null;
 let semanticConventions = null;
-function getApi() {
-    return api;
-}
-function getSdk() {
-    return sdk;
-}
-function getResources() {
-    return resources;
-}
-function getSemanticConventions() {
-    return semanticConventions;
-}
-/** Whether OpenTelemetry packages are available */
 let otelAvailable = null;
-/**
- * Dynamic import helper that bypasses TypeScript type checking (SMI-755)
- * This allows the code to compile even when @opentelemetry packages aren't installed
- */
 async function dynamicImport(moduleName) {
     try {
-        // Use Function constructor to bypass TypeScript's static analysis
         const importFn = new Function('m', 'return import(m)');
         return await importFn(moduleName);
     }
@@ -53,9 +23,6 @@ async function dynamicImport(moduleName) {
         return null;
     }
 }
-/**
- * Check if OpenTelemetry is available (SMI-755)
- */
 async function checkOTelAvailability() {
     if (otelAvailable !== null)
         return otelAvailable;
@@ -63,62 +30,17 @@ async function checkOTelAvailability() {
     otelAvailable = result !== null;
     return otelAvailable;
 }
-/**
- * No-op span wrapper for when tracing is disabled
- */
-class NoOpSpanWrapper {
-    setAttributes(_attributes) { }
-    setStatus(_code, _message) { }
-    recordException(_error) { }
-    addEvent(_name, _attributes) { }
-    end() { }
-    getSpan() {
-        return null;
-    }
+function getApi() {
+    return api;
 }
-/**
- * Active span wrapper with real OTEL span
- */
-class ActiveSpanWrapper {
-    span;
-    constructor(span) {
-        this.span = span;
-    }
-    setAttributes(attributes) {
-        // Filter out undefined values
-        const filtered = {};
-        for (const [key, value] of Object.entries(attributes)) {
-            if (value !== undefined) {
-                filtered[key] = value;
-            }
-        }
-        this.span.setAttributes(filtered);
-    }
-    setStatus(code, message) {
-        const statusCode = code === 'ok' ? 1 : 2; // SpanStatusCode.OK = 1, ERROR = 2
-        this.span.setStatus({ code: statusCode, message });
-    }
-    recordException(error) {
-        this.span.recordException(error);
-    }
-    addEvent(name, attributes) {
-        // Filter out undefined values
-        const filtered = {};
-        if (attributes) {
-            for (const [key, value] of Object.entries(attributes)) {
-                if (value !== undefined) {
-                    filtered[key] = value;
-                }
-            }
-        }
-        this.span.addEvent(name, filtered);
-    }
-    end() {
-        this.span.end();
-    }
-    getSpan() {
-        return this.span;
-    }
+function getSdk() {
+    return sdk;
+}
+function getResources() {
+    return resources;
+}
+function getSemanticConventions() {
+    return semanticConventions;
 }
 /**
  * Skillsmith Tracer - Wrapper for OpenTelemetry tracing
@@ -137,13 +59,11 @@ export class SkillsmithTracer {
             consoleExport: config.consoleExport ?? false,
             sampleRate: config.sampleRate ?? 1.0,
         };
-        // SMI-755: Check master telemetry switch first
         const telemetryDisabled = process.env.SKILLSMITH_TELEMETRY_ENABLED === 'false';
         if (telemetryDisabled) {
             this.enabled = false;
             return;
         }
-        // Check if tracing should be enabled
         const explicitlyEnabled = process.env.SKILLSMITH_TRACING_ENABLED === 'true';
         const explicitlyDisabled = process.env.SKILLSMITH_TRACING_ENABLED === 'false';
         if (explicitlyDisabled) {
@@ -153,10 +73,6 @@ export class SkillsmithTracer {
             this.enabled = true;
         }
     }
-    /**
-     * Initialize the tracer
-     * Must be called before creating spans
-     */
     async initialize() {
         if (this.initialized)
             return;
@@ -164,30 +80,24 @@ export class SkillsmithTracer {
             this.initialized = true;
             return;
         }
-        // SMI-755: Check if OpenTelemetry is available before attempting to load
         const isAvailable = await checkOTelAvailability();
         if (!isAvailable) {
-            console.warn('[Skillsmith Telemetry] OpenTelemetry packages not installed. ' +
-                'Tracing disabled. Install @opentelemetry/api and related packages to enable.');
+            console.warn('[Skillsmith Telemetry] OpenTelemetry packages not installed. Tracing disabled.');
             this.enabled = false;
             this.initialized = true;
             return;
         }
         try {
-            // SMI-755: Lazy load OTEL modules with error handling
-            // Use dynamicImport to bypass TypeScript type checking
             api = await dynamicImport('@opentelemetry/api');
             sdk = await dynamicImport('@opentelemetry/sdk-node');
             resources = await dynamicImport('@opentelemetry/resources');
             semanticConventions = await dynamicImport('@opentelemetry/semantic-conventions');
-            // If any core module failed to load, disable tracing
             if (!api || !sdk || !resources || !semanticConventions) {
                 console.warn('[Skillsmith Telemetry] Some OpenTelemetry packages missing. Tracing disabled.');
                 this.enabled = false;
                 this.initialized = true;
                 return;
             }
-            // Get typed accessors
             const otelApi = getApi();
             const otelSdk = getSdk();
             const otelResources = getResources();
@@ -197,22 +107,17 @@ export class SkillsmithTracer {
                 this.initialized = true;
                 return;
             }
-            // Build SDK configuration
             const sdkConfig = {};
-            // Create resource with service info
-            const Resource = otelResources.Resource;
-            sdkConfig.resource = new Resource({
+            sdkConfig.resource = otelResources.resourceFromAttributes({
                 [otelSemConv['ATTR_SERVICE_NAME'] ?? 'service.name']: this.config.serviceName,
                 [otelSemConv['ATTR_SERVICE_VERSION'] ?? 'service.version']: '0.1.0',
             });
-            // Add auto-instrumentation if enabled
             if (this.config.autoInstrument) {
                 try {
                     const autoInst = (await dynamicImport('@opentelemetry/auto-instrumentations-node'));
                     if (autoInst?.getNodeAutoInstrumentations) {
                         sdkConfig.instrumentations = [
                             autoInst.getNodeAutoInstrumentations({
-                                // Customize instrumentations
                                 '@opentelemetry/instrumentation-fs': { enabled: false },
                                 '@opentelemetry/instrumentation-dns': { enabled: false },
                                 '@opentelemetry/instrumentation-net': { enabled: false },
@@ -221,52 +126,30 @@ export class SkillsmithTracer {
                     }
                 }
                 catch {
-                    // Auto-instrumentation optional, continue without it
+                    // Auto-instrumentation optional
                 }
             }
-            // Initialize SDK
             const NodeSDK = otelSdk.NodeSDK;
             this.sdkInstance = new NodeSDK(sdkConfig);
             await this.sdkInstance.start();
-            // Get tracer
             this.tracer = otelApi.trace.getTracer(this.config.serviceName, '0.1.0');
             this.initialized = true;
         }
         catch (error) {
-            // SMI-755: Graceful fallback - disable tracing on error
             console.warn('[Skillsmith Telemetry] Failed to initialize OpenTelemetry tracing:', error);
             this.enabled = false;
             this.initialized = true;
         }
     }
-    /**
-     * Check if tracing is enabled
-     */
     isEnabled() {
         return this.enabled && this.initialized;
     }
-    /**
-     * Start a new span
-     *
-     * @param name - Span name (e.g., 'mcp.tool.search', 'db.query')
-     * @param options - Span options
-     * @returns SpanWrapper for manipulating the span
-     */
     startSpan(name, options) {
-        if (!this.isEnabled() || !this.tracer) {
+        if (!this.isEnabled() || !this.tracer)
             return new NoOpSpanWrapper();
-        }
         const span = this.tracer.startSpan(name, options);
         return new ActiveSpanWrapper(span);
     }
-    /**
-     * Execute a function within a span context
-     *
-     * @param name - Span name
-     * @param fn - Function to execute
-     * @param options - Span options
-     * @returns Result of the function
-     */
     async withSpan(name, fn, options) {
         const spanWrapper = this.startSpan(name, options);
         try {
@@ -275,9 +158,8 @@ export class SkillsmithTracer {
             return result;
         }
         catch (error) {
-            if (error instanceof Error) {
+            if (error instanceof Error)
                 spanWrapper.recordException(error);
-            }
             spanWrapper.setStatus('error', error instanceof Error ? error.message : 'Unknown error');
             throw error;
         }
@@ -285,9 +167,6 @@ export class SkillsmithTracer {
             spanWrapper.end();
         }
     }
-    /**
-     * Execute a synchronous function within a span context
-     */
     withSpanSync(name, fn, options) {
         const spanWrapper = this.startSpan(name, options);
         try {
@@ -296,9 +175,8 @@ export class SkillsmithTracer {
             return result;
         }
         catch (error) {
-            if (error instanceof Error) {
+            if (error instanceof Error)
                 spanWrapper.recordException(error);
-            }
             spanWrapper.setStatus('error', error instanceof Error ? error.message : 'Unknown error');
             throw error;
         }
@@ -306,23 +184,15 @@ export class SkillsmithTracer {
             spanWrapper.end();
         }
     }
-    /**
-     * Get the current active span (if any)
-     */
     getCurrentSpan() {
         const otelApi = getApi();
-        if (!otelApi) {
+        if (!otelApi)
             return new NoOpSpanWrapper();
-        }
         const span = otelApi.trace.getActiveSpan();
-        if (!span) {
+        if (!span)
             return new NoOpSpanWrapper();
-        }
         return new ActiveSpanWrapper(span);
     }
-    /**
-     * Shutdown the tracer and flush pending spans
-     */
     async shutdown() {
         if (this.sdkInstance) {
             await this.sdkInstance.shutdown();
@@ -334,40 +204,24 @@ export class SkillsmithTracer {
 }
 // Default tracer instance
 let defaultTracer = null;
-/**
- * Get the default tracer instance
- */
 export function getTracer() {
-    if (!defaultTracer) {
+    if (!defaultTracer)
         defaultTracer = new SkillsmithTracer();
-    }
     return defaultTracer;
 }
-/**
- * Initialize the default tracer
- * Should be called at application startup
- */
 export async function initializeTracing(config) {
-    if (defaultTracer) {
+    if (defaultTracer)
         await defaultTracer.shutdown();
-    }
     defaultTracer = new SkillsmithTracer(config);
     await defaultTracer.initialize();
     return defaultTracer;
 }
-/**
- * Shutdown the default tracer
- * Should be called at application shutdown
- */
 export async function shutdownTracing() {
     if (defaultTracer) {
         await defaultTracer.shutdown();
         defaultTracer = null;
     }
 }
-/**
- * Decorator for tracing async methods
- */
 export function traced(spanName) {
     return function (target, propertyKey, descriptor) {
         const originalMethod = descriptor.value;