autotel/dist/span-name-normalizer.d.cts

Write Once, Observe Anywhere

import { SpanProcessor, Span, ReadableSpan } from '@opentelemetry/sdk-trace-base';
import { Context } from '@opentelemetry/api';

/**
 * Span Name Normalizer
 *
 * Normalizes span names to reduce cardinality from dynamic path segments.
 * This is critical for observability backends that charge by unique span names
 * or have cardinality limits.
 *
 * @example Basic usage with custom function
 * ```typescript
 * init({
 *   service: 'my-app',
 *   spanNameNormalizer: (name) => {
 *     return name.replace(/\/[0-9]+/g, '/:id');
 *   }
 * })
 * ```
 *
 * @example Using built-in preset
 * ```typescript
 * init({
 *   service: 'my-app',
 *   spanNameNormalizer: 'rest-api'
 * })
 * ```
 */

/**
 * Function to normalize a span name
 * @param name - The original span name
 * @returns The normalized span name
 */
type SpanNameNormalizerFn = (name: string) => string;
/**
 * Built-in normalizer preset names
 */
type SpanNameNormalizerPreset = 'rest-api' | 'graphql' | 'minimal';
/**
 * Normalizer config - either a function or a preset name
 */
type SpanNameNormalizerConfig = SpanNameNormalizerFn | SpanNameNormalizerPreset;
interface SpanNameNormalizingProcessorOptions {
    /**
     * Normalizer function or preset name
     */
    normalizer: SpanNameNormalizerConfig;
}
/**
 * Built-in normalizer patterns
 */
declare const NORMALIZER_PATTERNS: {
    readonly numericId: RegExp;
    readonly uuid: RegExp;
    readonly shortUuid: RegExp;
    readonly objectId: RegExp;
    readonly hash: RegExp;
    readonly isoDate: RegExp;
    readonly timestamp: RegExp;
    readonly email: RegExp;
};
/**
 * Built-in normalizer presets
 */
declare const NORMALIZER_PRESETS: Record<SpanNameNormalizerPreset, SpanNameNormalizerFn>;
/**
 * Span processor that normalizes span names to reduce cardinality.
 *
 * Normalization happens in onStart() when we have access to the mutable Span.
 * This allows us to call span.updateName() before the span is finalized.
 *
 * Common use cases:
 * - REST APIs: /users/123/posts/456 → /users/:id/posts/:id
 * - UUIDs: /items/550e8400-e29b-41d4-a716-446655440000 → /items/:uuid
 * - Dates: /logs/2024-01-15 → /logs/:date
 */
declare class SpanNameNormalizingProcessor implements SpanProcessor {
    private readonly wrappedProcessor;
    private readonly normalizer;
    constructor(wrappedProcessor: SpanProcessor, options: SpanNameNormalizingProcessorOptions);
    /**
     * Normalize span name on start (when Span is mutable)
     */
    onStart(span: Span, parentContext: Context): void;
    /**
     * Pass through onEnd unchanged
     */
    onEnd(span: ReadableSpan): void;
    forceFlush(): Promise<void>;
    shutdown(): Promise<void>;
}

export { NORMALIZER_PATTERNS, NORMALIZER_PRESETS, type SpanNameNormalizerConfig, type SpanNameNormalizerFn, type SpanNameNormalizerPreset, SpanNameNormalizingProcessor, type SpanNameNormalizingProcessorOptions };