@atrim/instrument-node 0.5.1-1451fcf-20260105212505 → 0.5.1-21bb978-20260105202350

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

@@ -1,4 +1,6 @@
-import { Layer, Tracer, Effect, FiberSet as FiberSet$1 } 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';
@@ -132,7 +134,135 @@ declare function createEffectInstrumentation(options?: EffectInstrumentationOpti
  * )
  * ```
  */
-declare const EffectInstrumentationLive: Layer.Layer<Tracer.Tracer, 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
@@ -525,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, autoEnrichSpan, createEffectInstrumentation, extractEffectMetadata, runIsolated, runWithSpan, withAutoEnrichedSpan };
+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 };

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

@@ -1,4 +1,6 @@
-import { Layer, Tracer, Effect, FiberSet as FiberSet$1 } 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';
@@ -132,7 +134,135 @@ declare function createEffectInstrumentation(options?: EffectInstrumentationOpti
  * )
  * ```
  */
-declare const EffectInstrumentationLive: Layer.Layer<Tracer.Tracer, 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
@@ -525,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, autoEnrichSpan, createEffectInstrumentation, extractEffectMetadata, runIsolated, runWithSpan, withAutoEnrichedSpan };
+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 };

package/target/dist/integrations/effect/index.js

@@ -1,9 +1,9 @@
-import { Data, Context, Effect, Layer, Tracer, FiberSet as FiberSet$1, Fiber, Option, FiberId } from 'effect';
-import * as OtelTracer from '@effect/opentelemetry/Tracer';
+import { Data, Context, Effect, Layer, FiberSet as FiberSet$1, Fiber, Option, FiberId, Tracer as Tracer$1 } from 'effect';
+import * as Tracer from '@effect/opentelemetry/Tracer';
 import * as Resource from '@effect/opentelemetry/Resource';
 import * as Otlp from '@effect/opentelemetry/Otlp';
 import { FetchHttpClient } from '@effect/platform';
-import { TraceFlags, trace, context } from '@opentelemetry/api';
+import { trace, context, TraceFlags } from '@opentelemetry/api';
 import { TELEMETRY_SDK_LANGUAGE_VALUE_NODEJS, ATTR_TELEMETRY_SDK_NAME, ATTR_TELEMETRY_SDK_LANGUAGE } from '@opentelemetry/semantic-conventions';
 import { FileSystem } from '@effect/platform/FileSystem';
 import * as HttpClient from '@effect/platform/HttpClient';
@@ -81,6 +81,11 @@ var InstrumentationConfigSchema = z.object({
     // - "standalone": Use Effect's own OTLP exporter (bypasses Node SDK filtering)
     exporter: z.enum(["unified", "standalone"]).default("unified"),
     auto_extract_metadata: z.boolean(),
+    // Auto-bridge OpenTelemetry context to Effect spans
+    // When true, Effect spans automatically become children of the active OTel span
+    // (e.g., HTTP request span from auto-instrumentation)
+    // This is essential for proper trace hierarchy when using Effect with HTTP frameworks
+    auto_bridge_context: z.boolean().default(true),
     auto_isolation: AutoIsolationConfigSchema.optional()
   }).optional(),
   http: HttpFilteringConfigSchema.optional()
@@ -105,7 +110,8 @@ var defaultConfig = {
   effect: {
     enabled: true,
     exporter: "unified",
-    auto_extract_metadata: true
+    auto_extract_metadata: true,
+    auto_bridge_context: true
   }
 };
 function parseAndValidateConfig(content) {
@@ -494,21 +500,6 @@ async function loadConfigWithOptions(options = {}) {
 // src/integrations/effect/effect-tracer.ts
 var SDK_NAME = "@effect/opentelemetry";
 var ATTR_TELEMETRY_EXPORTER_MODE = "telemetry.exporter.mode";
-var ATTR_EFFECT_INSTRUMENTED = "effect.instrumented";
-var EffectAttributeTracerLayer = Layer.effect(
-  Tracer.Tracer,
-  Effect.gen(function* () {
-    const baseTracer = yield* OtelTracer.make;
-    return Tracer.make({
-      span: (name, parent, context2, links, startTime, kind, options) => {
-        const span = baseTracer.span(name, parent, context2, links, startTime, kind, options);
-        span.attribute(ATTR_EFFECT_INSTRUMENTED, true);
-        return span;
-      },
-      context: (f, fiber) => baseTracer.context(f, fiber)
-    });
-  }).pipe(Effect.provide(OtelTracer.layerGlobalTracer))
-);
 function createEffectInstrumentation(options = {}) {
   return Layer.unwrapEffect(
     Effect.gen(function* () {
@@ -569,7 +560,7 @@ function createEffectInstrumentation(options = {}) {
         logger.log("Effect OpenTelemetry instrumentation (unified)");
         logger.log(`  Service: ${serviceName}`);
         logger.log("  Using global TracerProvider for span export");
-        return EffectAttributeTracerLayer.pipe(
+        return Tracer.layerGlobal.pipe(
           Layer.provide(
             Resource.layer({
               serviceName,
@@ -588,7 +579,7 @@ var EffectInstrumentationLive = Effect.sync(() => {
   logger.minimal(`@atrim/instrumentation/effect: Effect tracing enabled (${serviceName})`);
   logger.log("Effect OpenTelemetry tracer (unified)");
   logger.log(`  Service: ${serviceName}`);
-  return EffectAttributeTracerLayer.pipe(
+  return Tracer.layerGlobal.pipe(
     Layer.provide(
       Resource.layer({
         serviceName,
@@ -603,6 +594,55 @@ var EffectInstrumentationLive = Effect.sync(() => {
     )
   );
 }).pipe(Layer.unwrapEffect);
+var withOtelParentSpan = (effect) => {
+  const currentSpan = trace.getSpan(context.active());
+  if (currentSpan) {
+    const spanContext = currentSpan.spanContext();
+    return Tracer.withSpanContext(spanContext)(effect);
+  }
+  return effect;
+};
+var getCurrentOtelSpanContext = Effect.sync(() => {
+  const currentSpan = trace.getSpan(context.active());
+  return currentSpan?.spanContext();
+});
+var getOtelParentSpan = Effect.sync(
+  () => {
+    const currentSpan = trace.getSpan(context.active());
+    if (!currentSpan) {
+      return void 0;
+    }
+    const spanContext = currentSpan.spanContext();
+    return Tracer.makeExternalSpan({
+      traceId: spanContext.traceId,
+      spanId: spanContext.spanId,
+      traceFlags: spanContext.traceFlags,
+      traceState: spanContext.traceState?.serialize()
+    });
+  }
+);
+var runWithOtelContext = (effect) => {
+  return Effect.flatMap(
+    Tracer.currentOtelSpan,
+    (otelSpan) => Effect.async((resume) => {
+      context.with(trace.setSpan(context.active(), otelSpan), () => {
+        Effect.runPromiseExit(effect).then((exit) => {
+          if (exit._tag === "Success") {
+            resume(Effect.succeed(exit.value));
+          } else {
+            resume(Effect.failCause(exit.cause));
+          }
+        });
+      });
+    })
+  ).pipe(
+    // If no OTel span is available, just run the effect normally
+    Effect.catchAll(() => effect)
+  );
+};
+var withFullOtelBridging = (effect) => {
+  return withOtelParentSpan(effect);
+};
 function annotateUser(userId, email, username) {
   const attributes = {
     "user.id": userId
@@ -790,7 +830,7 @@ var runIsolated = (set, effect, name, options) => {
     return FiberSet$1.run(set, effect, { propagateInterruption });
   }
   return Effect.gen(function* () {
-    const maybeParent = yield* Effect.serviceOption(Tracer.ParentSpan);
+    const maybeParent = yield* Effect.serviceOption(Tracer$1.ParentSpan);
     if (maybeParent._tag === "None" || !captureLogicalParent) {
       const isolated2 = effect.pipe(
         Effect.withSpan(name, {
@@ -867,6 +907,6 @@ var FiberSet = {
   runWithSpan
 };
 
-export { EffectInstrumentationLive, FiberSet, annotateBatch, annotateCache, annotateDataSize, annotateError, annotateHttpRequest, annotateLLM, annotatePriority, annotateQuery, annotateSpawnedTasks, annotateUser, autoEnrichSpan, createEffectInstrumentation, extractEffectMetadata, runIsolated, runWithSpan, withAutoEnrichedSpan };
+export { EffectInstrumentationLive, FiberSet, annotateBatch, annotateCache, annotateDataSize, annotateError, annotateHttpRequest, annotateLLM, annotatePriority, annotateQuery, annotateSpawnedTasks, annotateUser, autoEnrichSpan, createEffectInstrumentation, extractEffectMetadata, getCurrentOtelSpanContext, getOtelParentSpan, runIsolated, runWithOtelContext, runWithSpan, withAutoEnrichedSpan, withFullOtelBridging, withOtelParentSpan };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map