feat(opentelemetry): add withActiveSpan function to attach Effect to current Span

.changeset/gorgeous-llamas-invent.md

@@ -0,0 +1,19 @@
+---
+"@effect/opentelemetry": patch
+---
+
+add withActiveSpan function to attach Effect to current Span
+
+This function allows you to connect the Effect spans into a parent span
+that was created outside of Effect, using the OpenTelemetry context propagation:
+
+```ts
+Effect.gen(function*() {
+  yield* Effect.sleep("100 millis").pipe(Effect.withSpan("sleep"));
+  yield* Console.log("done");
+}).pipe(
+  Effect.withSpan("program"),
+  // This connects child spans to the current OpenTelemetry context
+  Tracer.withActiveSpan,
+)
+```

packages/opentelemetry/src/Tracer.ts

@@ -82,3 +82,15 @@ export const TraceFlags: Tag<Otel.TraceFlags, Otel.TraceFlags> = internal.traceF
  * @category tags
  */
 export const TraceState: Tag<Otel.TraceState, Otel.TraceState> = internal.traceStateTag
+
+/**
+ * Attach the provided Effect to the current Span as reported from OpenTelemetry's
+ * context propagation.
+ *
+ * This is handy when you set up OpenTelemetry outside of Effect and want to
+ * attach to a parent span.
+ *
+ * @since 0.37.5
+ * @category effects
+ */
+export const withActiveSpan: <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R> = internal.withActiveSpan

packages/opentelemetry/src/internal/tracer.ts

@@ -304,3 +304,13 @@ const unknownToAttributeValue = (value: unknown): OtelApi.AttributeValue => {
   }
   return Inspectable.toStringUnknown(value)
 }
+
+export const withActiveSpan = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+  Effect.suspend(() => {
+    const activeSpan = OtelApi.trace.getActiveSpan()
+    if (!activeSpan) {
+      return effect
+    }
+    const span = makeExternalSpan(activeSpan.spanContext())
+    return Effect.withParentSpan(effect, span)
+  })

packages/opentelemetry/test/Tracer.test.ts

@@ -1,10 +1,11 @@
-import { currentOtelSpan, OtelSpan } from "@effect/opentelemetry/internal/tracer"
+import { currentOtelSpan, OtelSpan, withActiveSpan } from "@effect/opentelemetry/internal/tracer"
 import * as NodeSdk from "@effect/opentelemetry/NodeSdk"
 import * as it from "@effect/vitest"
 import * as OtelApi from "@opentelemetry/api"
 import { AsyncHooksContextManager } from "@opentelemetry/context-async-hooks"
 import { InMemorySpanExporter, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base"
 import * as Effect from "effect/Effect"
+import * as Runtime from "effect/Runtime"
 import { assert, describe, expect } from "vitest"
 
 const TracingLive = NodeSdk.layer(Effect.sync(() => ({
@@ -76,6 +77,36 @@ describe("Tracer", () => {
         ),
         TracingLive
       ))
+
+    it.scoped("withActiveSpan", () =>
+      Effect.gen(function*() {
+        const effect = Effect.gen(function*() {
+          const span = yield* Effect.currentParentSpan
+          assert(span._tag === "Span")
+          const parent = yield* span.parent
+          return parent
+        }).pipe(Effect.withSpan("child"), withActiveSpan)
+
+        const runtime = yield* Effect.runtime()
+
+        yield* Effect.promise(async () => {
+          await OtelApi.trace.getTracer("test").startActiveSpan("otel-span", {
+            root: true,
+            attributes: { "root": "yes" }
+          }, async (span) => {
+            try {
+              const parent = await Runtime.runPromise(runtime)(effect)
+              const { spanId, traceId } = span.spanContext()
+              expect(parent).toMatchObject({
+                spanId,
+                traceId
+              })
+            } finally {
+              span.end()
+            }
+          })
+        })
+      }).pipe(Effect.provide(TracingLive)))
   })
 
   describe("not provided", () => {