@agentick/core 0.0.1

package/dist/core/logger.js

@@ -0,0 +1,346 @@
+/**
+ * Logger - Structured logging with automatic context injection
+ *
+ * Built on pino for performance, with automatic injection of:
+ * - Execution context (executionId, threadId, userId, tick)
+ * - OpenTelemetry trace/span IDs for log-trace correlation
+ * - Custom metadata
+ *
+ * @example
+ * ```typescript
+ * import { Logger } from './core';
+ *
+ * // Configure once at app start
+ * Logger.configure({
+ *   level: 'info',
+ *   transport: {
+ *     targets: [
+ *       { target: 'pino-pretty', options: { colorize: true } },
+ *       { target: 'pino/file', options: { destination: './app.log' } },
+ *     ],
+ *   },
+ * });
+ *
+ * // Use anywhere - context is auto-injected
+ * const log = Logger.get();
+ * log.info('Processing request');
+ *
+ * // Create scoped child logger
+ * const toolLog = Logger.for('CalculatorTool');
+ * toolLog.debug('Executing', { expression: '2+2' });
+ * ```
+ */
+import pino, {} from "pino";
+import { Context } from "./context";
+// =============================================================================
+// Implementation
+// =============================================================================
+let globalLogger = null;
+let globalConfig = {};
+/**
+ * Default context fields extractor.
+ * Only extracts well-defined KernelContext properties.
+ * Does NOT make assumptions about user/metadata structure.
+ */
+const defaultContextFieldsExtractor = (ctx) => {
+    const fields = {};
+    // Core KernelContext fields (well-defined)
+    if (ctx.requestId)
+        fields.request_id = ctx.requestId;
+    if (ctx.traceId)
+        fields.trace_id = ctx.traceId;
+    // Procedure context (well-defined)
+    if (ctx.procedurePid)
+        fields.procedure_id = ctx.procedurePid;
+    if (ctx.procedureNode?.name)
+        fields.procedure_name = ctx.procedureNode.name;
+    if (ctx.origin?.name)
+        fields.origin_procedure = ctx.origin.name;
+    return fields;
+};
+/**
+ * Extract context fields for logging.
+ * Called on every log to inject current execution context.
+ */
+function getContextFields(config) {
+    if (config.includeContext === false) {
+        return {};
+    }
+    const ctx = Context.tryGet();
+    if (!ctx) {
+        return {};
+    }
+    // Use custom extractor or default
+    const extractor = config.contextFields ?? defaultContextFieldsExtractor;
+    return extractor(ctx);
+}
+/**
+ * Create pino logger options from config.
+ */
+function createPinoOptions(config) {
+    const isDev = process.env.NODE_ENV !== "production";
+    const usePretty = config.prettyPrint ?? isDev;
+    const options = {
+        level: config.level ?? "info",
+        base: config.base ?? { pid: process.pid },
+        // Mixin runs on every log to inject context
+        mixin: () => {
+            const contextFields = getContextFields(config);
+            const customFields = config.mixin?.() ?? {};
+            return { ...contextFields, ...customFields };
+        },
+        // Timestamp in ISO format
+        timestamp: pino.stdTimeFunctions.isoTime,
+    };
+    // Transport configuration
+    if (config.transport) {
+        options.transport = config.transport;
+    }
+    else if (usePretty) {
+        options.transport = {
+            target: "pino-pretty",
+            options: {
+                colorize: true,
+                translateTime: "SYS:standard",
+                ignore: "pid,hostname",
+            },
+        };
+    }
+    return options;
+}
+/**
+ * Wrap pino logger to match KernelLogger interface.
+ */
+function wrapLogger(pinoLogger) {
+    return {
+        trace: pinoLogger.trace.bind(pinoLogger),
+        debug: pinoLogger.debug.bind(pinoLogger),
+        info: pinoLogger.info.bind(pinoLogger),
+        warn: pinoLogger.warn.bind(pinoLogger),
+        error: pinoLogger.error.bind(pinoLogger),
+        fatal: pinoLogger.fatal.bind(pinoLogger),
+        child(bindings) {
+            return wrapLogger(pinoLogger.child(bindings));
+        },
+        get level() {
+            return pinoLogger.level;
+        },
+        isLevelEnabled(level) {
+            return pinoLogger.isLevelEnabled(level);
+        },
+    };
+}
+/**
+ * Get or create the global logger instance.
+ */
+function getOrCreateGlobalLogger() {
+    if (!globalLogger) {
+        globalLogger = pino(createPinoOptions(globalConfig));
+    }
+    return globalLogger;
+}
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Logger singleton for Tentickle applications.
+ *
+ * Provides structured logging with automatic context injection from the
+ * current execution context (via AsyncLocalStorage).
+ *
+ * @example
+ * ```typescript
+ * // Configure at app startup
+ * Logger.configure({ level: 'debug' });
+ *
+ * // Get logger (context auto-injected)
+ * const log = Logger.get();
+ * log.info('Request received');
+ *
+ * // Create child logger for a component
+ * const componentLog = Logger.for('MyComponent');
+ * componentLog.debug('Initializing');
+ *
+ * // Or from an object (uses constructor name)
+ * class MyTool {
+ *   private log = Logger.for(this);
+ * }
+ * ```
+ */
+export const Logger = {
+    /**
+     * Configure the global logger.
+     * Should be called once at application startup.
+     *
+     * @param config Logger configuration
+     *
+     * @example
+     * ```typescript
+     * Logger.configure({
+     *   level: process.env.LOG_LEVEL ?? 'info',
+     *   transport: {
+     *     targets: [
+     *       { target: 'pino-pretty', options: { colorize: true } },
+     *       { target: 'pino/file', options: { destination: './logs/app.log' } },
+     *     ],
+     *   },
+     * });
+     * ```
+     */
+    configure(config) {
+        // Replace or merge with existing config
+        if (config.replace) {
+            globalConfig = config;
+        }
+        else {
+            globalConfig = { ...globalConfig, ...config };
+        }
+        // Handle contextFields composition
+        if (config.contextFields) {
+            globalConfig.contextFields = composeContextFields(defaultContextFields, config.contextFields);
+        }
+        else if (!globalConfig.contextFields) {
+            globalConfig.contextFields = defaultContextFields;
+        }
+        globalLogger = pino(createPinoOptions(globalConfig));
+    },
+    /**
+     * Get the global logger instance.
+     * Context is automatically injected into every log.
+     *
+     * @returns KernelLogger instance
+     *
+     * @example
+     * ```typescript
+     * const log = Logger.get();
+     * log.info('Processing', { items: 5 });
+     * // Output includes executionId, userId, trace_id, etc.
+     * ```
+     */
+    get() {
+        return wrapLogger(getOrCreateGlobalLogger());
+    },
+    /**
+     * Create a child logger scoped to a component or name.
+     *
+     * @param nameOrComponent Component name or object (uses constructor.name)
+     * @returns Child logger with component binding
+     *
+     * @example
+     * ```typescript
+     * // With string name
+     * const log = Logger.for('CalculatorTool');
+     *
+     * // With object (uses class name)
+     * class MyAgent {
+     *   private log = Logger.for(this);
+     * }
+     * ```
+     */
+    for(nameOrComponent) {
+        const name = typeof nameOrComponent === "string" ? nameOrComponent : nameOrComponent.constructor.name;
+        return wrapLogger(getOrCreateGlobalLogger().child({ component: name }));
+    },
+    /**
+     * Create a child logger with custom bindings.
+     *
+     * @param bindings Key-value pairs to include in every log
+     * @returns Child logger with bindings
+     *
+     * @example
+     * ```typescript
+     * const requestLog = Logger.child({ request_id: req.id });
+     * requestLog.info('Handling request');
+     * ```
+     */
+    child(bindings) {
+        return wrapLogger(getOrCreateGlobalLogger().child(bindings));
+    },
+    /**
+     * Create a standalone logger instance with custom config.
+     * Does not affect the global logger.
+     *
+     * @param config Logger configuration
+     * @returns New logger instance
+     *
+     * @example
+     * ```typescript
+     * const auditLog = Logger.create({
+     *   level: 'info',
+     *   transport: { target: 'pino/file', options: { destination: './audit.log' } },
+     * });
+     * ```
+     */
+    create(config = {}) {
+        return wrapLogger(pino(createPinoOptions(config)));
+    },
+    /**
+     * Get the current log level.
+     */
+    get level() {
+        return getOrCreateGlobalLogger().level;
+    },
+    /**
+     * Set the log level at runtime.
+     *
+     * @param level New log level
+     */
+    setLevel(level) {
+        getOrCreateGlobalLogger().level = level;
+    },
+    /**
+     * Check if a level is enabled.
+     *
+     * @param level Log level to check
+     * @returns true if the level is enabled
+     */
+    isLevelEnabled(level) {
+        return getOrCreateGlobalLogger().isLevelEnabled(level);
+    },
+    /**
+     * Reset the global logger (mainly for testing).
+     */
+    reset() {
+        globalLogger = null;
+        globalConfig = {};
+    },
+};
+// =============================================================================
+// Helpers
+// =============================================================================
+/**
+ * Compose multiple context field extractors into one.
+ * Later extractors override earlier ones for the same keys.
+ *
+ * @example
+ * ```typescript
+ * import { composeContextFields, defaultContextFields } from './core';
+ *
+ * Logger.configure({
+ *   contextFields: composeContextFields(
+ *     defaultContextFields,  // Core kernel fields
+ *     (ctx) => ({            // Your custom fields
+ *       tenantId: ctx.user?.tenantId,
+ *       threadId: ctx.metadata?.threadId,
+ *       executionId: ctx.metadata?.executionId,
+ *     }),
+ *   ),
+ * });
+ * ```
+ */
+export function composeContextFields(...extractors) {
+    return (ctx) => {
+        const result = {};
+        for (const extractor of extractors) {
+            Object.assign(result, extractor(ctx));
+        }
+        return result;
+    };
+}
+/**
+ * The default context fields extractor.
+ * Exports core KernelContext fields only.
+ * Use with composeContextFields to extend.
+ */
+export const defaultContextFields = defaultContextFieldsExtractor;
+//# sourceMappingURL=logger.js.map

package/dist/core/logger.js.map

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

package/dist/core/metrics-helpers.d.ts

@@ -0,0 +1,40 @@
+import { type KernelContext } from "./context";
+/**
+ * Helper functions for working with metrics.
+ * Supports both flat and nested metric structures via dot notation.
+ */
+/**
+ * Add a metric value (accumulates).
+ * Supports dot notation for nested paths: 'usage.inputTokens'
+ */
+export declare function addMetric(ctx: KernelContext, key: string, value: number): void;
+/**
+ * Set a metric value (overwrites).
+ * Supports dot notation for nested paths: 'usage.inputTokens'
+ */
+export declare function setMetric(ctx: KernelContext, key: string, value: number): void;
+/**
+ * Get a metric value.
+ * Supports dot notation for nested paths: 'usage.inputTokens'
+ */
+export declare function getMetric(ctx: KernelContext, key: string): number;
+/**
+ * Add usage metrics from a usage object.
+ * Converts nested structure to flat dot-notation keys.
+ *
+ * @example
+ * addUsageMetrics(ctx, { inputTokens: 100, outputTokens: 50 });
+ * // Sets: ctx.metrics['usage.inputTokens'] = 100
+ * //       ctx.metrics['usage.outputTokens'] = 50
+ */
+export declare function addUsageMetrics(ctx: KernelContext, usage: Record<string, number>): void;
+/**
+ * Get usage metrics as an object.
+ * Converts flat dot-notation keys back to nested structure.
+ *
+ * @example
+ * const usage = getUsageMetrics(ctx);
+ * // Returns: { inputTokens: 100, outputTokens: 50 }
+ */
+export declare function getUsageMetrics(ctx: KernelContext): Record<string, number>;
+//# sourceMappingURL=metrics-helpers.d.ts.map

package/dist/core/metrics-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-helpers.d.ts","sourceRoot":"","sources":["../../src/core/metrics-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C;;;GAGG;AAEH;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAK9E;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAK9E;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CASvF;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAc1E"}

package/dist/core/metrics-helpers.js

@@ -0,0 +1,72 @@
+import {} from "./context";
+/**
+ * Helper functions for working with metrics.
+ * Supports both flat and nested metric structures via dot notation.
+ */
+/**
+ * Add a metric value (accumulates).
+ * Supports dot notation for nested paths: 'usage.inputTokens'
+ */
+export function addMetric(ctx, key, value) {
+    if (!ctx.metrics) {
+        ctx.metrics = {};
+    }
+    ctx.metrics[key] = (ctx.metrics[key] || 0) + value;
+}
+/**
+ * Set a metric value (overwrites).
+ * Supports dot notation for nested paths: 'usage.inputTokens'
+ */
+export function setMetric(ctx, key, value) {
+    if (!ctx.metrics) {
+        ctx.metrics = {};
+    }
+    ctx.metrics[key] = value;
+}
+/**
+ * Get a metric value.
+ * Supports dot notation for nested paths: 'usage.inputTokens'
+ */
+export function getMetric(ctx, key) {
+    return ctx.metrics?.[key] || 0;
+}
+/**
+ * Add usage metrics from a usage object.
+ * Converts nested structure to flat dot-notation keys.
+ *
+ * @example
+ * addUsageMetrics(ctx, { inputTokens: 100, outputTokens: 50 });
+ * // Sets: ctx.metrics['usage.inputTokens'] = 100
+ * //       ctx.metrics['usage.outputTokens'] = 50
+ */
+export function addUsageMetrics(ctx, usage) {
+    if (!ctx.metrics) {
+        ctx.metrics = {};
+    }
+    for (const [key, value] of Object.entries(usage)) {
+        const metricKey = `usage.${key}`;
+        ctx.metrics[metricKey] = (ctx.metrics[metricKey] || 0) + value;
+    }
+}
+/**
+ * Get usage metrics as an object.
+ * Converts flat dot-notation keys back to nested structure.
+ *
+ * @example
+ * const usage = getUsageMetrics(ctx);
+ * // Returns: { inputTokens: 100, outputTokens: 50 }
+ */
+export function getUsageMetrics(ctx) {
+    if (!ctx.metrics) {
+        return {};
+    }
+    const usage = {};
+    for (const [key, value] of Object.entries(ctx.metrics)) {
+        if (key.startsWith("usage.")) {
+            const usageKey = key.substring(6); // Remove 'usage.' prefix
+            usage[usageKey] = value;
+        }
+    }
+    return usage;
+}
+//# sourceMappingURL=metrics-helpers.js.map

package/dist/core/metrics-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-helpers.js","sourceRoot":"","sources":["../../src/core/metrics-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,MAAM,WAAW,CAAC;AAE/C;;;GAGG;AAEH;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,GAAkB,EAAE,GAAW,EAAE,KAAa;IACtE,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QACjB,GAAG,CAAC,OAAO,GAAG,EAAE,CAAC;IACnB,CAAC;IACD,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC;AACrD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,GAAkB,EAAE,GAAW,EAAE,KAAa;IACtE,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QACjB,GAAG,CAAC,OAAO,GAAG,EAAE,CAAC;IACnB,CAAC;IACD,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAC3B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,GAAkB,EAAE,GAAW;IACvD,OAAO,GAAG,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,GAAkB,EAAE,KAA6B;IAC/E,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QACjB,GAAG,CAAC,OAAO,GAAG,EAAE,CAAC;IACnB,CAAC;IAED,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,MAAM,SAAS,GAAG,SAAS,GAAG,EAAE,CAAC;QACjC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC;IACjE,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,GAAkB;IAChD,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QACjB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QACvD,IAAI,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7B,MAAM,QAAQ,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,yBAAyB;YAC5D,KAAK,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/core/otel-provider.d.ts

@@ -0,0 +1,54 @@
+/**
+ * OpenTelemetry provider for Tentickle telemetry.
+ *
+ * Creates a TelemetryProvider that wraps the standard @opentelemetry/api,
+ * eliminating boilerplate for users who already have OTel configured.
+ *
+ * @module @tentickle/kernel/otel-provider
+ */
+import type { TelemetryProvider } from "./telemetry";
+export interface OTelProviderOptions {
+    /**
+     * Service name for traces and metrics.
+     * @default 'tentickle'
+     */
+    serviceName?: string;
+    /**
+     * Service version for traces and metrics.
+     */
+    serviceVersion?: string;
+    /**
+     * Custom tracer name (if different from serviceName).
+     */
+    tracerName?: string;
+    /**
+     * Custom meter name (if different from serviceName).
+     */
+    meterName?: string;
+}
+/**
+ * Create an OpenTelemetry provider from the standard @opentelemetry/api.
+ *
+ * Requires `@opentelemetry/api` to be installed and configured in your app.
+ * This function dynamically imports OTel to avoid hard dependencies.
+ *
+ * @example
+ * ```typescript
+ * import { Telemetry, createOTelProvider } from './core';
+ *
+ * // Basic usage - just works if OTel is configured
+ * Telemetry.setProvider(createOTelProvider());
+ *
+ * // With options
+ * Telemetry.setProvider(createOTelProvider({
+ *   serviceName: 'my-agent-service',
+ *   serviceVersion: '1.0.0',
+ * }));
+ * ```
+ *
+ * @param options - Configuration options
+ * @returns A TelemetryProvider that wraps OpenTelemetry
+ * @throws Error if @opentelemetry/api is not installed
+ */
+export declare function createOTelProvider(options?: OTelProviderOptions): TelemetryProvider;
+//# sourceMappingURL=otel-provider.d.ts.map

package/dist/core/otel-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel-provider.d.ts","sourceRoot":"","sources":["../../src/core/otel-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAA4B,MAAM,aAAa,CAAC;AAE/E,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,iBAAiB,CAsFvF"}

package/dist/core/otel-provider.js

@@ -0,0 +1,107 @@
+/**
+ * OpenTelemetry provider for Tentickle telemetry.
+ *
+ * Creates a TelemetryProvider that wraps the standard @opentelemetry/api,
+ * eliminating boilerplate for users who already have OTel configured.
+ *
+ * @module @tentickle/kernel/otel-provider
+ */
+/**
+ * Create an OpenTelemetry provider from the standard @opentelemetry/api.
+ *
+ * Requires `@opentelemetry/api` to be installed and configured in your app.
+ * This function dynamically imports OTel to avoid hard dependencies.
+ *
+ * @example
+ * ```typescript
+ * import { Telemetry, createOTelProvider } from './core';
+ *
+ * // Basic usage - just works if OTel is configured
+ * Telemetry.setProvider(createOTelProvider());
+ *
+ * // With options
+ * Telemetry.setProvider(createOTelProvider({
+ *   serviceName: 'my-agent-service',
+ *   serviceVersion: '1.0.0',
+ * }));
+ * ```
+ *
+ * @param options - Configuration options
+ * @returns A TelemetryProvider that wraps OpenTelemetry
+ * @throws Error if @opentelemetry/api is not installed
+ */
+export function createOTelProvider(options = {}) {
+    // Dynamic require - fails gracefully if not installed
+    let otel;
+    try {
+        otel = require("@opentelemetry/api");
+    }
+    catch {
+        throw new Error("createOTelProvider requires @opentelemetry/api to be installed. " +
+            "Run: pnpm add @opentelemetry/api");
+    }
+    const serviceName = options.serviceName ?? "tentickle";
+    const tracerName = options.tracerName ?? serviceName;
+    const meterName = options.meterName ?? serviceName;
+    const tracer = otel.trace.getTracer(tracerName, options.serviceVersion);
+    const meter = otel.metrics.getMeter(meterName, options.serviceVersion);
+    // Cache for counters and histograms to avoid recreating them
+    const counters = new Map();
+    const histograms = new Map();
+    return {
+        startTrace(name) {
+            const span = tracer.startSpan(name);
+            const ctx = otel.trace.setSpan(otel.context.active(), span);
+            otel.context.with(ctx, () => { });
+            return span.spanContext().traceId;
+        },
+        startSpan(name) {
+            const parentContext = otel.context.active();
+            const span = tracer.startSpan(name, undefined, parentContext);
+            return {
+                end: () => span.end(),
+                setAttribute: (key, value) => span.setAttribute(key, value),
+                recordError: (error) => {
+                    span.recordException(error);
+                    span.setStatus({ code: otel.SpanStatusCode.ERROR, message: error?.message });
+                },
+            };
+        },
+        recordError(error) {
+            const span = otel.trace.getActiveSpan();
+            if (span) {
+                span.recordException(error);
+                span.setStatus({ code: otel.SpanStatusCode.ERROR, message: error?.message });
+            }
+        },
+        endTrace() {
+            const span = otel.trace.getActiveSpan();
+            span?.end();
+        },
+        getCounter(name, unit, description) {
+            const key = `${name}:${unit}:${description}`;
+            let counter = counters.get(key);
+            if (!counter) {
+                const otelCounter = meter.createCounter(name, { unit, description });
+                counter = {
+                    add: (value, attributes) => otelCounter.add(value, attributes),
+                };
+                counters.set(key, counter);
+            }
+            return counter;
+        },
+        getHistogram(name, unit, description) {
+            const key = `${name}:${unit}:${description}`;
+            let histogram = histograms.get(key);
+            if (!histogram) {
+                const otelHistogram = meter.createHistogram(name, { unit, description });
+                histogram = {
+                    record: (value, attributes) => otelHistogram.record(value, attributes),
+                };
+                histograms.set(key, histogram);
+            }
+            return histogram;
+        },
+    };
+}
+//# sourceMappingURL=otel-provider.js.map

package/dist/core/otel-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel-provider.js","sourceRoot":"","sources":["../../src/core/otel-provider.ts"],"names":[],"mappings":"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"}