/**
 * W3C trace-context propagation for the MCP via OTel SDK.
 *
 * Pattern matches Grafana's mcp-grafana (tools.go:230-243, 417-438):
 *   1. Extract `traceparent` from request._meta when the MCP host passes it
 *      so tool spans become children of the agent's trace. End-to-end one
 *      unified trace from the user prompt down through the tool call.
 *   2. Start a span per tool dispatch with semconv attributes
 *      (`gen_ai.tool.name`, `mcp.method.name`, plus our `gen_ai.system`).
 *   3. Defer span end + record errors via OTel semconv.
 *   4. Export via the operator's configured OTLP endpoint. We do not pin a
 *      target; we read standard OTel env vars
 *      (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, etc.) so the MCP
 *      becomes a node in whatever observability pipeline the customer
 *      already runs.
 *
 * Zero-config behavior: if `OTEL_EXPORTER_OTLP_ENDPOINT` is not set, this
 * module initializes nothing. Tool dispatches still call into the
 * propagator helpers; they short-circuit to no-ops. No performance cost.
 *
 * Why a separate file: keeps the OTel SDK init out of the hot path of
 * src/index.ts. The SDK pulls in ~3 MB of code that we want lazy-loaded
 * only when actually exporting.
 */
import { type Span } from '@opentelemetry/api';
/** Re-export the OTel Span type under a stable name so callers don't depend on the SDK package path. */
export type OtelSpan = Span;
/**
 * Initialize the OTel SDK if the operator has configured an OTLP endpoint.
 * Idempotent. Safe to call multiple times. Returns true when OTel is
 * active for the rest of the process.
 *
 * Reads (all standard OTel env vars; no Log10x-specific config):
 *   OTEL_EXPORTER_OTLP_ENDPOINT  — required to enable
 *   OTEL_SERVICE_NAME            — defaults to "log10x-mcp"
 *   OTEL_RESOURCE_ATTRIBUTES     — free-form; honored by the SDK natively
 */
export declare function initOtel(): Promise<boolean>;
/**
 * Start a span for a tool call. `extra` is the SDK's RequestHandlerExtra,
 * carrying optional `_meta.traceparent` from the caller.
 *
 * Returns the span (or null if OTel isn't initialized). The caller must
 * call `endToolSpan(span, ...)` once the tool finishes.
 *
 * When _meta.traceparent is present, we extract the parent context and the
 * new span becomes a child of the caller's trace — same end-to-end trace
 * that started at the user prompt.
 */
export declare function startToolSpan(toolName: string, extra: {
    _meta?: Record<string, unknown>;
    sessionId?: string;
    requestId?: string | number;
} | undefined): Span | null;
/**
 * Close a tool span. `outcome` lets us record the standard outcome
 * attributes per OTel semconv. On error: also record the exception and
 * set status=ERROR so the trace UI flags it.
 */
export declare function endToolSpan(span: Span | null, outcome: {
    ok: true;
    durationMs: number;
} | {
    ok: false;
    durationMs: number;
    error: unknown;
}): void;
export declare function isOtelInitialized(): boolean;