import { OtelTraceContext } from "@gala-chain/api";
import { Attributes, Span } from "@opentelemetry/api";
/**
 * Starts the OTEL tracer when `OTEL_EXPORTER_OTLP_ENDPOINT` is set.
 * Config from standard OTEL_* env vars:
 *   OTEL_EXPORTER_OTLP_ENDPOINT
 *   OTEL_EXPORTER_OTLP_PROTOCOL
 *   OTEL_EXPORTER_OTLP_HEADERS
 *   OTEL_SERVICE_NAME
 *   OTEL_SERVICE_VERSION
 */
export declare function initTracing(): void;
export declare function isTracingEnabled(): boolean;
/**
 * Starts a SERVER span for a chaincode method, optionally as a child of dto.trace.
 */
export declare function startTransactionSpan(name: string, parent: OtelTraceContext | undefined, attributes?: Attributes): Span | undefined;
export declare function recordTransactionSpanError(span: Span | undefined, err: unknown): void;
/**
 * Runs `fn` with `span` as the active OTEL context so child spans nest under it.
 * Uses ROOT_CONTEXT as the base so a stale ambient span cannot become the parent.
 */
export declare function runInSpanContext<T>(span: Span | undefined, fn: () => Promise<T>): Promise<T>;
/**
 * Starts an INTERNAL child span under the active context, or `fallbackParent` when
 * no span is active (common after Fabric lifecycle boundaries).
 * No-op when tracing is disabled.
 */
export declare function startChildSpan(name: string, attributes?: Attributes, fallbackParent?: Span): Span | undefined;
export declare function endChildSpan(span: Span | undefined, err?: unknown): void;
/**
 * Times an async operation as an INTERNAL child span. Never swallows errors from `fn`.
 * Pass `fallbackParent` (EVALUATE/SERVER) so parenting survives lost ALS context.
 * Export is not awaited — BatchSpanProcessor sends in the background.
 */
export declare function withSpan<T>(name: string, attributes: Attributes, fn: (span: Span | undefined) => Promise<T>, fallbackParent?: Span): Promise<T>;
/**
 * Times a sync operation as an INTERNAL child span. Never swallows errors.
 */
export declare function withSpanSync<T>(name: string, attributes: Attributes, fn: (span: Span | undefined) => T, fallbackParent?: Span): T;
/** Truncate long attribute values for OTEL. */
export declare function truncateOtelAttr(value: string, maxLen?: number): string;
/**
 * Format a Fabric state key for span attributes: composite-key `\u0000` separators
 * become `/` so keys are readable in trace UIs.
 */
export declare function formatOtelStateKey(key: string, maxLen?: number): string;
/**
 * Ends the SERVER span. Export is left to BatchSpanProcessor (background).
 * Do not forceFlush here — a down OTEL endpoint must not block the transaction.
 * Pass `failed` when the transaction already recorded an error status.
 */
export declare function endTransactionSpan(span: Span | undefined, failed?: boolean): Promise<void>;
/**
 * Verifies the OTLP endpoint is reachable and that a probe span can be exported.
 * Intended for chaincode startup and local `otel:verify` runs. Never throws.
 */
export declare function verifyOtelConnection(): Promise<boolean>;
/** @internal test helper */
export declare function _resetTracingForTests(): Promise<void>;
//# sourceMappingURL=tracing.d.ts.map