autotel-plugins 0.19.25 → 0.19.27

package/dist/kafka.d.cts

@@ -1,5 +1,22 @@
 import { SpanLink, Span, Context, SpanContext } from 'autotel';
-export { C as CORRELATION_ID_HEADER, t as SEMATTRS_LINKED_TRACE_ID_COUNT, u as SEMATTRS_LINKED_TRACE_ID_HASH, v as SEMATTRS_MESSAGING_BATCH_MESSAGE_COUNT, x as SEMATTRS_MESSAGING_DESTINATION_NAME, y as SEMATTRS_MESSAGING_KAFKA_BATCH_FIRST_OFFSET, z as SEMATTRS_MESSAGING_KAFKA_BATCH_LAST_OFFSET, A as SEMATTRS_MESSAGING_KAFKA_BATCH_MESSAGES_FAILED, B as SEMATTRS_MESSAGING_KAFKA_BATCH_MESSAGES_PROCESSED, D as SEMATTRS_MESSAGING_KAFKA_BATCH_PROCESSING_TIME_MS, E as SEMATTRS_MESSAGING_KAFKA_CONSUMER_GROUP, F as SEMATTRS_MESSAGING_KAFKA_MESSAGE_KEY, G as SEMATTRS_MESSAGING_KAFKA_OFFSET, H as SEMATTRS_MESSAGING_KAFKA_PARTITION, K as SEMATTRS_MESSAGING_OPERATION, Q as SEMATTRS_MESSAGING_SYSTEM } from './constants-DKKe2D25.cjs';
+export {
+  C as CORRELATION_ID_HEADER,
+  t as SEMATTRS_LINKED_TRACE_ID_COUNT,
+  u as SEMATTRS_LINKED_TRACE_ID_HASH,
+  v as SEMATTRS_MESSAGING_BATCH_MESSAGE_COUNT,
+  x as SEMATTRS_MESSAGING_DESTINATION_NAME,
+  y as SEMATTRS_MESSAGING_KAFKA_BATCH_FIRST_OFFSET,
+  z as SEMATTRS_MESSAGING_KAFKA_BATCH_LAST_OFFSET,
+  A as SEMATTRS_MESSAGING_KAFKA_BATCH_MESSAGES_FAILED,
+  B as SEMATTRS_MESSAGING_KAFKA_BATCH_MESSAGES_PROCESSED,
+  D as SEMATTRS_MESSAGING_KAFKA_BATCH_PROCESSING_TIME_MS,
+  E as SEMATTRS_MESSAGING_KAFKA_CONSUMER_GROUP,
+  F as SEMATTRS_MESSAGING_KAFKA_MESSAGE_KEY,
+  G as SEMATTRS_MESSAGING_KAFKA_OFFSET,
+  H as SEMATTRS_MESSAGING_KAFKA_PARTITION,
+  K as SEMATTRS_MESSAGING_OPERATION,
+  Q as SEMATTRS_MESSAGING_SYSTEM,
+} from './constants-DKKe2D25.cjs';
 
 /**
  * Kafka plugin types - Processing spans, batch lineage, and correlation
@@ -13,7 +30,10 @@ export { C as CORRELATION_ID_HEADER, t as SEMATTRS_LINKED_TRACE_ID_COUNT, u as S
  * Values can be string, Buffer, or undefined.
  * Also accepts Map for compatibility with @platformatic/kafka and other clients.
  */
-type RawKafkaHeaders = Record<string, string | Buffer | undefined> | Map<string, string | Buffer | undefined> | undefined;
+type RawKafkaHeaders =
+  | Record<string, string | Buffer | undefined>
+  | Map<string, string | Buffer | undefined>
+  | undefined;
 /**
  * Context mode for processing spans.
  *
@@ -31,102 +51,102 @@ type ContextMode = 'inherit' | 'link' | 'none';
  * Descriptor for creating a processing span.
  */
 interface ProcessingDescriptor {
-    /**
-     * Name for the processing span (e.g., "order.process")
-     */
-    name: string;
-    /**
-     * Kafka message headers for context extraction.
-     * Use normalizeHeaders() to convert from RawKafkaHeaders.
-     */
-    headers: RawKafkaHeaders;
-    /**
-     * Context mode for relating to extracted remote context.
-     * @default 'inherit'
-     */
-    contextMode?: ContextMode;
-    /**
-     * Additional span links to include.
-     */
-    links?: SpanLink[];
-    /**
-     * Kafka topic name. Sets `messaging.destination.name` attribute.
-     */
-    topic?: string;
-    /**
-     * Consumer group name. Sets `messaging.kafka.consumer.group` attribute.
-     */
-    consumerGroup?: string;
-    /**
-     * Kafka partition number. Sets `messaging.kafka.partition` attribute.
-     */
-    partition?: number;
-    /**
-     * Message offset. Sets `messaging.kafka.offset` attribute.
-     */
-    offset?: string;
-    /**
-     * Message key. Sets `messaging.kafka.message.key` attribute.
-     */
-    key?: string;
+  /**
+   * Name for the processing span (e.g., "order.process")
+   */
+  name: string;
+  /**
+   * Kafka message headers for context extraction.
+   * Use normalizeHeaders() to convert from RawKafkaHeaders.
+   */
+  headers: RawKafkaHeaders;
+  /**
+   * Context mode for relating to extracted remote context.
+   * @default 'inherit'
+   */
+  contextMode?: ContextMode;
+  /**
+   * Additional span links to include.
+   */
+  links?: SpanLink[];
+  /**
+   * Kafka topic name. Sets `messaging.destination.name` attribute.
+   */
+  topic?: string;
+  /**
+   * Consumer group name. Sets `messaging.kafka.consumer.group` attribute.
+   */
+  consumerGroup?: string;
+  /**
+   * Kafka partition number. Sets `messaging.kafka.partition` attribute.
+   */
+  partition?: number;
+  /**
+   * Message offset. Sets `messaging.kafka.offset` attribute.
+   */
+  offset?: string;
+  /**
+   * Message key. Sets `messaging.kafka.message.key` attribute.
+   */
+  key?: string;
 }
 /**
  * Descriptor for creating a producer span.
  */
 interface ProducerDescriptor {
-    /**
-     * Name for the producer span (e.g., "order.publish")
-     */
-    name: string;
-    /**
-     * Kafka topic name. Sets `messaging.destination.name` attribute.
-     */
-    topic: string;
-    /**
-     * Message key. Sets `messaging.kafka.message.key` attribute.
-     */
-    messageKey?: string;
-    /**
-     * Messaging system. Defaults to 'kafka'.
-     */
-    system?: string;
+  /**
+   * Name for the producer span (e.g., "order.publish")
+   */
+  name: string;
+  /**
+   * Kafka topic name. Sets `messaging.destination.name` attribute.
+   */
+  topic: string;
+  /**
+   * Message key. Sets `messaging.kafka.message.key` attribute.
+   */
+  messageKey?: string;
+  /**
+   * Messaging system. Defaults to 'kafka'.
+   */
+  system?: string;
 }
 /**
  * Options for batch lineage extraction.
  */
 interface BatchLineageOptions {
-    /**
-     * Include raw trace IDs in the result.
-     * @default false (privacy consideration)
-     */
-    includeTraceIds?: boolean;
-    /**
-     * Maximum number of links to include.
-     * @default 128
-     */
-    maxLinks?: number;
+  /**
+   * Include raw trace IDs in the result.
+   * @default false (privacy consideration)
+   */
+  includeTraceIds?: boolean;
+  /**
+   * Maximum number of links to include.
+   * @default 128
+   */
+  maxLinks?: number;
 }
 /**
  * Result of batch lineage extraction.
  */
 interface BatchLineageResult {
-    /**
-     * Count of unique, linked trace IDs.
-     */
-    linked_trace_id_count: number;
-    /**
-     * SHA-256 hash of sorted trace IDs (16 hex chars, 64-bit).
-     * Useful for comparing batches without exposing individual trace IDs.
-     */
-    linked_trace_id_hash: string;
-    /**
-     * Raw trace IDs, only if includeTraceIds was true.
-     */
-    trace_ids?: string[];
-    /**
-     * Valid SpanLinks from extracted contexts (capped at maxLinks).
-     */
-    links: SpanLink[];
+  /**
+   * Count of unique, linked trace IDs.
+   */
+  linked_trace_id_count: number;
+  /**
+   * SHA-256 hash of sorted trace IDs (16 hex chars, 64-bit).
+   * Useful for comparing batches without exposing individual trace IDs.
+   */
+  linked_trace_id_hash: string;
+  /**
+   * Raw trace IDs, only if includeTraceIds was true.
+   */
+  trace_ids?: string[];
+  /**
+   * Valid SpanLinks from extracted contexts (capped at maxLinks).
+   */
+  links: SpanLink[];
 }
 /**
  * Options for injecting trace headers.
@@ -135,15 +155,15 @@ interface BatchLineageResult {
  * If W3CBaggagePropagator is registered, baggage will be injected automatically.
  */
 interface InjectOptions {
-    /**
-     * Explicit correlation ID to use. If not provided, derives from current context.
-     */
-    correlationId?: string;
-    /**
-     * Whether to include x-correlation-id header.
-     * @default true
-     */
-    includeCorrelationIdHeader?: boolean;
+  /**
+   * Explicit correlation ID to use. If not provided, derives from current context.
+   */
+  correlationId?: string;
+  /**
+   * Whether to include x-correlation-id header.
+   * @default true
+   */
+  includeCorrelationIdHeader?: boolean;
 }
 /**
  * Type for the processing span callback function.
@@ -157,7 +177,7 @@ type ProducerSpanCallback<T> = (span: Span) => Promise<T>;
  * Item with optional headers for batch lineage extraction.
  */
 interface BatchItem {
-    headers?: RawKafkaHeaders;
+  headers?: RawKafkaHeaders;
 }
 
 /**
@@ -201,7 +221,9 @@ interface BatchItem {
  * // { traceparent: '00-abc...', 'content-type': 'application/json' }
  * ```
  */
-declare function normalizeHeaders(headers?: RawKafkaHeaders): Record<string, string>;
+declare function normalizeHeaders(
+  headers?: RawKafkaHeaders,
+): Record<string, string>;
 /**
  * Extract trace context from normalized headers using OTel propagators.
  *
@@ -280,7 +302,9 @@ declare function deriveCorrelationId(): string;
  * }
  * ```
  */
-declare function extractCorrelationId(headers: Record<string, string>): string | undefined;
+declare function extractCorrelationId(
+  headers: Record<string, string>,
+): string | undefined;
 /**
  * Inject trace headers into outgoing message headers.
  *
@@ -313,7 +337,10 @@ declare function extractCorrelationId(headers: Record<string, string>): string |
  * });
  * ```
  */
-declare function injectTraceHeaders(base?: Record<string, string>, options?: InjectOptions): Record<string, string>;
+declare function injectTraceHeaders(
+  base?: Record<string, string>,
+  options?: InjectOptions,
+): Record<string, string>;
 
 /**
  * Processing span wrapper for Kafka message handling.
@@ -391,7 +418,10 @@ declare function injectTraceHeaders(base?: Record<string, string>, options?: Inj
  * });
  * ```
  */
-declare function withProcessingSpan<T>(descriptor: ProcessingDescriptor, fn: ProcessingSpanCallback<T>): Promise<T>;
+declare function withProcessingSpan<T>(
+  descriptor: ProcessingDescriptor,
+  fn: ProcessingSpanCallback<T>,
+): Promise<T>;
 
 /**
  * Producer span wrapper for Kafka message publishing.
@@ -442,7 +472,10 @@ declare function withProcessingSpan<T>(descriptor: ProcessingDescriptor, fn: Pro
  * });
  * ```
  */
-declare function withProducerSpan<T>(descriptor: ProducerDescriptor, fn: ProducerSpanCallback<T>): Promise<T>;
+declare function withProducerSpan<T>(
+  descriptor: ProducerDescriptor,
+  fn: ProducerSpanCallback<T>,
+): Promise<T>;
 
 /**
  * Batch lineage utilities for fan-in trace correlation.
@@ -498,7 +531,10 @@ declare function withProducerSpan<T>(descriptor: ProducerDescriptor, fn: Produce
  * console.log('Processing batch from traces:', lineage.trace_ids);
  * ```
  */
-declare function extractBatchLineage(items: BatchItem[], options?: BatchLineageOptions): BatchLineageResult;
+declare function extractBatchLineage(
+  items: BatchItem[],
+  options?: BatchLineageOptions,
+): BatchLineageResult;
 /**
  * Async version of extractBatchLineage that uses crypto.subtle for hashing.
  *
@@ -513,7 +549,10 @@ declare function extractBatchLineage(items: BatchItem[], options?: BatchLineageO
  * const lineage = await extractBatchLineageAsync(batch, { maxLinks: 50 });
  * ```
  */
-declare function extractBatchLineageAsync(items: BatchItem[], options?: BatchLineageOptions): Promise<BatchLineageResult>;
+declare function extractBatchLineageAsync(
+  items: BatchItem[],
+  options?: BatchLineageOptions,
+): Promise<BatchLineageResult>;
 
 /**
  * Batch consumer wrapper for KafkaJS batch processing.
@@ -543,26 +582,28 @@ declare function extractBatchLineageAsync(items: BatchItem[], options?: BatchLin
  * Matches the exact signature from KafkaJS.
  */
 interface EachBatchPayload {
-    batch: {
-        topic: string;
-        partition: number;
-        messages: Array<{
-            offset: string;
-            key?: Buffer | null;
-            value: Buffer | null;
-            headers?: Record<string, Buffer | string | undefined>;
-        }>;
-        firstOffset(): string | null;
-        lastOffset(): string;
-        highWatermark: string;
-    };
-    resolveOffset(offset: string): void;
-    heartbeat(): Promise<void>;
-    commitOffsetsIfNecessary(offsets?: Record<string, Record<number, string>>): Promise<void>;
-    uncommittedOffsets(): Record<string, Record<number, string>>;
-    isRunning(): boolean;
-    isStale(): boolean;
-    pause(): () => void;
+  batch: {
+    topic: string;
+    partition: number;
+    messages: Array<{
+      offset: string;
+      key?: Buffer | null;
+      value: Buffer | null;
+      headers?: Record<string, Buffer | string | undefined>;
+    }>;
+    firstOffset(): string | null;
+    lastOffset(): string;
+    highWatermark: string;
+  };
+  resolveOffset(offset: string): void;
+  heartbeat(): Promise<void>;
+  commitOffsetsIfNecessary(
+    offsets?: Record<string, Record<number, string>>,
+  ): Promise<void>;
+  uncommittedOffsets(): Record<string, Record<number, string>>;
+  isRunning(): boolean;
+  isStale(): boolean;
+  pause(): () => void;
 }
 /**
  * Batch consumer handler type.
@@ -572,14 +613,14 @@ type EachBatchHandler = (payload: EachBatchPayload) => Promise<void>;
  * Progress metrics during batch processing.
  */
 interface BatchProgressMetrics {
-    /** Number of messages processed so far */
-    processed: number;
-    /** Number of messages that failed processing */
-    failed: number;
-    /** Number of messages skipped */
-    skipped: number;
-    /** Batch processing time in milliseconds */
-    batchProcessingTimeMs: number;
+  /** Number of messages processed so far */
+  processed: number;
+  /** Number of messages that failed processing */
+  failed: number;
+  /** Number of messages skipped */
+  skipped: number;
+  /** Batch processing time in milliseconds */
+  batchProcessingTimeMs: number;
 }
 /**
  * Per-message span mode.
@@ -592,23 +633,23 @@ type PerMessageSpanMode = 'all' | 'errors' | 'none';
  * Configuration for batch consumer wrapper.
  */
 interface BatchConsumerConfig {
-    /**
-     * Name for the batch processing span (e.g., "orders.batch")
-     */
-    name: string;
-    /**
-     * Consumer group name. Sets `messaging.kafka.consumer.group` attribute.
-     */
-    consumerGroup?: string;
-    /**
-     * Per-message span creation mode. When 'all', message spans follow extracted trace context from headers when valid (trace continuation), otherwise parent to the batch span; all per-message spans are ended on batch completion.
-     * @default 'none' (to avoid cardinality explosion)
-     */
-    perMessageSpans?: PerMessageSpanMode;
-    /**
-     * Optional callback for real-time visibility into batch processing.
-     */
-    onProgress?: (metrics: BatchProgressMetrics) => void;
+  /**
+   * Name for the batch processing span (e.g., "orders.batch")
+   */
+  name: string;
+  /**
+   * Consumer group name. Sets `messaging.kafka.consumer.group` attribute.
+   */
+  consumerGroup?: string;
+  /**
+   * Per-message span creation mode. When 'all', message spans follow extracted trace context from headers when valid (trace continuation), otherwise parent to the batch span; all per-message spans are ended on batch completion.
+   * @default 'none' (to avoid cardinality explosion)
+   */
+  perMessageSpans?: PerMessageSpanMode;
+  /**
+   * Optional callback for real-time visibility into batch processing.
+   */
+  onProgress?: (metrics: BatchProgressMetrics) => void;
 }
 /**
  * Wrap a KafkaJS eachBatch handler with observability.
@@ -644,16 +685,25 @@ interface BatchConsumerConfig {
  * });
  * ```
  */
-declare function withBatchConsumer(config: BatchConsumerConfig, handler: EachBatchHandler): EachBatchHandler;
+declare function withBatchConsumer(
+  config: BatchConsumerConfig,
+  handler: EachBatchHandler,
+): EachBatchHandler;
 /**
  * Helper to create a per-message span for error cases.
  * Call this in your error handler when using perMessageSpans: 'errors'.
  */
-declare function createMessageErrorSpan(name: string, message: {
+declare function createMessageErrorSpan(
+  name: string,
+  message: {
     offset: string;
     key?: Buffer | null;
     headers?: Record<string, Buffer | string | undefined>;
-}, error: Error, topic: string, partition: number): void;
+  },
+  error: Error,
+  topic: string,
+  partition: number,
+): void;
 
 /**
  * Stream processor for Kafka pipeline patterns.
@@ -694,72 +744,76 @@ declare function createMessageErrorSpan(name: string, message: {
  * Input message type for stream processing.
  */
 interface StreamMessage {
-    headers?: RawKafkaHeaders;
-    key?: Buffer | null;
-    value: Buffer | null;
-    offset?: string;
+  headers?: RawKafkaHeaders;
+  key?: Buffer | null;
+  value: Buffer | null;
+  offset?: string;
 }
 /**
  * Configuration for stream processor.
  */
 interface StreamProcessorConfig {
-    /**
-     * Name for the processor (e.g., "order-enrichment")
-     */
-    name: string;
-    /**
-     * Expected stage names (for documentation/validation).
-     * Stages can be run in any order.
-     */
-    stages?: string[];
+  /**
+   * Name for the processor (e.g., "order-enrichment")
+   */
+  name: string;
+  /**
+   * Expected stage names (for documentation/validation).
+   * Stages can be run in any order.
+   */
+  stages?: string[];
 }
 /**
  * Options for producing output messages.
  */
 interface ProduceOptions {
-    /**
-     * Create a SpanLink to the input message's extracted context.
-     * Useful for lineage tracking.
-     * @default false
-     */
-    linkToInput?: boolean;
-    /**
-     * Additional headers to include (merged with trace headers).
-     */
-    headers?: Record<string, string>;
+  /**
+   * Create a SpanLink to the input message's extracted context.
+   * Useful for lineage tracking.
+   * @default false
+   */
+  linkToInput?: boolean;
+  /**
+   * Additional headers to include (merged with trace headers).
+   */
+  headers?: Record<string, string>;
 }
 /**
  * Context passed to the processor callback.
  */
 interface ProcessorContext {
-    /**
-     * The processor-level span.
-     */
-    span: Span;
-    /**
-     * Execute a named stage with automatic span creation.
-     *
-     * @param stageName - Name of the stage (e.g., "validate", "enrich")
-     * @param fn - Stage function to execute
-     * @returns Result of the stage function
-     */
-    stage<T>(stageName: string, fn: () => T | Promise<T>): Promise<T>;
-    /**
-     * Produce a message with proper span creation and header injection.
-     *
-     * The returned headers should be used when actually sending the message.
-     *
-     * @param topic - Destination topic
-     * @param payload - Message payload
-     * @param options - Produce options
-     * @returns Headers to use when sending (includes trace context)
-     */
-    produce(topic: string, payload: unknown, options?: ProduceOptions): Promise<Record<string, string>>;
-    /**
-     * Get the extracted context from the input message.
-     * Useful for creating manual links or context propagation.
-     */
-    inputContext: SpanContext | undefined;
+  /**
+   * The processor-level span.
+   */
+  span: Span;
+  /**
+   * Execute a named stage with automatic span creation.
+   *
+   * @param stageName - Name of the stage (e.g., "validate", "enrich")
+   * @param fn - Stage function to execute
+   * @returns Result of the stage function
+   */
+  stage<T>(stageName: string, fn: () => T | Promise<T>): Promise<T>;
+  /**
+   * Produce a message with proper span creation and header injection.
+   *
+   * The returned headers should be used when actually sending the message.
+   *
+   * @param topic - Destination topic
+   * @param payload - Message payload
+   * @param options - Produce options
+   * @returns Headers to use when sending (includes trace context)
+   */
+  produce(
+    topic: string,
+    payload: unknown,
+    options?: ProduceOptions,
+  ): Promise<Record<string, string>>;
+  /**
+   * Get the extracted context from the input message.
+   * Useful for creating manual links or context propagation.
+   */
+  inputContext: SpanContext | undefined;
 }
 /**
  * Processor callback type.
@@ -769,14 +823,14 @@ type ProcessorCallback<T> = (ctx: ProcessorContext) => Promise<T>;
  * Stream processor instance.
  */
 interface StreamProcessor {
-    /**
-     * Run the processor on an input message.
-     *
-     * @param message - Input Kafka message
-     * @param callback - Processor callback with stage/produce helpers
-     * @returns Result of the processor callback
-     */
-    run<T>(message: StreamMessage, callback: ProcessorCallback<T>): Promise<T>;
+  /**
+   * Run the processor on an input message.
+   *
+   * @param message - Input Kafka message
+   * @param callback - Processor callback with stage/produce helpers
+   * @returns Result of the processor callback
+   */
+  run<T>(message: StreamMessage, callback: ProcessorCallback<T>): Promise<T>;
 }
 /**
  * Create a stream processor for pipeline-style message processing.
@@ -812,7 +866,9 @@ interface StreamProcessor {
  * });
  * ```
  */
-declare function createStreamProcessor(config: StreamProcessorConfig): StreamProcessor;
+declare function createStreamProcessor(
+  config: StreamProcessorConfig,
+): StreamProcessor;
 
 /**
  * Consumer metrics for Kafka observability.
@@ -853,79 +909,80 @@ type LagStrategy = 'polling' | 'event' | 'hybrid';
  * Matches KafkaJS consumer shape.
  */
 interface KafkaConsumer {
-    on(event: string, listener: (...args: unknown[]) => void): void;
-    describeGroup?(): Promise<{
-        members: Array<{
-            memberId: string;
-            clientId: string;
-            memberAssignment: Buffer;
-        }>;
-        state: string;
+  on(event: string, listener: (...args: unknown[]) => void): void;
+  describeGroup?(): Promise<{
+    members: Array<{
+      memberId: string;
+      clientId: string;
+      memberAssignment: Buffer;
     }>;
+    state: string;
+  }>;
 }
 /**
  * Minimal Kafka admin interface for lag calculation.
  */
 interface KafkaAdmin {
-    fetchTopicOffsets(topic: string): Promise<Array<{
+  fetchTopicOffsets(topic: string): Promise<
+    Array<{
+      partition: number;
+      offset: string;
+      high: string;
+      low: string;
+    }>
+  >;
+  fetchOffsets(options: { groupId: string; topics: string[] }): Promise<
+    Array<{
+      topic: string;
+      partitions: Array<{
         partition: number;
         offset: string;
-        high: string;
-        low: string;
-    }>>;
-    fetchOffsets(options: {
-        groupId: string;
-        topics: string[];
-    }): Promise<Array<{
-        topic: string;
-        partitions: Array<{
-            partition: number;
-            offset: string;
-        }>;
-    }>>;
+      }>;
+    }>
+  >;
 }
 /**
  * Configuration for consumer metrics.
  */
 interface ConsumerMetricsConfig {
-    /**
-     * The Kafka consumer to monitor.
-     */
-    consumer: KafkaConsumer;
-    /**
-     * Optional Kafka admin client for lag calculation.
-     * Required if enableLag is true and lagStrategy is 'polling' or 'hybrid'.
-     */
-    admin?: KafkaAdmin;
-    /**
-     * Consumer group ID (required for lag calculation).
-     */
-    groupId?: string;
-    /**
-     * Topics to monitor for lag.
-     */
-    topics?: string[];
-    /**
-     * Prefix for metric names.
-     * @default 'kafka.consumer'
-     */
-    metricsPrefix?: string;
-    /**
-     * Enable consumer lag tracking.
-     * @default false
-     */
-    enableLag?: boolean;
-    /**
-     * Strategy for lag calculation.
-     * @default 'hybrid'
-     */
-    lagStrategy?: LagStrategy;
-    /**
-     * Interval for lag polling in milliseconds.
-     * Required when enableLag is true and lagStrategy is 'polling'.
-     * @default 30000
-     */
-    lagPollIntervalMs?: number;
+  /**
+   * The Kafka consumer to monitor.
+   */
+  consumer: KafkaConsumer;
+  /**
+   * Optional Kafka admin client for lag calculation.
+   * Required if enableLag is true and lagStrategy is 'polling' or 'hybrid'.
+   */
+  admin?: KafkaAdmin;
+  /**
+   * Consumer group ID (required for lag calculation).
+   */
+  groupId?: string;
+  /**
+   * Topics to monitor for lag.
+   */
+  topics?: string[];
+  /**
+   * Prefix for metric names.
+   * @default 'kafka.consumer'
+   */
+  metricsPrefix?: string;
+  /**
+   * Enable consumer lag tracking.
+   * @default false
+   */
+  enableLag?: boolean;
+  /**
+   * Strategy for lag calculation.
+   * @default 'hybrid'
+   */
+  lagStrategy?: LagStrategy;
+  /**
+   * Interval for lag polling in milliseconds.
+   * Required when enableLag is true and lagStrategy is 'polling'.
+   * @default 30000
+   */
+  lagPollIntervalMs?: number;
 }
 /**
  * Consumer metrics collector.
@@ -938,54 +995,63 @@ interface ConsumerMetricsConfig {
  * - kafka.consumer.lag (gauge, opt-in)
  */
 declare class ConsumerMetrics {
-    private readonly config;
-    private readonly meter;
-    private readonly messagesProcessed;
-    private readonly processingDuration;
-    private readonly batchSize;
-    private readonly rebalances;
-    private readonly lag;
-    private partitionStates;
-    private lagPollInterval?;
-    private isRunning;
-    constructor(config: ConsumerMetricsConfig);
-    /**
-     * Start metrics collection.
-     */
-    start(): Promise<void>;
-    /**
-     * Stop metrics collection.
-     */
-    stop(): Promise<void>;
-    /**
-     * Record a message being processed.
-     *
-     * @param topic - Message topic
-     * @param partition - Message partition
-     * @param durationMs - Processing duration in milliseconds
-     */
-    recordMessageProcessed(topic: string, partition: number, durationMs?: number): void;
-    /**
-     * Record a batch being processed.
-     *
-     * @param topic - Batch topic
-     * @param partition - Batch partition
-     * @param size - Number of messages in the batch
-     */
-    recordBatch(topic: string, partition: number, size: number): void;
-    /**
-     * Update offset state for event-based lag tracking.
-     *
-     * @param topic - Topic name
-     * @param partition - Partition number
-     * @param offset - Current consumer offset
-     * @param highWatermark - Optional high watermark
-     */
-    updateOffset(topic: string, partition: number, offset: string, highWatermark?: string): void;
-    /**
-     * Poll for lag using admin client.
-     */
-    private pollLag;
+  private readonly config;
+  private readonly meter;
+  private readonly messagesProcessed;
+  private readonly processingDuration;
+  private readonly batchSize;
+  private readonly rebalances;
+  private readonly lag;
+  private partitionStates;
+  private lagPollInterval?;
+  private isRunning;
+  constructor(config: ConsumerMetricsConfig);
+  /**
+   * Start metrics collection.
+   */
+  start(): Promise<void>;
+  /**
+   * Stop metrics collection.
+   */
+  stop(): Promise<void>;
+  /**
+   * Record a message being processed.
+   *
+   * @param topic - Message topic
+   * @param partition - Message partition
+   * @param durationMs - Processing duration in milliseconds
+   */
+  recordMessageProcessed(
+    topic: string,
+    partition: number,
+    durationMs?: number,
+  ): void;
+  /**
+   * Record a batch being processed.
+   *
+   * @param topic - Batch topic
+   * @param partition - Batch partition
+   * @param size - Number of messages in the batch
+   */
+  recordBatch(topic: string, partition: number, size: number): void;
+  /**
+   * Update offset state for event-based lag tracking.
+   *
+   * @param topic - Topic name
+   * @param partition - Partition number
+   * @param offset - Current consumer offset
+   * @param highWatermark - Optional high watermark
+   */
+  updateOffset(
+    topic: string,
+    partition: number,
+    offset: string,
+    highWatermark?: string,
+  ): void;
+  /**
+   * Poll for lag using admin client.
+   */
+  private pollLag;
 }
 
 /**
@@ -1018,38 +1084,38 @@ type EventMode = 'events' | 'spans';
  * Minimal Kafka consumer interface for event instrumentation.
  */
 interface EventConsumer {
-    on(event: string, listener: (...args: unknown[]) => void): void;
-    off?(event: string, listener: (...args: unknown[]) => void): void;
+  on(event: string, listener: (...args: unknown[]) => void): void;
+  off?(event: string, listener: (...args: unknown[]) => void): void;
 }
 /**
  * Configuration for consumer event instrumentation.
  */
 interface ConsumerEventsConfig {
-    /**
-     * Event mode: 'events' attaches to spans, 'spans' creates new spans.
-     * @default 'events'
-     */
-    mode?: EventMode;
-    /**
-     * Trace rebalance events (GROUP_JOIN, REBALANCING).
-     * @default true
-     */
-    traceRebalances?: boolean;
-    /**
-     * Trace error events (CRASH, DISCONNECT).
-     * @default true
-     */
-    traceErrors?: boolean;
-    /**
-     * Trace heartbeat events.
-     * @default false (too noisy for most use cases)
-     */
-    traceHeartbeats?: boolean;
-    /**
-     * Optional lifecycle span to attach events to.
-     * Only used when mode is 'events'.
-     */
-    lifecycleSpan?: Span;
+  /**
+   * Event mode: 'events' attaches to spans, 'spans' creates new spans.
+   * @default 'events'
+   */
+  mode?: EventMode;
+  /**
+   * Trace rebalance events (GROUP_JOIN, REBALANCING).
+   * @default true
+   */
+  traceRebalances?: boolean;
+  /**
+   * Trace error events (CRASH, DISCONNECT).
+   * @default true
+   */
+  traceErrors?: boolean;
+  /**
+   * Trace heartbeat events.
+   * @default false (too noisy for most use cases)
+   */
+  traceHeartbeats?: boolean;
+  /**
+   * Optional lifecycle span to attach events to.
+   * Only used when mode is 'events'.
+   */
+  lifecycleSpan?: Span;
 }
 /**
  * Cleanup function returned by instrumentConsumerEvents.
@@ -1076,6 +1142,53 @@ type CleanupFunction = () => void;
  * cleanup();
  * ```
  */
-declare function instrumentConsumerEvents(consumer: EventConsumer, config?: ConsumerEventsConfig): CleanupFunction;
+declare function instrumentConsumerEvents(
+  consumer: EventConsumer,
+  config?: ConsumerEventsConfig,
+): CleanupFunction;
 
-export { type BatchConsumerConfig, type BatchItem, type BatchLineageOptions, type BatchLineageResult, type BatchProgressMetrics, type CleanupFunction, type ConsumerEventsConfig, ConsumerMetrics, type ConsumerMetricsConfig, type ContextMode, type EachBatchHandler, type EachBatchPayload, type EventConsumer, type EventMode, type InjectOptions, type KafkaAdmin, type KafkaConsumer, type LagStrategy, type PerMessageSpanMode, type ProcessingDescriptor, type ProcessingSpanCallback, type ProcessorCallback, type ProcessorContext, type ProduceOptions, type ProducerDescriptor, type ProducerSpanCallback, type RawKafkaHeaders, type StreamMessage, type StreamProcessor, type StreamProcessorConfig, createMessageErrorSpan, createStreamProcessor, deriveCorrelationId, extractBatchLineage, extractBatchLineageAsync, extractCorrelationId, extractTraceContext, injectTraceHeaders, instrumentConsumerEvents, normalizeHeaders, withBatchConsumer, withProcessingSpan, withProducerSpan };
+export {
+  type BatchConsumerConfig,
+  type BatchItem,
+  type BatchLineageOptions,
+  type BatchLineageResult,
+  type BatchProgressMetrics,
+  type CleanupFunction,
+  type ConsumerEventsConfig,
+  ConsumerMetrics,
+  type ConsumerMetricsConfig,
+  type ContextMode,
+  type EachBatchHandler,
+  type EachBatchPayload,
+  type EventConsumer,
+  type EventMode,
+  type InjectOptions,
+  type KafkaAdmin,
+  type KafkaConsumer,
+  type LagStrategy,
+  type PerMessageSpanMode,
+  type ProcessingDescriptor,
+  type ProcessingSpanCallback,
+  type ProcessorCallback,
+  type ProcessorContext,
+  type ProduceOptions,
+  type ProducerDescriptor,
+  type ProducerSpanCallback,
+  type RawKafkaHeaders,
+  type StreamMessage,
+  type StreamProcessor,
+  type StreamProcessorConfig,
+  createMessageErrorSpan,
+  createStreamProcessor,
+  deriveCorrelationId,
+  extractBatchLineage,
+  extractBatchLineageAsync,
+  extractCorrelationId,
+  extractTraceContext,
+  injectTraceHeaders,
+  instrumentConsumerEvents,
+  normalizeHeaders,
+  withBatchConsumer,
+  withProcessingSpan,
+  withProducerSpan,
+};