import { Span } from '@opentelemetry/api';

/**
 * OpenTelemetry tracing setup for Shogo runtime services.
 *
 * Wires a `NodeSDK` with an OTLP HTTP trace exporter pointed at
 * `OTEL_EXPORTER_OTLP_ENDPOINT`, optionally authenticated via
 * `SIGNOZ_INGESTION_KEY`. In production / staging, spans are batched
 * before flush; in development a `SimpleSpanProcessor` flushes
 * eagerly so traces are visible immediately.
 *
 * Lifted into the SDK from `@shogo/shared-runtime` (was AGPL) under MIT.
 * The OpenTelemetry packages are optional `peerDependencies` of the SDK
 * — only consumers that actually call `initInstrumentation` need them
 * installed.
 *
 * @example
 *   import { initInstrumentation, traceOperation, shutdownInstrumentation }
 *     from '@shogo-ai/sdk/instrumentation'
 *
 *   initInstrumentation({ serviceName: 'my-api', serviceVersion: '1.0.0' })
 *
 *   await traceOperation('my-api', 'cold-start', { region: 'us-west' }, async (span) => {
 *     // ... boot work ...
 *     span.setAttribute('warm-pool-size', 4)
 *   })
 *
 *   process.on('SIGTERM', () => shutdownInstrumentation())
 */

interface InstrumentationConfig {
    serviceName: string;
    serviceVersion?: string;
}
declare function initInstrumentation(config: InstrumentationConfig): void;
declare function shutdownInstrumentation(): Promise<void>;
/**
 * Trace a function execution with automatic error recording and timing.
 * Use for key operations like cold starts, builds, tool calls, etc.
 */
declare function traceOperation<T>(tracerName: string, spanName: string, attributes: Record<string, string | number | boolean>, fn: (span: Span) => Promise<T>): Promise<T>;

export { type InstrumentationConfig, initInstrumentation, shutdownInstrumentation, traceOperation };