@atrim/instrument-node 0.1.3-12a8f92-20251118011211

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

@@ -0,0 +1,343 @@
+import { Layer, FiberSet as FiberSet$1, Effect } from 'effect';
+import { ConfigLoaderOptions } from '@atrim/instrument-core';
+import * as effect_Runtime from 'effect/Runtime';
+import * as effect_FiberId from 'effect/FiberId';
+import * as effect_Scope from 'effect/Scope';
+import { RuntimeFiber } from 'effect/Fiber';
+
+/**
+ * Effect-TS Tracer integration with context propagation
+ *
+ * This module provides Effect-TS tracing that seamlessly integrates with
+ * OpenTelemetry NodeSDK auto-instrumentation. Effect spans will automatically
+ * continue existing traces created by NodeSDK (e.g., HTTP requests).
+ *
+ * Context Propagation:
+ * - NodeSDK auto-instrumentation creates root spans (e.g., HTTP requests)
+ * - Effect operations automatically become child spans of the active trace
+ * - Uses OpenTelemetry Context API (equivalent to Java thread-local)
+ * - No configuration needed - works out of the box
+ *
+ * Architecture:
+ * 1. @effect/opentelemetry uses the global OpenTelemetry tracer provider
+ * 2. When an Effect operation starts, it checks context.active() for existing spans
+ * 3. If found, creates child spans. If not, creates new root span.
+ * 4. This happens automatically via OpenTelemetry Context propagation
+ */
+
+/**
+ * Configuration options for Effect instrumentation
+ */
+interface EffectInstrumentationOptions extends ConfigLoaderOptions {
+    /**
+     * OTLP endpoint URL
+     * @default process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318'
+     */
+    otlpEndpoint?: string;
+    /**
+     * Service name
+     * @default process.env.OTEL_SERVICE_NAME || 'effect-service'
+     */
+    serviceName?: string;
+    /**
+     * Service version
+     * @default process.env.npm_package_version || '1.0.0'
+     */
+    serviceVersion?: string;
+    /**
+     * Whether to automatically extract Effect fiber metadata
+     * @default true
+     */
+    autoExtractMetadata?: boolean;
+    /**
+     * Whether to continue existing traces from NodeSDK auto-instrumentation
+     *
+     * When true (default):
+     * - Effect spans become children of existing NodeSDK spans
+     * - Example: HTTP request span → Effect business logic span
+     * - Uses OpenTelemetry Context API for propagation
+     *
+     * When false:
+     * - Effect operations always create new root spans
+     * - Not recommended unless you have specific requirements
+     *
+     * @default true
+     */
+    continueExistingTraces?: boolean;
+}
+/**
+ * Create Effect instrumentation layer with custom options
+ *
+ * This function creates an Effect Layer that provides OpenTelemetry tracing
+ * with automatic context propagation from NodeSDK auto-instrumentation.
+ *
+ * @example
+ * ```typescript
+ * // With NodeSDK auto-instrumentation
+ * import { NodeSDK } from '@opentelemetry/sdk-node'
+ * import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
+ *
+ * // 1. Start NodeSDK (creates HTTP spans automatically)
+ * const sdk = new NodeSDK({
+ *   instrumentations: [getNodeAutoInstrumentations()]
+ * })
+ * sdk.start()
+ *
+ * // 2. Create Effect instrumentation (will continue NodeSDK traces)
+ * const EffectLayer = createEffectInstrumentation()
+ *
+ * // 3. Use in Effect operations
+ * const program = Effect.gen(function* () {
+ *   // This span will be a child of the HTTP request span (if any)
+ *   yield* Effect.log("Business logic")
+ * }).pipe(
+ *   Effect.withSpan("app.business.logic"),
+ *   Effect.provide(EffectLayer)
+ * )
+ * ```
+ */
+declare function createEffectInstrumentation(options?: EffectInstrumentationOptions): Layer.Layer<never, never, never>;
+/**
+ * Zero-config Effect instrumentation layer
+ *
+ * Uses the global OpenTelemetry tracer provider that was set up by
+ * initializeInstrumentation(). This ensures all traces (Express, Effect, etc.)
+ * go to the same OTLP endpoint.
+ *
+ * Context Propagation:
+ * - Automatically continues traces from NodeSDK auto-instrumentation
+ * - Effect spans become children of HTTP request spans
+ * - No configuration needed
+ *
+ * @example
+ * ```typescript
+ * import { EffectInstrumentationLive } from '@atrim/instrumentation/effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   // This span continues any existing trace from NodeSDK
+ *   yield* Effect.log("Processing")
+ * }).pipe(
+ *   Effect.withSpan("app.process"),
+ *   Effect.provide(EffectInstrumentationLive)
+ * )
+ * ```
+ */
+declare const EffectInstrumentationLive: Layer.Layer<never, never, never>;
+
+/**
+ * Effect-specific span annotation helpers
+ */
+declare function annotateUser(_userId: string, _email?: string): void;
+declare function annotateDataSize(_bytes: number, _count: number): void;
+declare function annotateBatch(_size: number, _batchSize: number): void;
+declare function annotateLLM(_model: string, _operation: string, _inputTokens: number, _outputTokens: number): void;
+declare function annotateQuery(_query: string, _database: string): void;
+declare function annotateHttpRequest(_method: string, _url: string, _statusCode: number): void;
+declare function annotateError(_error: Error, _context?: Record<string, string | number | boolean>): void;
+declare function annotatePriority(_priority: string): void;
+declare function annotateCache(_operation: string, _hit: boolean): void;
+
+/**
+ * Effect metadata extraction
+ *
+ * Automatically extracts metadata from Effect fibers and adds them as span attributes.
+ * This provides valuable context about the Effect execution environment.
+ */
+/**
+ * Metadata extracted from Effect fibers
+ */
+interface EffectMetadata {
+    'effect.fiber.id'?: string;
+    'effect.fiber.status'?: string;
+    'effect.operation.root'?: boolean;
+    'effect.operation.interrupted'?: boolean;
+}
+
+/**
+ * Options for span isolation when running effects in FiberSet
+ */
+interface IsolationOptions {
+    /**
+     * Whether to create a root span (breaks parent chain)
+     * @default true (from config or this default)
+     */
+    readonly createRoot?: boolean;
+    /**
+     * Capture logical parent relationship via span links and attributes
+     * @default true
+     */
+    readonly captureLogicalParent?: boolean;
+    /**
+     * Use OpenTelemetry span links to track logical parent
+     * Works in: Honeycomb, Datadog, Lightstep, SigNoz, Splunk
+     * @default true
+     */
+    readonly useSpanLinks?: boolean;
+    /**
+     * Add custom attributes for logical parent tracking
+     * Works in: ALL observability tools (universal fallback)
+     * @default true
+     */
+    readonly useAttributes?: boolean;
+    /**
+     * Propagate interruption from parent
+     * @default undefined (FiberSet.run default behavior)
+     */
+    readonly propagateInterruption?: boolean;
+    /**
+     * Custom span attributes to add
+     */
+    readonly attributes?: Record<string, unknown>;
+    /**
+     * Span category for Atrim grouping
+     * @default "background_task"
+     */
+    readonly category?: string;
+}
+/**
+ * Run an effect in a FiberSet with automatic span isolation and virtual parent tracking.
+ *
+ * This function prevents span context leakage (fibers inheriting parent spans incorrectly)
+ * while maintaining logical parent relationships for observability.
+ *
+ * **Technical:** Uses `{ root: true }` to create independent root span
+ * **Observability:** Uses span links + attributes to track logical parent
+ *
+ * @example
+ * ```typescript
+ * import { runIsolated } from "@atrim/instrumentation/effect/fiberset"
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const set = yield* FiberSet.make()
+ *
+ *     yield* Effect.gen(function* () {
+ *       // Spawn background tasks with automatic isolation
+ *       yield* runIsolated(set, backgroundTask1(), "background-task-1")
+ *       yield* runIsolated(set, backgroundTask2(), "background-task-2")
+ *     }).pipe(
+ *       Effect.withSpan("parent-operation")
+ *     )
+ *
+ *     yield* Effect.sleep("100 millis")
+ *   })
+ * )
+ *
+ * // In Honeycomb/Datadog/SigNoz:
+ * // - background tasks are ROOT spans (no context leakage)
+ * // - span links show they were spawned by parent-operation
+ * // - can reconstruct virtual hierarchy
+ * ```
+ *
+ * @param set - The FiberSet to run the effect in
+ * @param effect - The effect to run (will be isolated)
+ * @param name - Span name for the isolated effect
+ * @param options - Configuration options
+ * @returns Effect that returns the forked fiber
+ *
+ * @see https://github.com/atrim-ai/instrumentation/issues/5
+ */
+declare const runIsolated: <A, E, R>(set: FiberSet$1.FiberSet<A, E>, effect: Effect.Effect<A, E, R>, name: string, options?: IsolationOptions) => Effect.Effect<RuntimeFiber<A, E>, never, R>;
+/**
+ * Convenience function to run an effect in a FiberSet with automatic span isolation.
+ *
+ * This is a simpler version of `runIsolated` with sensible defaults.
+ *
+ * @example
+ * ```typescript
+ * yield* runWithSpan(set, "background-task", backgroundTask(), {
+ *   attributes: { "task.priority": "high" }
+ * })
+ * ```
+ */
+declare const runWithSpan: <A, E, R>(set: FiberSet$1.FiberSet<A, E>, name: string, effect: Effect.Effect<A, E, R>, options?: {
+    readonly propagateInterruption?: boolean;
+    readonly attributes?: Record<string, unknown>;
+    readonly category?: string;
+}) => Effect.Effect<RuntimeFiber<A, E>, never, R>;
+/**
+ * Annotate the current span with metadata about spawned FiberSet tasks.
+ *
+ * Call this in the parent operation before spawning tasks to add metadata
+ * that helps reconstruct the virtual hierarchy.
+ *
+ * @example
+ * ```typescript
+ * yield* Effect.gen(function* () {
+ *   yield* annotateSpawnedTasks([
+ *     { name: "background-task-1" },
+ *     { name: "background-task-2" },
+ *     { name: "background-task-3" }
+ *   ])
+ *
+ *   yield* runIsolated(set, task1(), "background-task-1")
+ *   yield* runIsolated(set, task2(), "background-task-2")
+ *   yield* runIsolated(set, task3(), "background-task-3")
+ * }).pipe(
+ *   Effect.withSpan("parent-operation")
+ * )
+ * ```
+ */
+declare const annotateSpawnedTasks: (tasks: Array<{
+    name: string;
+    spanId?: string;
+    category?: string;
+}>) => Effect.Effect<void>;
+/**
+ * Re-export FiberSet namespace with isolation helpers
+ *
+ * This provides a convenient way to import all FiberSet functions:
+ * ```typescript
+ * import { FiberSet } from "@atrim/instrumentation/effect/fiberset"
+ * ```
+ */
+declare const FiberSet: {
+    make: <A = unknown, E = unknown>() => Effect.Effect<FiberSet$1.FiberSet<A, E>, never, effect_Scope.Scope>;
+    add: {
+        <A, E, XE extends E, XA extends A>(fiber: RuntimeFiber<XA, XE>, options?: {
+            readonly propagateInterruption?: boolean | undefined;
+        } | undefined): (self: FiberSet$1.FiberSet<A, E>) => Effect.Effect<void>;
+        <A, E, XE extends E, XA extends A>(self: FiberSet$1.FiberSet<A, E>, fiber: RuntimeFiber<XA, XE>, options?: {
+            readonly propagateInterruption?: boolean | undefined;
+        } | undefined): Effect.Effect<void>;
+    };
+    unsafeAdd: {
+        <A, E, XE extends E, XA extends A>(fiber: RuntimeFiber<XA, XE>, options?: {
+            readonly interruptAs?: effect_FiberId.FiberId | undefined;
+            readonly propagateInterruption?: boolean | undefined;
+        } | undefined): (self: FiberSet$1.FiberSet<A, E>) => void;
+        <A, E, XE extends E, XA extends A>(self: FiberSet$1.FiberSet<A, E>, fiber: RuntimeFiber<XA, XE>, options?: {
+            readonly interruptAs?: effect_FiberId.FiberId | undefined;
+            readonly propagateInterruption?: boolean | undefined;
+        } | undefined): void;
+    };
+    run: {
+        <A, E>(self: FiberSet$1.FiberSet<A, E>, options?: {
+            readonly propagateInterruption?: boolean | undefined;
+        } | undefined): <R, XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>) => Effect.Effect<RuntimeFiber<XA, XE>, never, R>;
+        <A, E, R, XE extends E, XA extends A>(self: FiberSet$1.FiberSet<A, E>, effect: Effect.Effect<XA, XE, R>, options?: {
+            readonly propagateInterruption?: boolean | undefined;
+        } | undefined): Effect.Effect<RuntimeFiber<XA, XE>, never, R>;
+    };
+    clear: <A, E>(self: FiberSet$1.FiberSet<A, E>) => Effect.Effect<void>;
+    join: <A, E>(self: FiberSet$1.FiberSet<A, E>) => Effect.Effect<void, E>;
+    awaitEmpty: <A, E>(self: FiberSet$1.FiberSet<A, E>) => Effect.Effect<void>;
+    size: <A, E>(self: FiberSet$1.FiberSet<A, E>) => Effect.Effect<number>;
+    runtime: <A, E>(self: FiberSet$1.FiberSet<A, E>) => <R = never>() => Effect.Effect<(<XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: (effect_Runtime.RunForkOptions & {
+        readonly propagateInterruption?: boolean | undefined;
+    }) | undefined) => RuntimeFiber<XA, XE>), never, R>;
+    runtimePromise: <A, E>(self: FiberSet$1.FiberSet<A, E>) => <R = never>() => Effect.Effect<(<XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: (effect_Runtime.RunForkOptions & {
+        readonly propagateInterruption?: boolean | undefined;
+    }) | undefined) => Promise<XA>), never, R>;
+    makeRuntime: <R = never, A = unknown, E = unknown>() => Effect.Effect<(<XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: effect_Runtime.RunForkOptions | undefined) => RuntimeFiber<XA, XE>), never, effect_Scope.Scope | R>;
+    makeRuntimePromise: <R = never, A = unknown, E = unknown>() => Effect.Effect<(<XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: effect_Runtime.RunForkOptions | undefined) => Promise<XA>), never, effect_Scope.Scope | R>;
+    isFiberSet: (u: unknown) => u is FiberSet$1.FiberSet<unknown, unknown>;
+    runIsolated: <A, E, R>(set: FiberSet$1.FiberSet<A, E>, effect: Effect.Effect<A, E, R>, name: string, options?: IsolationOptions) => Effect.Effect<RuntimeFiber<A, E>, never, R>;
+    runWithSpan: <A, E, R>(set: FiberSet$1.FiberSet<A, E>, name: string, effect: Effect.Effect<A, E, R>, options?: {
+        readonly propagateInterruption?: boolean;
+        readonly attributes?: Record<string, unknown>;
+        readonly category?: string;
+    }) => Effect.Effect<RuntimeFiber<A, E>, never, R>;
+};
+
+export { EffectInstrumentationLive, type EffectMetadata, FiberSet, type IsolationOptions, annotateBatch, annotateCache, annotateDataSize, annotateError, annotateHttpRequest, annotateLLM, annotatePriority, annotateQuery, annotateSpawnedTasks, annotateUser, createEffectInstrumentation, runIsolated, runWithSpan };