autotel/dist/diagnostics.d.cts

Write Once, Observe Anywhere

import { Attributes, Tracer } from "@opentelemetry/api";

//#region src/diagnostics/channel.d.ts
/**
 * Edge-safe wrappers over Node's `diagnostics_channel`.
 *
 * The module is loaded lazily through {@link safeRequire} — never a static
 * `node:` import — so merely importing this file is side-effect-free and bundles
 * cleanly for browser/edge targets, where every subscribe call degrades to a
 * no-op (returning an unsubscribe that does nothing). This is the shared
 * primitive behind autotel's diagnostics-channel integrations (console capture,
 * HTTP spans) and any app- or library-specific channel you want to bridge into
 * a span/event.
 *
 * `diagnostics_channel.subscribe` (Node 18.7+) and `tracingChannel` (Node 19+)
 * are used; autotel targets Node 22+, but on any runtime that lacks them the
 * loader returns `undefined` and the helpers no-op.
 */
/** Whether Node's `diagnostics_channel` is available in this runtime. */
declare function diagnosticsChannelAvailable(): boolean;
/** Handler for a plain named channel. */
type ChannelMessageHandler = (message: unknown, name: string | symbol) => void;
/**
 * Subscribe to a named diagnostics channel. Returns an idempotent unsubscribe
 * function; a no-op (that still returns a disposer) on unsupported runtimes.
 */
declare function subscribeChannel(name: string, handler: ChannelMessageHandler): () => void;
/** Subscriber set for a {@link https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel TracingChannel}. */
interface TracingChannelHandlers {
  start?(message: unknown): void;
  end?(message: unknown): void;
  asyncStart?(message: unknown): void;
  asyncEnd?(message: unknown): void;
  error?(message: unknown): void;
}
/**
 * Subscribe to a `tracingChannel` (the `tracing:${name}:{start,end,…}` set).
 * Returns an idempotent unsubscribe; a no-op on runtimes without
 * `tracingChannel` support.
 */
declare function subscribeTracingChannel(name: string, handlers: TracingChannelHandlers): () => void;
//#endregion
//#region src/diagnostics/console.d.ts
/** Console methods that publish a diagnostics channel. */
type ConsoleLevel = 'log' | 'info' | 'debug' | 'warn' | 'error';
interface CaptureConsoleOptions {
  /** Which console methods to capture. Defaults to all five. */
  levels?: readonly ConsoleLevel[];
  /**
   * Where to record captured output:
   * - `'log'` (default): emit an OpenTelemetry log record;
   * - `'span-event'`: add an event to the active span (nothing if no active span);
   * - `'both'`.
   */
  target?: 'log' | 'span-event' | 'both';
  /** Logger name for emitted records. Defaults to `'autotel.console'`. */
  loggerName?: string;
  /** Static attributes merged onto every captured record/event. */
  attributes?: Attributes;
}
/**
 * Start capturing `console.*` calls as wide events. Returns a disposer that
 * stops capture. Safe to call on runtimes without the console channels (no-op).
 */
declare function captureConsole(options?: CaptureConsoleOptions): () => void;
//#endregion
//#region src/diagnostics/http.d.ts
interface InstrumentHttpOptions {
  /** Instrument inbound (server) requests. Default `true`. */
  server?: boolean;
  /** Instrument outbound (client) requests. Default `true`. */
  client?: boolean;
  /** Tracer to use. Defaults to `trace.getTracer('autotel.http-diagnostics')`. */
  tracer?: Tracer;
}
/**
 * Start emitting HTTP server/client spans from Node's HTTP diagnostics
 * channels. Returns a disposer; a no-op on runtimes without the channels.
 */
declare function instrumentHttp(options?: InstrumentHttpOptions): () => void;
//#endregion
export { type CaptureConsoleOptions, type ChannelMessageHandler, type ConsoleLevel, type InstrumentHttpOptions, type TracingChannelHandlers, captureConsole, diagnosticsChannelAvailable, instrumentHttp, subscribeChannel, subscribeTracingChannel };
//# sourceMappingURL=diagnostics.d.cts.map