/**
 * Fastify Tracing Middleware
 *
 * Request tracing middleware for Fastify that provides:
 * - Automatic span creation for HTTP requests
 * - Trace ID injection in response headers
 * - Error span recording
 * - Security context propagation
 *
 * @packageDocumentation
 */
import type { FastifyRequest, FastifyReply, FastifyPluginCallback } from 'fastify';
import { type Span, type Context, type Attributes } from '@opentelemetry/api';
import { getTraceContext } from './propagation.js';
/**
 * Tracing middleware configuration options
 */
export interface TracingMiddlewareOptions {
    /** Enable tracing (default: true) */
    enabled?: boolean;
    /** Paths to exclude from tracing */
    excludePaths?: string[];
    /** Include request body in span (default: false, security risk) */
    includeRequestBody?: boolean;
    /** Include response body in span (default: false) */
    includeResponseBody?: boolean;
    /** Maximum body size to include (bytes) */
    maxBodySize?: number;
    /** Add trace headers to response */
    addResponseHeaders?: boolean;
    /** Custom request hook */
    requestHook?: (span: Span, request: FastifyRequest) => void;
    /** Custom response hook */
    responseHook?: (span: Span, request: FastifyRequest, reply: FastifyReply) => void;
    /** Trace context extractor */
    traceContextExtractor?: (request: FastifyRequest) => TracingSecurityContext | null;
}
/**
 * Security context for tracing (separate from Fastify's securityContext)
 */
export interface TracingSecurityContext {
    tenantId?: string;
    entityId?: string;
    userId?: string;
    roles?: string[];
    permissions?: string[];
    sessionId?: string;
    apiKeyId?: string;
}
/**
 * Extended Fastify request with tracing context
 */
export interface TracedFastifyRequest extends FastifyRequest {
    /** Active tracing span */
    span?: Span;
    /** OpenTelemetry context for tracing (different from request's traceContext) */
    otelContext?: Context;
    /** Trace ID */
    traceId?: string;
    /** Span ID */
    spanId?: string;
    /** Tracing security context (separate from FastifyRequest.securityContext) */
    tracingSecurityContext?: TracingSecurityContext;
}
/**
 * Fastify tracing plugin
 */
export declare const tracingMiddleware: FastifyPluginCallback<TracingMiddlewareOptions>;
/**
 * Create request-scoped tracing context
 *
 * Run async operations within the request's trace context
 */
export declare function runInRequestContext<T>(request: FastifyRequest, fn: () => T): T;
/**
 * Create a child span for the current request
 */
export declare function createRequestChildSpan(request: FastifyRequest, name: string, attributes?: Attributes): Span;
/**
 * Execute a function within a child span of the request
 */
export declare function withRequestSpan<T>(request: FastifyRequest, name: string, fn: (span: Span) => Promise<T>, attributes?: Attributes): Promise<T>;
/**
 * Add attributes to the request's span
 */
export declare function addRequestSpanAttributes(request: FastifyRequest, attributes: Attributes): void;
/**
 * Add an event to the request's span
 */
export declare function addRequestSpanEvent(request: FastifyRequest, name: string, attributes?: Attributes): void;
/**
 * Record an error on the request's span
 */
export declare function recordRequestError(request: FastifyRequest, error: Error, attributes?: Attributes): void;
/**
 * Get trace ID from request
 */
export declare function getRequestTraceId(request: FastifyRequest): string | undefined;
/**
 * Get span ID from request
 */
export declare function getRequestSpanId(request: FastifyRequest): string | undefined;
/**
 * Get tracing security context from request
 */
export declare function getRequestTracingSecurityContext(request: FastifyRequest): TracingSecurityContext | undefined;
declare module 'fastify' {
    interface FastifyInstance {
        getActiveSpan: () => Span | undefined;
        getTraceContext: () => ReturnType<typeof getTraceContext>;
        injectTraceHeaders: (headers: Record<string, string>) => Record<string, string>;
    }
}
//# sourceMappingURL=middleware.d.ts.map