@atrim/instrument-node 0.7.0 → 0.7.1-dev.14fdea7.20260108224013

package/target/dist/integrations/effect/auto/index.d.ts

@@ -0,0 +1,359 @@
+import { Layer, Supervisor, Effect, Context, Option, Fiber, Exit, FiberRef } from 'effect';
+import * as OtelApi from '@opentelemetry/api';
+import { AutoInstrumentationConfig, InstrumentationConfig } from '@atrim/instrument-core';
+export { AutoInstrumentationConfig } from '@atrim/instrument-core';
+
+/**
+ * Auto-Tracing Supervisor for Effect-TS
+ *
+ * Provides automatic tracing of all Effect fibers without manual Effect.withSpan() calls.
+ * Uses Effect's Supervisor API to intercept fiber creation/termination and create
+ * OpenTelemetry spans automatically.
+ *
+ * @example
+ * ```typescript
+ * import { AutoTracingLive } from '@atrim/instrument-node/effect/auto'
+ *
+ * const program = Effect.gen(function* () {
+ *   yield* doWork()  // Automatically traced!
+ * }).pipe(Effect.provide(AutoTracingLive))
+ * ```
+ */
+
+/**
+ * FiberRef to enable/disable auto-tracing for specific fibers
+ * Use withoutAutoTracing() to disable
+ */
+declare const AutoTracingEnabled: FiberRef.FiberRef<boolean>;
+/**
+ * FiberRef to override auto-generated span name
+ * Use setSpanName() to override
+ */
+declare const AutoTracingSpanName: FiberRef.FiberRef<Option.Option<string>>;
+/**
+ * Supervisor that automatically creates OpenTelemetry spans for all Effect fibers
+ *
+ * This supervisor intercepts fiber creation and termination, creating spans
+ * based on configuration from instrumentation.yaml.
+ */
+declare class AutoTracingSupervisor extends Supervisor.AbstractSupervisor<void> {
+    private readonly config;
+    private readonly fiberSpans;
+    private readonly fiberStartTimes;
+    private _tracer;
+    private readonly includePatterns;
+    private readonly excludePatterns;
+    private activeFiberCount;
+    private _rootSpan;
+    constructor(config: AutoInstrumentationConfig);
+    /**
+     * Set the root span for parent context propagation
+     */
+    setRootSpan(span: OtelApi.Span): void;
+    /**
+     * Get the tracer lazily - this allows time for the NodeSdk layer to register the global provider
+     */
+    private get tracer();
+    /**
+     * Returns the current value (void for this supervisor)
+     */
+    get value(): Effect.Effect<void>;
+    /**
+     * Called when a fiber starts executing
+     */
+    onStart<A, E, R>(_context: Context.Context<R>, _effect: Effect.Effect<A, E, R>, parent: Option.Option<Fiber.RuntimeFiber<unknown, unknown>>, fiber: Fiber.RuntimeFiber<A, E>): void;
+    /**
+     * Called when a fiber completes (success or failure)
+     */
+    onEnd<A, E>(exit: Exit.Exit<A, E>, fiber: Fiber.RuntimeFiber<A, E>): void;
+    /**
+     * Check if a span name should be traced based on filter patterns
+     */
+    private shouldTrace;
+    /**
+     * Get initial span attributes for a fiber
+     */
+    private getInitialAttributes;
+    /**
+     * Parse stack trace to get source info
+     */
+    private parseStackTrace;
+    /**
+     * Parse min_duration string to nanoseconds
+     */
+    private parseMinDuration;
+}
+/**
+ * Create a custom AutoTracingSupervisor with the given config
+ */
+declare const createAutoTracingSupervisor: (config: AutoInstrumentationConfig) => AutoTracingSupervisor;
+/**
+ * Layer that provides auto-tracing with custom configuration
+ *
+ * @example
+ * ```typescript
+ * const CustomAutoTracing = createAutoTracingLayer({
+ *   enabled: true,
+ *   span_naming: {
+ *     default: 'app.{function}',
+ *     rules: [{ match: { file: 'src/services/.*' }, name: 'service.{function}' }]
+ *   }
+ * })
+ * ```
+ */
+declare const createAutoTracingLayer: (options?: {
+    config?: AutoInstrumentationConfig;
+}) => Layer.Layer<never>;
+/**
+ * Wrap an Effect with auto-tracing supervision
+ *
+ * This creates a span for the main effect AND supervises all child fibers.
+ * Use this when you need to ensure all fibers in an effect are traced.
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   yield* doWork()  // Automatically traced!
+ * })
+ *
+ * const tracedProgram = withAutoTracing(program, { enabled: true, ... })
+ * Effect.runPromise(tracedProgram)
+ * ```
+ */
+declare const withAutoTracing: <A, E, R>(effect: Effect.Effect<A, E, R>, config: AutoInstrumentationConfig, mainSpanName?: string) => Effect.Effect<A, E, R>;
+/**
+ * Zero-config auto-tracing layer
+ *
+ * Loads configuration from instrumentation.yaml and automatically traces
+ * all Effect fibers based on the configuration.
+ *
+ * @example
+ * ```typescript
+ * import { AutoTracingLive } from '@atrim/instrument-node/effect/auto'
+ *
+ * const program = Effect.gen(function* () {
+ *   yield* doWork()  // Automatically traced!
+ * }).pipe(Effect.provide(AutoTracingLive))
+ * ```
+ */
+declare const AutoTracingLive: Layer.Layer<never>;
+/**
+ * Disable auto-tracing for a specific Effect
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   yield* publicWork()  // Traced
+ *   yield* withoutAutoTracing(internalWork())  // NOT traced
+ * })
+ * ```
+ */
+declare const withoutAutoTracing: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+/**
+ * Override the auto-generated span name for a specific Effect
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   yield* setSpanName('custom.operation.name')(myEffect)
+ * })
+ * ```
+ */
+declare const setSpanName: (name: string) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+/**
+ * Create a fully YAML-driven auto-instrumentation layer
+ *
+ * This layer reads all configuration from instrumentation.yaml including:
+ * - Exporter configuration (type, endpoint, processor)
+ * - Auto-tracing configuration (naming rules, filters, performance)
+ * - Service metadata (name, version)
+ *
+ * @example
+ * ```typescript
+ * import { createFullAutoTracingLayer } from '@atrim/instrument-node/effect/auto'
+ *
+ * // Everything configured via instrumentation.yaml - no code config needed!
+ * const AppLive = createFullAutoTracingLayer()
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(AppLive)))
+ * ```
+ */
+declare const createFullAutoTracingLayer: () => Layer.Layer<never>;
+/**
+ * Fully YAML-driven auto-instrumentation layer
+ *
+ * This is the recommended way to use auto-instrumentation. All configuration
+ * comes from instrumentation.yaml - no code configuration needed.
+ *
+ * @example
+ * ```yaml
+ * # instrumentation.yaml
+ * effect:
+ *   auto_instrumentation:
+ *     enabled: true
+ *     span_naming:
+ *       default: "effect.{function}"
+ *       rules:
+ *         - match: { function: "internal.*" }
+ *           name: "internal.{function}"
+ *     filter:
+ *       exclude:
+ *         - "^internal\\."
+ *   exporter_config:
+ *     type: otlp              # or 'console' for dev
+ *     endpoint: http://localhost:4318
+ *     processor: batch        # or 'simple' for dev
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { FullAutoTracingLive } from '@atrim/instrument-node/effect/auto'
+ *
+ * // Just provide the layer - everything else from YAML!
+ * Effect.runPromise(program.pipe(Effect.provide(FullAutoTracingLive)))
+ * ```
+ */
+declare const FullAutoTracingLive: Layer.Layer<never>;
+
+/**
+ * Node.js configuration loader
+ *
+ * Provides configuration loading using native Node.js APIs (fs, fetch)
+ * This module doesn't require Effect Platform, making it work without Effect installed.
+ */
+
+/**
+ * Legacy options interface for backward compatibility
+ */
+interface ConfigLoaderOptions {
+    configPath?: string;
+    configUrl?: string;
+    config?: InstrumentationConfig;
+    cacheTimeout?: number;
+}
+
+/**
+ * Auto-Tracing Configuration Loader
+ *
+ * Loads auto-tracing configuration from instrumentation.yaml
+ * and provides a typed Effect service for accessing it.
+ */
+
+/**
+ * Default auto-tracing configuration when not specified in instrumentation.yaml
+ */
+declare const defaultAutoTracingConfig: AutoInstrumentationConfig;
+declare const AutoTracingConfig_base: Context.TagClass<AutoTracingConfig, "AutoTracingConfig", {
+    enabled: boolean;
+    filter: {
+        include: string[];
+        exclude: string[];
+    };
+    granularity: "fiber" | "operator";
+    span_naming: {
+        default: string;
+        infer_from_source: boolean;
+        rules: {
+            match: {
+                function?: string | undefined;
+                file?: string | undefined;
+                module?: string | undefined;
+            };
+            name: string;
+        }[];
+    };
+    performance: {
+        sampling_rate: number;
+        min_duration: string;
+        max_concurrent: number;
+    };
+    metadata: {
+        fiber_info: boolean;
+        source_location: boolean;
+        parent_fiber: boolean;
+    };
+}>;
+/**
+ * Service tag for auto-tracing configuration
+ */
+declare class AutoTracingConfig extends AutoTracingConfig_base {
+}
+/**
+ * Load auto-tracing configuration from instrumentation.yaml
+ *
+ * Returns the config from effect.auto_instrumentation section,
+ * or defaults if not specified.
+ */
+declare const loadAutoTracingConfig: (options?: ConfigLoaderOptions) => Effect.Effect<AutoInstrumentationConfig, never, never>;
+/**
+ * Load auto-tracing configuration synchronously from cache or default
+ *
+ * Note: This is a synchronous fallback when Effect runtime isn't available.
+ * Prefer loadAutoTracingConfig() when possible.
+ */
+declare const loadAutoTracingConfigSync: () => AutoInstrumentationConfig;
+/**
+ * Layer that provides auto-tracing configuration
+ */
+declare const AutoTracingConfigLive: Layer.Layer<AutoTracingConfig, never, never>;
+/**
+ * Layer that provides custom auto-tracing configuration
+ */
+declare const AutoTracingConfigLayer: (config: AutoInstrumentationConfig) => Layer.Layer<AutoTracingConfig>;
+
+/**
+ * Span Name Inference for Auto-Tracing
+ *
+ * Provides intelligent span naming based on source code information
+ * and configuration rules from instrumentation.yaml.
+ */
+
+/**
+ * Source code information extracted from stack traces
+ */
+interface SourceInfo {
+    /** Function name (or 'anonymous') */
+    function: string;
+    /** Full file path */
+    file: string;
+    /** Line number */
+    line: number;
+    /** Column number */
+    column: number;
+}
+/**
+ * Template variables available for span naming
+ */
+interface TemplateVariables {
+    fiber_id: string;
+    function: string;
+    module: string;
+    file: string;
+    line: string;
+    operator: string;
+    [key: string]: string;
+}
+/**
+ * Infer a span name based on fiber ID, source info, and configuration
+ *
+ * Priority:
+ * 1. Match against naming rules (first match wins)
+ * 2. Use default template with source info if available
+ * 3. Fallback to default template with fiber ID only
+ *
+ * @param fiberId - The fiber's numeric ID
+ * @param sourceInfo - Optional source code information from stack trace
+ * @param config - Auto-instrumentation configuration
+ * @returns The inferred span name
+ */
+declare function inferSpanName(fiberId: number, sourceInfo: SourceInfo | undefined, config: AutoInstrumentationConfig): string;
+/**
+ * Sanitize a span name to be OpenTelemetry compliant
+ *
+ * - Replaces invalid characters with underscores
+ * - Ensures name is not empty
+ * - Truncates to reasonable length
+ */
+declare function sanitizeSpanName(name: string): string;
+
+export { AutoTracingConfig, AutoTracingConfigLayer, AutoTracingConfigLive, AutoTracingEnabled, AutoTracingLive, AutoTracingSpanName, AutoTracingSupervisor, FullAutoTracingLive, type SourceInfo, type TemplateVariables, createAutoTracingLayer, createAutoTracingSupervisor, createFullAutoTracingLayer, defaultAutoTracingConfig, inferSpanName, loadAutoTracingConfig, loadAutoTracingConfigSync, sanitizeSpanName, setSpanName, withAutoTracing, withoutAutoTracing };