Guidance on interop between Effect OTLP tracer and @opentelemetry/api Tracer?

[schickling]

Hi! We're using Effect's OTLP tracer (@effect/opentelemetry/Otlp) but also need an @opentelemetry/api Tracer for libraries expecting the OTel API. We're currently bridging the Effect tracer to an OTel API tracer with a custom adapter and using it as a workaround.

Question: Is there an official/idiomatic way to get interop between Effect's tracer (Otlp/OtelTracer) and the @opentelemetry/api tracer? Any recommended patterns or utilities to avoid maintaining a custom adapter?

Workaround (abridged):

const makeOtelEffectBridgeLayer = ({ baseUrl, serviceName, tracerExportInterval = 500 }) => {
  const otlpLayer = baseUrl
    ? Otlp.layer({ baseUrl, resource: { serviceName }, tracerExportInterval })
    : Layer.empty

  const otelAdapterLayer = Layer.effect(
    OtelTracer.OtelTracer,
    Effect.gen(function* () {
      const otlpTracer = yield* Effect.tracer
      return makeOtelTracerAdapter(otlpTracer)
    }),
  ).pipe(Layer.provide(otlpLayer))

  const otelEffectTracerLayer = Layer.unwrapEffect(Effect.map(OtelTracer.make, Layer.setTracer)).pipe(
    Layer.provide(otelAdapterLayer),
  )

  return otelEffectTracerLayer.pipe(Layer.provideMerge(otelAdapterLayer))
}

makeOtelTracerAdapter maps OTel API spans to Effect spans (parent context, links, attributes, timestamps). We're happy to share full code if useful.

Thanks!

[schickling]

Adding the full workaround code below for context.

Full workaround code

import * as Otlp from '@effect/opentelemetry/Otlp'
import * as otel from '@opentelemetry/api'
import { shouldNeverHappen } from '@overtone/utils'
import { Context, Effect, Exit, type HttpClient, Layer, Option, OtelTracer, Tracer } from '@overtone/utils/effect'

const effectSpanSymbol = Symbol('overtone.effectSpan')

type OtelSpanAdapter = otel.Span & { [effectSpanSymbol]: Tracer.Span }

const isTimeInput = (value: unknown): value is otel.TimeInput =>
  typeof value === 'number' || value instanceof Date || (Array.isArray(value) && value.length === 2)

const toEpochNanos = (time?: otel.TimeInput): bigint => {
  if (time === undefined) {
    return BigInt(Date.now()) * 1_000_000n
  }

  if (typeof time === 'number') {
    return BigInt(Math.floor(time)) * 1_000_000n
  }

  if (time instanceof Date) {
    return BigInt(time.getTime()) * 1_000_000n
  }

  const [seconds, nanos] = time
  return BigInt(seconds) * 1_000_000_000n + BigInt(nanos)
}

const toEffectSpanKind = (kind: otel.SpanKind | undefined): Tracer.SpanKind => {
  switch (kind) {
    case otel.SpanKind.SERVER:
      return 'server'
    case otel.SpanKind.CLIENT:
      return 'client'
    case otel.SpanKind.PRODUCER:
      return 'producer'
    case otel.SpanKind.CONSUMER:
      return 'consumer'
    // case otel.SpanKind.INTERNAL:
    default:
      return 'internal'
  }
}

const toEffectExternalSpan = (context: otel.SpanContext): Tracer.ExternalSpan =>
  Tracer.externalSpan({
    traceId: context.traceId,
    spanId: context.spanId,
    sampled: (context.traceFlags & otel.TraceFlags.SAMPLED) === otel.TraceFlags.SAMPLED,
    context: Context.empty(),
  })

const toEffectSpanLink = (link: otel.Link): Tracer.SpanLink => ({
  _tag: 'SpanLink',
  span: toEffectExternalSpan(link.context),
  attributes: link.attributes ?? {},
})

const toAttributesRecord = (attributes: otel.Attributes | undefined): Record<string, unknown> | undefined => {
  if (!attributes) return
  const record: Record<string, unknown> = {}
  for (const [key, value] of Object.entries(attributes)) {
    record[key] = value
  }
  return record
}

const makeOtelSpan = (span: Tracer.Span): OtelSpanAdapter => {
  const otelSpan: OtelSpanAdapter = {
    [effectSpanSymbol]: span,
    spanContext: () => ({
      traceId: span.traceId,
      spanId: span.spanId,
      traceFlags: span.sampled ? otel.TraceFlags.SAMPLED : otel.TraceFlags.NONE,
      isRemote: false,
    }),
    setAttribute: (key: string, value: otel.AttributeValue) => {
      span.attribute(key, value)
      return otelSpan
    },
    setAttributes: (attributes: otel.Attributes) => {
      for (const [key, value] of Object.entries(attributes ?? {})) {
        span.attribute(key, value)
      }
      return otelSpan
    },
    addEvent: (name: string, attributesOrTime?: otel.Attributes | otel.TimeInput, time?: otel.TimeInput) => {
      const attributes = isTimeInput(attributesOrTime) ? undefined : attributesOrTime
      const eventTime = isTimeInput(attributesOrTime) ? attributesOrTime : time
      span.event(name, toEpochNanos(eventTime), toAttributesRecord(attributes))
      return otelSpan
    },
    addLink: (link: otel.Link) => {
      span.addLinks([toEffectSpanLink(link)])
      return otelSpan
    },
    addLinks: (links: otel.Link[]) => {
      span.addLinks(links.map(toEffectSpanLink))
      return otelSpan
    },
    setStatus: (_status: otel.SpanStatus) => otelSpan,
    updateName: (_name: string) => otelSpan,
    recordException: (_exception: otel.Exception | string, _time?: otel.TimeInput) => otelSpan,
    end: (time?: otel.TimeInput) => {
      span.end(toEpochNanos(time), Exit.succeed(undefined))
    },
    isRecording: () => true,
  }

  return otelSpan
}

const isOtelSpanAdapter = (span: otel.Span): span is OtelSpanAdapter => effectSpanSymbol in span

const toEffectParentSpan = (span: otel.Span | undefined): Option.Option<Tracer.AnySpan> => {
  if (!span) return Option.none()
  if (isOtelSpanAdapter(span)) {
    return Option.some(span[effectSpanSymbol])
  }
  return Option.some(toEffectExternalSpan(span.spanContext()))
}

const makeOtelTracerAdapter = (tracer: Tracer.Tracer): otel.Tracer => {
  const startSpan: otel.Tracer['startSpan'] = (
    name: string,
    options?: otel.SpanOptions,
    context: otel.Context = otel.context.active(),
  ) => {
    const parentSpan = options?.root === true ? Option.none() : toEffectParentSpan(otel.trace.getSpan(context))
    const links = options?.links?.map(toEffectSpanLink) ?? []

    const effectSpan = tracer.span(
      name,
      parentSpan,
      Context.empty(),
      links,
      toEpochNanos(),
      toEffectSpanKind(options?.kind),
      { attributes: toAttributesRecord(options?.attributes) },
    )

    return makeOtelSpan(effectSpan)
  }

  const startActiveSpan: otel.Tracer['startActiveSpan'] = (
    name: string,
    optionsOrFn: otel.SpanOptions | ((span: otel.Span) => unknown),
    contextOrFn?: otel.Context | ((span: otel.Span) => unknown),
    fn?: (span: otel.Span) => unknown,
  ) => {
    if (typeof optionsOrFn === 'function') {
      const span = startSpan(name)
      return otel.context.with(otel.trace.setSpan(otel.context.active(), span), () => optionsOrFn(span))
    }

    if (typeof contextOrFn === 'function') {
      const span = startSpan(name, optionsOrFn)
      return otel.context.with(otel.trace.setSpan(otel.context.active(), span), () => contextOrFn(span))
    }

    if (!fn) {
      return shouldNeverHappen('startActiveSpan callback is missing')
    }

    const span = startSpan(name, optionsOrFn, contextOrFn)
    const activeContext = contextOrFn ?? otel.context.active()

    return otel.context.with(otel.trace.setSpan(activeContext, span), () => fn(span))
  }

  return { startSpan, startActiveSpan }
}

/**
 * Create a bridge layer that keeps the OTLP Effect tracer and exposes an OpenTelemetry tracer adapter.
 */
export const makeOtelEffectBridgeLayer = ({
  baseUrl,
  serviceName,
  tracerExportInterval = 500,
}: {
  baseUrl?: string
  serviceName: string
  tracerExportInterval?: number
}): Layer.Layer<OtelTracer.OtelTracer, never, HttpClient.HttpClient> => {
  const otlpLayer = baseUrl
    ? Otlp.layer({
        baseUrl,
        resource: { serviceName },
        tracerExportInterval,
      })
    : Layer.empty

  const otelAdapterLayer = Layer.effect(
    OtelTracer.OtelTracer,
    Effect.gen(function* () {
      const otlpTracer = yield* Effect.tracer
      return makeOtelTracerAdapter(otlpTracer)
    }),
  ).pipe(Layer.provide(otlpLayer))

  const otelEffectTracerLayer = Layer.unwrapEffect(Effect.map(OtelTracer.make, Layer.setTracer)).pipe(
    Layer.provide(otelAdapterLayer),
  )

  return otelEffectTracerLayer.pipe(Layer.provideMerge(otelAdapterLayer))
}

[clayroach]

We solve this a bit differently - instead of wrapping Effect's tracer with an OTel API adapter, we run both side-by-side. NodeSDK handles auto-instrumentation (Express, HTTP, etc.) while @effect/opentelemetry/Otlp handles Effect spans. We use the tracerContext callback to bridge context so they share parent-child relationships.

This works for us since we don't have libraries requiring the OTel API Tracer interface directly - we just need Effect spans and auto-instrumented spans in the same trace. If you do have libraries that requires an actual @opentelemetry/api.Tracer, your adapter approach makes sense.

Here's how we set up the context bridge: https://github.com/atrim-ai/instrumentation/blob/main/packages/node/src/integrations/effect/effect-tracer.ts Line 173+

This follows the same approach as the OTel base SDK https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-sdk-trace-base/src/Tracer.ts#L79