autotel/dist/instrumentation.d.ts

Write Once, Observe Anywhere

import { NodeSDK } from '@opentelemetry/sdk-node';

interface InstrumentationConfig {
    serviceName: string;
    serviceVersion?: string;
    deploymentEnvironment?: string;
    otlpEndpoint?: string;
    /** Headers for authentication (e.g., Grafana Cloud, Honeycomb) */
    headers?: string;
    /** Resource attributes as comma-separated key=value pairs */
    resourceAttributes?: string;
    /** Enable async resource detection for process/host info (default: false) */
    detectResources?: boolean;
    /**
     * Use selective instrumentation instead of full auto-instrumentation
     * **Default: true** (performance-first)
     *
     * When true, auto-instrumentation is disabled. You can manually add
     * specific instrumentations via the `instrumentations` field.
     * This reduces overhead from ~81% to near-zero based on Platformatic benchmarks.
     *
     * Set to false to enable full auto-instrumentation (not recommended for production).
     *
     * @see https://blogger.platformatic.dev/the-hidden-cost-of-context
     */
    selectiveInstrumentation?: boolean;
    /**
     * Custom instrumentations to use (only when selectiveInstrumentation is true)
     * @example
     * ```typescript
     * import { HttpInstrumentation } from '@opentelemetry/instrumentation-http'
     *
     * initInstrumentation({
     *   serviceName: 'api',
     *   selectiveInstrumentation: true,
     *   instrumentations: [new HttpInstrumentation()]
     * })
     * ```
     */
    instrumentations?: any[];
}
/**
 * Shutdown the OpenTelemetry SDK gracefully
 * Call this before process exit or during hot-reloads
 */
declare function shutdownInstrumentation(sdk?: NodeSDK): Promise<void>;
declare function initInstrumentation(config: InstrumentationConfig): Promise<NodeSDK>;

export { type InstrumentationConfig, initInstrumentation, shutdownInstrumentation };