import { Span as ApiSpan } from '@opentelemetry/api';
import { Span as OTelSpan } from '@opentelemetry/sdk-trace-node';
import { SpanType } from './constants';
import { LiveSpan } from './entities/span';
export interface SpanOptions {
    /**
     * The name of the span.
     */
    name: string;
    /**
     * The type of the span, e.g., `LLM`, `TOOL`, `RETRIEVER`, etc.
     */
    spanType?: SpanType;
    /**
     * The inputs of the span.
     */
    inputs?: any;
    /**
     * The attributes of the span.
     */
    attributes?: Record<string, any>;
    /**
     * The start time of the span in nanoseconds. If not provided, the current time will be used.
     */
    startTimeNs?: number;
    /**
     * The parent span object. If not provided, the span is considered a root span.
     */
    parent?: LiveSpan;
}
/**
 * Options for tracing a function
 */
export interface TraceOptions extends Omit<SpanOptions, 'parent' | 'startTimeNs' | 'inputs' | 'name'> {
    /**
     * The name of the span.
     */
    name?: string;
}
/**
 * Start a new span with the given name and span type.
 *
 * This function does NOT attach the created span to the current context. To create
 * nested spans, you need to set the parent span explicitly in the `parent` field.
 * The span must be ended by calling `end` method on the returned Span object.
 *
 * @param options Optional span options (name, spanType, inputs, attributes, startTimeNs, parent)
 * @returns The created span object.
 *
 * @example
 * ```typescript
 * const span = startSpan({
 *   name: 'my_span',
 *   spanType: 'LLM',
 *   inputs: {
 *     prompt: 'Hello, world!'
 *   }
 * });
 *
 * // Do something
 *
 * // End the span
 * span.end({
 *   status: 'OK',
 *   outputs: {
 *     response: 'Hello, world!'
 *   }
 * });
 * ```
 *
 */
export declare function startSpan(options: SpanOptions): LiveSpan;
/**
 * Execute a function within a span context. The span is automatically started before
 * the function executes and ended after it completes (or throws an error).
 *
 * This function uses OpenTelemetry's active span context to automatically manage
 * parent-child relationships between spans.
 *
 * This function supports two usage patterns:
 * 1. Inline: `withSpan((span) => { ... })` - span properties set within the callback
 * 2. Options: `withSpan((span) => { ... }, { name: 'test', ... })` - span properties set via options object
 *
 * @param callback The callback function to execute within the span context
 * @param options Optional span options (name, spanType, inputs, attributes, startTimeNs)
 * @returns The result of the callback function
 */
export declare function withSpan<T>(callback: (span: LiveSpan) => T | Promise<T>, options?: Omit<SpanOptions, 'parent'>): T | Promise<T>;
/**
 * Helper function to create and register an MLflow span from an OpenTelemetry span
 * @param otelSpan The OpenTelemetry span
 * @param spanType The MLflow span type
 * @param inputs Optional inputs to set on the span
 * @param attributes Optional attributes to set on the span
 * @returns The created and registered MLflow LiveSpan
 */
export declare function createAndRegisterMlflowSpan(otelSpan: OTelSpan | ApiSpan, spanType?: SpanType, inputs?: any, attributes?: Record<string, any>): LiveSpan;
/**
 * Create a traced version of a function or decorator for tracing class methods.
 *
 * When used as a function wrapper, the span will automatically capture:
 * - The function inputs
 * - The function outputs
 * - The function name as the span name
 * - The function execution time
 * - Any exception thrown by the function
 *
 * When used as a decorator, it preserves the `this` context for class methods.
 *
 * Note: Typescript decorator is still in experimental stage.
 *
 * @param func The function to trace (when used as function wrapper)
 * @param options Optional trace options including name, spanType, and attributes
 * @returns The traced function or method decorator
 *
 * @example
 * // Function wrapper with no options
 * const tracedFunc = trace(myFunc);
 *
 * @example
 * // Function wrapper with options
 * const tracedFunc = trace(myFunc, { name: 'custom_span_name', spanType: 'LLM' });
 *
 * @example
 * // Decorator with no options
 * class MyService {
 *   @trace()
 *   async processData(data: any) {
 *     return processedData;
 *   }
 * }
 *
 * @example
 * // Decorator with options
 * class MyService {
 *   @trace({ name: 'custom_span', spanType: SpanType.LLM })
 *   async generateText(prompt: string) {
 *     return generatedText;
 *   }
 * }
 */
export declare function trace(options?: TraceOptions): any;
export declare function trace<T extends (...args: any[]) => any>(func: T, options?: TraceOptions): T;
/**
 * Get the last active trace ID.
 * @returns The last active trace ID.
 */
export declare function getLastActiveTraceId(): string | undefined;
/**
 * Get the current active span in the global context.
 *
 * This only works when the span is created with fluent APIs like `@trace` or
 * `withSpan`. If a span is created with the `startSpan` API, it won't be
 * attached to the global context so this function will not return it.
 *
 * @returns The current active span if exists, otherwise null.
 *
 * @example
 * ```typescript
 * const tracedFunc = trace(() => {
 *   const span = getCurrentActiveSpan();
 *   span?.setAttribute("key", "value");
 *   return 0;
 * });
 *
 * tracedFunc();
 * ```
 */
export declare function getCurrentActiveSpan(): LiveSpan | null;
/**
 * Options for updating the current trace
 */
export interface UpdateCurrentTraceOptions {
    /**
     * A dictionary of tags to update the trace with. Tags are designed for mutable values
     * that can be updated after the trace is created via MLflow UI or API.
     */
    tags?: Record<string, string>;
    /**
     * A dictionary of metadata to update the trace with. Metadata cannot be updated
     * once the trace is logged. It is suitable for recording immutable values like the
     * git hash of the application version that produced the trace.
     */
    metadata?: Record<string, string>;
    /**
     * Client supplied request ID to associate with the trace. This is useful for linking
     * the trace back to a specific request in your application or external system.
     */
    clientRequestId?: string;
    /**
     * A preview of the request to be shown in the Trace list view in the UI.
     * By default, MLflow will truncate the trace request naively by limiting the length.
     * This parameter allows you to specify a custom preview string.
     */
    requestPreview?: string;
    /**
     * A preview of the response to be shown in the Trace list view in the UI.
     * By default, MLflow will truncate the trace response naively by limiting the length.
     * This parameter allows you to specify a custom preview string.
     */
    responsePreview?: string;
}
/**
 * Update the current active trace with the given options.
 *
 * You can use this function either within a function decorated with `@trace` or
 * within the scope of the `withSpan` context. If there is no active trace found,
 * this function will log a warning and return.
 *
 * @param options Options for updating the trace
 *
 * @example
 * Using within a function decorated with `@trace`:
 * ```typescript
 * const myFunc = trace((x: number) => {
 *   updateCurrentTrace({ tags: { fruit: "apple" }, clientRequestId: "req-12345" });
 *   return x + 1;
 * });
 * ```
 *
 * @example
 * Using within the `withSpan` context:
 * ```typescript
 * withSpan((span) => {
 *   updateCurrentTrace({ tags: { fruit: "apple" }, clientRequestId: "req-12345" });
 * }, { name: "span" });
 * ```
 *
 * @example
 * Updating source information of the trace:
 * ```typescript
 * updateCurrentTrace({
 *   metadata: {
 *     "mlflow.trace.session": "session-4f855da00427",
 *     "mlflow.trace.user": "user-id-cc156f29bcfb",
 *     "mlflow.source.name": "inference.ts",
 *     "mlflow.source.git.commit": "1234567890",
 *     "mlflow.source.git.repoURL": "https://github.com/mlflow/mlflow"
 *   }
 * });
 * ```
 */
export declare function updateCurrentTrace({ tags, metadata, clientRequestId, requestPreview, responsePreview, }: UpdateCurrentTraceOptions): void;