/**
 * Copyright 2025 The Artinet Project
 * SPDX-License-Identifier: Apache-2.0
 *
 * @fileoverview OpenTelemetry integration for Artinet SDK.
 *
 * Lightweight utilities for integrating user-configured OpenTelemetry
 * with the SDK's tracing and logging interfaces.
 *
 * @module @artinet/sdk/otel
 *
 * @example
 * ```typescript
 * import { trace } from '@opentelemetry/api';
 * import { configure } from '@artinet/sdk';
 * import { configureOtel, withSpan } from '@artinet/sdk/otel';
 *
 * // User initializes their own OpenTelemetry setup
 * // ... NodeSDK setup, exporters, etc. ...
 *
 * // Get tracer and configure SDK
 * const tracer = trace.getTracer('my-agent');
 * configure({
 *   tracer,
 *   logger: configureOtel({ level: 'debug' })
 * });
 * ```
 */
import { trace, context, SpanKind, SpanStatusCode, Tracer, Span, Context } from "@opentelemetry/api";
import type { ILogger } from "../config/observability.js";
/**
 * Options for configuring the OTel-aware logger.
 */
export interface OtelLoggerOptions {
    /**
     * Base logger to wrap (logs go here AND to spans).
     * If not provided, logs only go to spans.
     */
    baseLogger?: ILogger;
    /**
     * Log level.
     * @default 'info'
     */
    level?: "trace" | "verbose" | "debug" | "info" | "warn" | "error" | "silent";
}
/**
 * Create a logger that adds log events to the current span.
 *
 * This logger optionally wraps a base logger and adds all log messages
 * as span events in the current trace context.
 *
 * @param options - Logger options
 * @returns ILogger implementation
 *
 * @example
 * ```typescript
 * import { configure } from '@artinet/sdk';
 * import { configureOtel } from '@artinet/sdk/otel';
 * import { configurePino } from '@artinet/sdk/pino';
 * import pino from 'pino';
 *
 * // Logs go to both Pino AND span events
 * configure({
 *   logger: configureOtel({
 *     baseLogger: configurePino(pino()),
 *     level: 'debug'
 *   })
 * });
 * ```
 */
export declare function configureOtel(options?: OtelLoggerOptions): ILogger;
/**
 * Execute a function within a new span.
 *
 * @param tracer - User's tracer instance
 * @param name - Span name
 * @param fn - Function to execute
 * @param options - Optional span options
 * @returns Result of the function
 *
 * @example
 * ```typescript
 * import { trace } from '@opentelemetry/api';
 * import { withSpan } from '@artinet/sdk/otel';
 *
 * const tracer = trace.getTracer('my-agent');
 * const result = await withSpan(tracer, 'processTask', async (span) => {
 *   span.setAttribute('taskId', '123');
 *   return await doWork();
 * });
 * ```
 */
export declare function withSpan<T>(tracer: Tracer, name: string, fn: (span: Span) => Promise<T>, options?: {
    kind?: SpanKind;
    attributes?: Record<string, string | number | boolean>;
}): Promise<T>;
/**
 * Re-export OpenTelemetry API types for convenience.
 */
export { trace, context, SpanKind, SpanStatusCode, type Tracer, type Span, type Context, };
export default configureOtel;