@atrim/instrument-node 0.4.0 → 0.5.0-14fdea7-20260108232035

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

@@ -0,0 +1,484 @@
+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';
+
+/**
+ * Effect-Native Tracing Layer
+ *
+ * Uses @effect/opentelemetry's NodeSdk.layer for proper Effect integration.
+ * This provides automatic HTTP request tracing and Effect.withSpan() support.
+ *
+ * Requires @effect/opentelemetry peer dependency to be installed.
+ */
+
+/**
+ * Create a layer that provides Effect-native tracing via NodeSdk.layer
+ *
+ * This integrates with Effect's built-in tracing system, which means:
+ * - HTTP requests are automatically traced by @effect/platform
+ * - Effect.withSpan() creates proper OTel spans
+ * - Parent-child span relationships work correctly
+ * - No need to fork fibers for tracing to work
+ *
+ * Configuration is loaded from instrumentation.yaml (exporter_config section).
+ *
+ * @example
+ * ```typescript
+ * import { EffectTracingLive } from '@atrim/instrument-node/effect/auto'
+ *
+ * // HTTP requests automatically traced!
+ * const HttpLive = router.pipe(
+ *   HttpServer.serve(),
+ *   Layer.provide(ServerLive),
+ *   Layer.provide(EffectTracingLive),
+ * )
+ * ```
+ */
+declare const createEffectTracingLayer: () => Layer.Layer<never>;
+/**
+ * Effect-native tracing layer using @effect/opentelemetry
+ *
+ * This is the **recommended** layer for Effect HTTP applications. It provides:
+ * - Automatic HTTP request tracing (built into @effect/platform)
+ * - Full Effect.withSpan() support for manual spans
+ * - Proper parent-child span relationships
+ * - No need to fork fibers manually
+ *
+ * Configuration is loaded from your instrumentation.yaml file.
+ *
+ * @example
+ * ```yaml
+ * # instrumentation.yaml
+ * effect:
+ *   exporter_config:
+ *     type: otlp        # or 'console' for dev
+ *     endpoint: http://localhost:4318
+ *     headers:
+ *       x-api-key: your-key
+ *     processor: batch   # or 'simple' for immediate export
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { EffectTracingLive } from '@atrim/instrument-node/effect/auto'
+ * import { HttpRouter, HttpServer } from "@effect/platform"
+ * import { NodeHttpServer, NodeRuntime } from "@effect/platform-node"
+ *
+ * const router = HttpRouter.empty.pipe(
+ *   HttpRouter.get("/", Effect.succeed(HttpServerResponse.text("Hello!"))),
+ * )
+ *
+ * const HttpLive = router.pipe(
+ *   HttpServer.serve(),
+ *   Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })),
+ *   Layer.provide(EffectTracingLive),  // <- Just add this!
+ * )
+ *
+ * NodeRuntime.runMain(Layer.launch(HttpLive))
+ * // All HTTP requests now automatically traced!
+ * ```
+ */
+declare const EffectTracingLive: Layer.Layer<never>;
+/**
+ * Create a combined layer that provides both:
+ * 1. Effect-native HTTP tracing (via NodeSdk.layer)
+ * 2. Fiber-level auto-tracing (via Supervisor)
+ *
+ * This gives you automatic spans for:
+ * - Every HTTP request (from Effect's platform middleware)
+ * - Every forked fiber (from our Supervisor)
+ *
+ * No manual Effect.withSpan() calls needed.
+ */
+declare const createCombinedTracingLayer: () => Layer.Layer<never>;
+/**
+ * Combined tracing layer providing both HTTP and fiber-level auto-tracing
+ *
+ * This is the **most comprehensive** tracing option. You get automatic spans for:
+ * - Every HTTP request (from Effect's @effect/platform middleware)
+ * - Every forked fiber (from our Supervisor)
+ *
+ * No manual Effect.withSpan() calls needed - everything is traced automatically.
+ *
+ * @example
+ * ```yaml
+ * # instrumentation.yaml
+ * effect:
+ *   auto_instrumentation:
+ *     enabled: true
+ *     granularity: fiber
+ *   exporter_config:
+ *     type: otlp
+ *     endpoint: http://localhost:4318
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { CombinedTracingLive } from '@atrim/instrument-node/effect/auto'
+ *
+ * const HttpLive = router.pipe(
+ *   HttpServer.serve(),
+ *   Layer.provide(ServerLive),
+ *   Layer.provide(CombinedTracingLive),
+ * )
+ *
+ * // Both HTTP requests AND forked fibers are auto-traced!
+ * ```
+ */
+declare const CombinedTracingLive: Layer.Layer<never>;
+
+/**
+ * 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, CombinedTracingLive, EffectTracingLive, FullAutoTracingLive, type SourceInfo, type TemplateVariables, createAutoTracingLayer, createAutoTracingSupervisor, createCombinedTracingLayer, createEffectTracingLayer, createFullAutoTracingLayer, defaultAutoTracingConfig, inferSpanName, loadAutoTracingConfig, loadAutoTracingConfigSync, sanitizeSpanName, setSpanName, withAutoTracing, withoutAutoTracing };