serverstruct/dist/otel.d.mts

Type safe and modular servers with H3

import * as h30 from "h3";
import { H3Event } from "h3";
import { Attributes, TextMapPropagator, Tracer } from "@opentelemetry/api";

//#region src/otel.d.ts
/**
 * Configuration options for OpenTelemetry trace middleware.
 */
interface TraceMiddlewareOptions {
  /**
   * Custom function to generate span names from H3 events.
   * Defaults to `{METHOD} {pathname}` (e.g., "GET /users/123").
   */
  spanName?: (event: H3Event) => string;
  /**
   * Custom function to add additional span attributes from H3 events.
   * Called during span recording to enrich traces with application-specific data.
   */
  spanAttributes?: (event: H3Event) => Attributes;
  /**
   * Custom OpenTelemetry tracer instance.
   * Defaults to a tracer created from this package name and version.
   */
  tracer?: Tracer;
  /**
   * HTTP headers to capture as span attributes.
   */
  headers?: {
    /**
     * Request header names to capture (e.g., ["authorization", "x-api-key"]).
     * Values are recorded as `http.request.header.<name>` attributes.
     */
    request?: string[];
    /**
     * Response header names to capture (e.g., ["x-request-id", "x-rate-limit"]).
     * Values are recorded as `http.response.header.<name>` attributes.
     */
    response?: string[];
  };
  /**
   * Trace context propagation configuration.
   */
  propagation?: {
    /**
     * Disable extraction of trace context from incoming request headers.
     * Defaults to false.
     */
    disabled?: boolean;
    /**
     * Custom propagator for trace context extraction.
     * Defaults to the global OpenTelemetry propagator.
     */
    propagator?: TextMapPropagator;
  };
}
/**
 * Creates an H3 middleware for OpenTelemetry distributed tracing.
 *
 * Automatically instruments HTTP requests with OpenTelemetry spans, capturing
 * the following semantic convention attributes:
 * - `http.request.method` - HTTP method
 * - `url.full` - Full request URL
 * - `url.path` - URL path
 * - `url.query` - Query string
 * - `url.scheme` - URL scheme
 * - `server.address` - Server host
 * - `user_agent.original` - User agent header
 * - `http.response.status_code` - Response status code
 * - `http.request.header.<name>` - Custom request headers
 * - `http.response.header.<name>` - Custom response headers
 *
 * Exceptions are recorded with full details when errors occur.
 *
 * Status codes are mapped to span statuses:
 * - 1xx-4xx: SpanStatusCode.OK
 * - 5xx: SpanStatusCode.ERROR
 *
 * The middleware supports trace context propagation for distributed tracing across
 * microservices using OpenTelemetry propagators.
 *
 * @param options - Configuration options for tracing behavior
 * @returns H3 middleware function
 *
 * @example
 * ```ts
 * import { traceMiddleware } from "serverstruct/otel";
 *
 * // Default usage
 * app.use(traceMiddleware());
 *
 * // With options
 * app.use(traceMiddleware({
 *   headers: {
 *     request: ["authorization"],
 *     response: ["x-request-id"]
 *   },
 *   propagation: {
 *     disabled: true
 *   }
 * }));
 * ```
 */
declare function traceMiddleware(options?: TraceMiddlewareOptions): h30.Middleware;
//#endregion
export { traceMiddleware };