autotel/dist/attribute-redacting-processor.d.cts

Write Once, Observe Anywhere

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

/**
 * Attribute Redacting Processor
 *
 * Automatically redacts PII and sensitive data from span attributes before export.
 * This is critical for compliance (GDPR, PCI-DSS, HIPAA) and data security.
 *
 * @example Basic usage with preset
 * ```typescript
 * init({
 *   service: 'my-app',
 *   attributeRedactor: 'default'
 * })
 * ```
 *
 * @example Custom patterns
 * ```typescript
 * init({
 *   service: 'my-app',
 *   attributeRedactor: {
 *     keyPatterns: [/password/i, /secret/i],
 *     valuePatterns: [
 *       { name: 'customerId', pattern: /CUST-\d{8}/g, replacement: 'CUST-***' }
 *     ]
 *   }
 * })
 * ```
 */

/**
 * Custom redactor function type
 */
type AttributeRedactorFn = (key: string, value: AttributeValue) => AttributeValue;
/**
 * Built-in redactor preset names
 */
type AttributeRedactorPreset = 'default' | 'strict' | 'pci-dss';
/**
 * Value pattern configuration
 */
interface ValuePatternConfig {
    /** Name for debugging/logging */
    name: string;
    /** Regex pattern to match in values */
    pattern: RegExp;
    /** Custom replacement (default: uses global replacement) */
    replacement?: string;
}
/**
 * Attribute redactor configuration
 */
interface AttributeRedactorConfig {
    /** Patterns to match against attribute keys (redacts entire value if key matches) */
    keyPatterns?: RegExp[];
    /** Patterns to match against attribute values (redacts matched portion) */
    valuePatterns?: ValuePatternConfig[];
    /** Default replacement string (default: '[REDACTED]') */
    replacement?: string;
    /** Custom redactor function for full control */
    redactor?: AttributeRedactorFn;
}
/**
 * Processor options
 */
interface AttributeRedactingProcessorOptions {
    redactor: AttributeRedactorConfig | AttributeRedactorPreset;
}
/**
 * Built-in patterns for detecting sensitive data
 */
declare const REDACTOR_PATTERNS: {
    readonly email: RegExp;
    readonly phone: RegExp;
    readonly ssn: RegExp;
    readonly creditCard: RegExp;
    readonly bearerToken: RegExp;
    readonly apiKeyInValue: RegExp;
    readonly jwt: RegExp;
    readonly sensitiveKey: RegExp;
};
/**
 * Built-in redactor presets
 */
declare const REDACTOR_PRESETS: Record<AttributeRedactorPreset, AttributeRedactorConfig>;
/**
 * Create a proxy wrapper around ReadableSpan with redacted attributes
 *
 * Since ReadableSpan.attributes is readonly, we use a Proxy to intercept
 * attribute access and return the redacted version.
 */
declare function createRedactedSpan(span: ReadableSpan, redactor: AttributeRedactorFn): ReadableSpan;
/**
 * Create an attribute redactor function from a config or preset.
 *
 * This is useful when you need to apply the same redaction logic
 * outside of the span processor pipeline (e.g., for canonical log lines).
 *
 * @example
 * ```typescript
 * const redactor = createAttributeRedactor('default');
 * const redactedValue = redactor('user.password', 'secret123');
 * // redactedValue === '[REDACTED]'
 * ```
 */
declare function createAttributeRedactor(config: AttributeRedactorConfig | AttributeRedactorPreset): AttributeRedactorFn;
/**
 * Span processor that redacts sensitive data from span attributes.
 *
 * Redaction happens in onEnd() when all attributes are finalized.
 * Uses a Proxy wrapper to intercept attribute access since ReadableSpan
 * attributes are readonly.
 *
 * Common use cases:
 * - PII compliance (GDPR, CCPA)
 * - PCI-DSS compliance for payment data
 * - Preventing secrets from leaking to observability backends
 */
declare class AttributeRedactingProcessor implements SpanProcessor {
    private readonly wrappedProcessor;
    private readonly redactor;
    constructor(wrappedProcessor: SpanProcessor, options: AttributeRedactingProcessorOptions);
    /**
     * Pass through onStart unchanged - attributes aren't finalized yet
     */
    onStart(span: Span, parentContext: Context): void;
    /**
     * Redact attributes and forward to wrapped processor
     */
    onEnd(span: ReadableSpan): void;
    forceFlush(): Promise<void>;
    shutdown(): Promise<void>;
}

export { AttributeRedactingProcessor, type AttributeRedactingProcessorOptions, type AttributeRedactorConfig, type AttributeRedactorFn, type AttributeRedactorPreset, REDACTOR_PATTERNS, REDACTOR_PRESETS, type ValuePatternConfig, createAttributeRedactor, createRedactedSpan };