@atrim/instrument-node 0.5.0 → 0.5.1-21bb978-20260105202350

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

@@ -1,4 +1,6 @@
-import { Layer, FiberSet as FiberSet$1, Effect } from 'effect';
+import { Layer, Effect, Tracer as Tracer$1, FiberSet as FiberSet$1 } from 'effect';
+import * as Tracer from '@effect/opentelemetry/Tracer';
+import { SpanContext } from '@opentelemetry/api';
 import { InstrumentationConfig } from '@atrim/instrument-core';
 import * as effect_Runtime from 'effect/Runtime';
 import * as effect_FiberId from 'effect/FiberId';
@@ -6,9 +8,10 @@ import * as effect_Scope from 'effect/Scope';
 import { RuntimeFiber } from 'effect/Fiber';
 
 /**
- * Node.js configuration loader using Effect Platform
+ * Node.js configuration loader
  *
- * Provides FileSystem and HttpClient layers for the core ConfigLoader service
+ * Provides configuration loading using native Node.js APIs (fs, fetch)
+ * This module doesn't require Effect Platform, making it work without Effect installed.
  */
 
 /**
@@ -46,17 +49,12 @@ interface ConfigLoaderOptions {
  */
 interface EffectInstrumentationOptions extends ConfigLoaderOptions {
     /**
-     * OTLP endpoint URL
-     * @default process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318'
-     */
-    otlpEndpoint?: string;
-    /**
-     * Service name
+     * Service name for Effect spans
      * @default process.env.OTEL_SERVICE_NAME || 'effect-service'
      */
     serviceName?: string;
     /**
-     * Service version
+     * Service version for Effect spans
      * @default process.env.npm_package_version || '1.0.0'
      */
     serviceVersion?: string;
@@ -66,20 +64,17 @@ interface EffectInstrumentationOptions extends ConfigLoaderOptions {
      */
     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
+     * OTLP endpoint URL (only used when exporter mode is 'standalone')
+     * @default process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318'
+     */
+    otlpEndpoint?: string;
+    /**
+     * Exporter mode:
+     * - 'unified': Use global TracerProvider from Node SDK (recommended, enables filtering)
+     * - 'standalone': Use Effect's own OTLP exporter (bypasses Node SDK filtering)
+     * @default 'unified'
      */
-    continueExistingTraces?: boolean;
+    exporterMode?: 'unified' | 'standalone';
 }
 /**
  * Create Effect instrumentation layer with custom options
@@ -118,11 +113,12 @@ declare function createEffectInstrumentation(options?: EffectInstrumentationOpti
  *
  * 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.
+ * go through the same TracerProvider and PatternSpanProcessor.
  *
  * Context Propagation:
  * - Automatically continues traces from NodeSDK auto-instrumentation
  * - Effect spans become children of HTTP request spans
+ * - Respects http.ignore_incoming_paths and other filtering patterns
  * - No configuration needed
  *
  * @example
@@ -138,27 +134,243 @@ declare function createEffectInstrumentation(options?: EffectInstrumentationOpti
  * )
  * ```
  */
-declare const EffectInstrumentationLive: Layer.Layer<never, never, never>;
+declare const EffectInstrumentationLive: Layer.Layer<Tracer.OtelTracer, never, never>;
+/**
+ * Bridge the current OpenTelemetry span context to Effect's tracer.
+ *
+ * Use this when running Effect code inside an HTTP handler that was
+ * auto-instrumented by OpenTelemetry. This ensures Effect spans become
+ * children of the HTTP span rather than starting a new trace.
+ *
+ * @example
+ * ```typescript
+ * // In an Express handler
+ * app.get('/api/users', async (req, res) => {
+ *   const program = fetchUsers().pipe(
+ *     Effect.withSpan('api.fetchUsers'),
+ *     withOtelParentSpan,  // Bridge to HTTP span
+ *     Effect.provide(EffectInstrumentationLive)
+ *   )
+ *   const result = await Effect.runPromise(program)
+ *   res.json(result)
+ * })
+ * ```
+ *
+ * Without this utility, Effect spans would start a new trace instead of
+ * continuing the HTTP request trace, resulting in disconnected spans.
+ *
+ * @param effect - The Effect to run with the current OTel span as parent
+ * @returns The same Effect with OTel parent span context attached
+ */
+declare const withOtelParentSpan: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+/**
+ * Create an Effect that gets the current OpenTelemetry span context.
+ *
+ * This is useful when you need to access the current span context for
+ * custom propagation or logging purposes.
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const spanContext = yield* getCurrentOtelSpanContext
+ *   if (spanContext) {
+ *     console.log('Current trace:', spanContext.traceId)
+ *   }
+ * })
+ * ```
+ *
+ * @returns Effect that yields the current SpanContext or undefined if none
+ */
+declare const getCurrentOtelSpanContext: Effect.Effect<SpanContext | undefined>;
+/**
+ * Create an external span reference from the current OpenTelemetry context.
+ *
+ * This creates an Effect ExternalSpan that can be used as a parent for
+ * Effect spans. Useful when you need more control over span parenting.
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const parentSpan = yield* getOtelParentSpan
+ *   if (parentSpan) {
+ *     yield* myOperation.pipe(
+ *       Effect.withSpan('child.operation', { parent: parentSpan })
+ *     )
+ *   }
+ * })
+ * ```
+ *
+ * @returns Effect that yields an ExternalSpan or undefined if no active span
+ */
+declare const getOtelParentSpan: Effect.Effect<Tracer$1.ExternalSpan | undefined>;
+/**
+ * Run an async operation with the current Effect span set as the active OTel span.
+ *
+ * Use this when calling async code that uses OTel auto-instrumentation
+ * (e.g., fetch, database drivers) from within an Effect span. This ensures
+ * the auto-instrumented spans become children of the Effect span.
+ *
+ * @example
+ * ```typescript
+ * const fetchData = Effect.gen(function* () {
+ *   // This fetch call will have the Effect span as its parent
+ *   const result = yield* runWithOtelContext(
+ *     Effect.tryPromise(() => fetch('https://api.example.com/data'))
+ *   )
+ *   return result
+ * }).pipe(Effect.withSpan('fetch.data'))
+ * ```
+ *
+ * Note: This is most useful when you need OTel auto-instrumentation (HTTP, DB)
+ * to see Effect spans as parents. For Effect-only code, this isn't needed.
+ *
+ * @param effect - The Effect containing async operations with OTel auto-instrumentation
+ * @returns The same Effect but with OTel context propagation during execution
+ */
+declare const runWithOtelContext: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+/**
+ * Higher-order function to create an Effect that bridges both directions:
+ * 1. Captures active OTel span as Effect's parent (OTel → Effect)
+ * 2. Sets Effect span as active OTel span during execution (Effect → OTel)
+ *
+ * This is the recommended way to run Effect code in HTTP handlers when you need
+ * full bidirectional tracing with OTel auto-instrumentation.
+ *
+ * @example
+ * ```typescript
+ * // In an Express handler
+ * app.get('/api/users', async (req, res) => {
+ *   const program = Effect.gen(function* () {
+ *     // Effect spans are children of HTTP request span
+ *     const users = yield* fetchUsersFromDb()
+ *
+ *     // HTTP client spans (from fetch) are children of Effect span
+ *     yield* notifyExternalService(users)
+ *
+ *     return users
+ *   }).pipe(
+ *     Effect.withSpan('api.getUsers'),
+ *     withFullOtelBridging,  // Bidirectional bridging
+ *     Effect.provide(EffectInstrumentationLive)
+ *   )
+ *
+ *   const result = await Effect.runPromise(program)
+ *   res.json(result)
+ * })
+ * ```
+ *
+ * @param effect - The Effect to run with full OTel bridging
+ * @returns Effect with bidirectional OTel context bridging
+ */
+declare const withFullOtelBridging: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
 
 /**
  * Effect-specific span annotation helpers
+ *
+ * Provides reusable helper functions for adding common span attributes.
+ * These helpers follow OpenTelemetry semantic conventions and platform patterns.
+ *
+ * Usage:
+ * ```typescript
+ * Effect.gen(function* () {
+ *   yield* annotateUser(userId, email)
+ *   yield* annotateBatch(items.length, 5)
+ *   const results = yield* storage.writeBatch(items)
+ *   yield* annotateBatch(items.length, 5, results.success, results.failures)
+ * }).pipe(Effect.withSpan('storage.writeBatch'))
+ * ```
  */
-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;
+
+/**
+ * Annotate span with user context
+ *
+ * @param userId - User identifier
+ * @param email - Optional user email
+ * @param username - Optional username
+ */
+declare function annotateUser(userId: string, email?: string, username?: string): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with data size metrics
+ *
+ * @param bytes - Total bytes processed
+ * @param items - Number of items
+ * @param compressionRatio - Optional compression ratio
+ */
+declare function annotateDataSize(bytes: number, items: number, compressionRatio?: number): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with batch operation metadata
+ *
+ * @param totalItems - Total number of items in batch
+ * @param batchSize - Size of each batch
+ * @param successCount - Optional number of successful items
+ * @param failureCount - Optional number of failed items
+ */
+declare function annotateBatch(totalItems: number, batchSize: number, successCount?: number, failureCount?: number): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with LLM operation metadata
+ *
+ * @param model - Model name (e.g., 'gpt-4', 'claude-3-opus')
+ * @param provider - LLM provider (e.g., 'openai', 'anthropic')
+ * @param tokens - Optional token usage information
+ */
+declare function annotateLLM(model: string, provider: string, tokens?: {
+    prompt?: number;
+    completion?: number;
+    total?: number;
+}): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with database query metadata
+ *
+ * @param query - SQL query or query description
+ * @param duration - Optional query duration in milliseconds
+ * @param rowCount - Optional number of rows returned/affected
+ * @param database - Optional database name
+ */
+declare function annotateQuery(query: string, duration?: number, rowCount?: number, database?: string): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with HTTP request metadata
+ *
+ * @param method - HTTP method (GET, POST, etc.)
+ * @param url - Request URL
+ * @param statusCode - Optional HTTP status code
+ * @param contentLength - Optional response content length
+ */
+declare function annotateHttpRequest(method: string, url: string, statusCode?: number, contentLength?: number): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with error context
+ *
+ * @param error - Error object or message
+ * @param recoverable - Whether the error is recoverable
+ * @param errorType - Optional error type/category
+ */
+declare function annotateError(error: Error | string, recoverable: boolean, errorType?: string): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with operation priority
+ *
+ * @param priority - Priority level (high, medium, low)
+ * @param reason - Optional reason for priority level
+ */
+declare function annotatePriority(priority: 'high' | 'medium' | 'low', reason?: string): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with cache operation metadata
+ *
+ * @param hit - Whether the cache was hit
+ * @param key - Cache key
+ * @param ttl - Optional time-to-live in seconds
+ */
+declare function annotateCache(hit: boolean, key: string, ttl?: number): Effect.Effect<void, never, never>;
 
 /**
  * Effect metadata extraction
  *
  * Automatically extracts metadata from Effect fibers and adds them as span attributes.
  * This provides valuable context about the Effect execution environment.
+ *
+ * Uses Effect's public APIs:
+ * - Fiber.getCurrentFiber() - Get current fiber information
+ * - Effect.currentSpan - Detect parent spans and nesting
  */
+
 /**
  * Metadata extracted from Effect fibers
  */
@@ -166,8 +378,95 @@ interface EffectMetadata {
     'effect.fiber.id'?: string;
     'effect.fiber.status'?: string;
     'effect.operation.root'?: boolean;
-    'effect.operation.interrupted'?: boolean;
+    'effect.operation.nested'?: boolean;
+    'effect.parent.span.id'?: string;
+    'effect.parent.span.name'?: string;
+    'effect.parent.trace.id'?: string;
 }
+/**
+ * Extract Effect-native metadata from current execution context
+ *
+ * Uses Effect's native APIs:
+ * - Fiber.getCurrentFiber() - Get current fiber information
+ * - Effect.currentSpan - Detect parent spans and nesting
+ *
+ * @returns Effect that yields extracted metadata
+ */
+declare function extractEffectMetadata(): Effect.Effect<EffectMetadata>;
+
+/**
+ * Effect Auto-Enrichment Utilities
+ *
+ * Provides utilities for automatically extracting and enriching spans with Effect-native metadata.
+ *
+ * Usage:
+ * ```typescript
+ * import { autoEnrichSpan, withAutoEnrichedSpan } from '@atrim/instrument-node/effect'
+ *
+ * // Option 1: Manual enrichment
+ * Effect.gen(function* () {
+ *   yield* autoEnrichSpan()  // Auto-add Effect metadata
+ *   yield* annotateBatch(items.length, 10)  // Add custom attributes
+ *   const result = yield* storage.writeBatch(items)
+ *   return result
+ * }).pipe(Effect.withSpan('storage.writeBatch'))
+ *
+ * // Option 2: Automatic enrichment wrapper
+ * const instrumented = withAutoEnrichedSpan('storage.writeBatch')(
+ *   Effect.gen(function* () {
+ *     yield* annotateBatch(items.length, 10)
+ *     return yield* storage.writeBatch(items)
+ *   })
+ * )
+ * ```
+ */
+
+/**
+ * Auto-enrich the current span with Effect metadata
+ *
+ * This function should be called within an Effect.withSpan() context.
+ * It extracts Effect metadata (fiber ID, status, parent span info)
+ * and adds it as span attributes.
+ *
+ * Best practice: Call this at the start of your instrumented Effect:
+ *
+ * ```typescript
+ * Effect.gen(function* () {
+ *   yield* autoEnrichSpan()  // Auto-add metadata
+ *   yield* annotateBatch(items.length, 10)  // Add custom attributes
+ *   const result = yield* storage.writeBatch(items)
+ *   return result
+ * }).pipe(Effect.withSpan('storage.writeBatch'))
+ * ```
+ *
+ * @returns Effect that annotates the current span with Effect metadata
+ */
+declare function autoEnrichSpan(): Effect.Effect<void>;
+/**
+ * Create a wrapper that combines Effect.withSpan with automatic enrichment
+ *
+ * This is a convenience function that wraps an Effect with both:
+ * 1. A span (via Effect.withSpan)
+ * 2. Automatic metadata extraction (via autoEnrichSpan)
+ *
+ * Usage:
+ * ```typescript
+ * const instrumented = withAutoEnrichedSpan('storage.writeBatch')(
+ *   Effect.gen(function* () {
+ *     yield* annotateBatch(items.length, 10)
+ *     return yield* storage.writeBatch(items)
+ *   })
+ * )
+ * ```
+ *
+ * @param spanName - The name of the span
+ * @param options - Optional span options
+ * @returns Function that wraps an Effect with an auto-enriched span
+ */
+declare function withAutoEnrichedSpan<A, E, R>(spanName: string, options?: {
+    readonly attributes?: Record<string, unknown>;
+    readonly kind?: 'client' | 'server' | 'producer' | 'consumer' | 'internal';
+}): (self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
 
 /**
  * Options for span isolation when running effects in FiberSet
@@ -356,4 +655,4 @@ declare const FiberSet: {
     }) => 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 };
+export { EffectInstrumentationLive, type EffectMetadata, FiberSet, type IsolationOptions, annotateBatch, annotateCache, annotateDataSize, annotateError, annotateHttpRequest, annotateLLM, annotatePriority, annotateQuery, annotateSpawnedTasks, annotateUser, autoEnrichSpan, createEffectInstrumentation, extractEffectMetadata, getCurrentOtelSpanContext, getOtelParentSpan, runIsolated, runWithOtelContext, runWithSpan, withAutoEnrichedSpan, withFullOtelBridging, withOtelParentSpan };