@effect/opentelemetry 4.0.0-beta.10 → 4.0.0-beta.101

package/src/{Tracer.ts → OtelTracer.ts}

@@ -1,18 +1,36 @@
 /**
- * @since 1.0.0
+ * Bridges Effect tracing into OpenTelemetry by installing an Effect `Tracer`
+ * that creates OpenTelemetry spans, records attributes, events, links, errors,
+ * and status, and keeps OpenTelemetry context active while traced effects run.
+ * Use this module when an application already has an OpenTelemetry
+ * `TracerProvider`, or when the Node and Web SDK layers should expose Effect
+ * spans to OTLP, console, or other OpenTelemetry-compatible exporters.
+ *
+ * The layer constructors wire Effect's tracer service to either the global
+ * OpenTelemetry tracer provider or an explicitly provided `OtelTracer`. This
+ * module does not create exporters or span processors by itself, so spans are
+ * exported only when the provider has been configured by the application or by
+ * the Node/Web SDK layers. Parentage is taken from Effect spans first and can
+ * also attach to the active OpenTelemetry context, while `makeExternalSpan` and
+ * `withSpanContext` are the entry points for continuing an incoming remote
+ * trace. Preserve `traceFlags` and `traceState` when building external spans;
+ * otherwise sampling defaults to sampled and trace state cannot be propagated.
+ *
+ * @since 4.0.0
  */
 import * as Otel from "@opentelemetry/api"
 import * as OtelSemConv from "@opentelemetry/semantic-conventions"
 import * as Cause from "effect/Cause"
 import type * as Clock from "effect/Clock"
+import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
 import * as Exit from "effect/Exit"
 import { constTrue, dual } from "effect/Function"
 import * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
 import * as Predicate from "effect/Predicate"
-import * as ServiceMap from "effect/ServiceMap"
 import * as Tracer from "effect/Tracer"
-import { recordToAttributes, unknownToAttributeValue } from "./internal/attributes.ts"
+import { nanosToHrTime, recordToAttributes, unknownToAttributeValue } from "./internal/attributes.ts"
 import { Resource } from "./Resource.ts"
 
 // =============================================================================
@@ -20,37 +38,45 @@ import { Resource } from "./Resource.ts"
 // =============================================================================
 
 /**
- * @since 1.0.0
- * @category Services
+ * Context service containing the OpenTelemetry `Tracer` used to create spans for Effect tracing.
+ *
+ * @category services
+ * @since 4.0.0
  */
-export class OtelTracer extends ServiceMap.Service<
+export class OtelTracer extends Context.Service<
   OtelTracer,
   Otel.Tracer
 >()("@effect/opentelemetry/Tracer") {}
 
 /**
- * @since 1.0.0
- * @category Services
+ * Context service containing the OpenTelemetry `TracerProvider` used to obtain tracers.
+ *
+ * @category services
+ * @since 4.0.0
  */
-export class OtelTracerProvider extends ServiceMap.Service<
+export class OtelTracerProvider extends Context.Service<
   OtelTracerProvider,
   Otel.TracerProvider
 >()("@effect/opentelemetry/Tracer/OtelTracerProvider") {}
 
 /**
- * @since 1.0.0
- * @category Services
+ * Context service containing OpenTelemetry trace flags used when constructing external span contexts.
+ *
+ * @category services
+ * @since 4.0.0
  */
-export class OtelTraceFlags extends ServiceMap.Service<
+export class OtelTraceFlags extends Context.Service<
   OtelTraceFlags,
   Otel.TraceFlags
 >()("@effect/opentelemetry/Tracer/OtelTraceFlags") {}
 
 /**
- * @since 1.0.0
- * @category Services
+ * Context service containing OpenTelemetry trace state used when constructing external span contexts.
+ *
+ * @category services
+ * @since 4.0.0
  */
-export class OtelTraceState extends ServiceMap.Service<
+export class OtelTraceState extends Context.Service<
   OtelTraceState,
   Otel.TraceState
 >()("@effect/opentelemetry/Tracer/OtelTraceState") {}
@@ -60,8 +86,10 @@ export class OtelTraceState extends ServiceMap.Service<
 // =============================================================================
 
 /**
- * @since 1.0.0
- * @category Constructors
+ * Creates an Effect `Tracer` implementation backed by the configured OpenTelemetry tracer.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const make: Effect.Effect<Tracer.Tracer, never, OtelTracer> = Effect.map(
   Effect.service(OtelTracer),
@@ -91,8 +119,10 @@ export const make: Effect.Effect<Tracer.Tracer, never, OtelTracer> = Effect.map(
 )
 
 /**
- * @since 1.0.0
- * @category Constructors
+ * Creates an Effect external span from an OpenTelemetry span context, preserving trace flags and trace state when provided.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const makeExternalSpan = (options: {
   readonly traceId: string
@@ -100,22 +130,24 @@ export const makeExternalSpan = (options: {
   readonly traceFlags?: number | undefined
   readonly traceState?: string | Otel.TraceState | undefined
 }): Tracer.ExternalSpan => {
-  let annotations = ServiceMap.empty()
-
-  if (options.traceFlags !== undefined) {
-    annotations = ServiceMap.add(annotations, OtelTraceFlags, options.traceFlags)
-  }
+  const annotations = Context.mutate(Context.empty(), (annotations) => {
+    let next = annotations
+    if (options.traceFlags !== undefined) {
+      next = Context.add(next, OtelTraceFlags, options.traceFlags)
+    }
 
-  if (typeof options.traceState === "string") {
-    try {
-      const traceState = Otel.createTraceState(options.traceState)
-      annotations = ServiceMap.add(annotations, OtelTraceState, traceState)
-    } catch {
-      //
+    if (typeof options.traceState === "string") {
+      try {
+        next = Context.add(next, OtelTraceState, Otel.createTraceState(options.traceState))
+      } catch {
+        //
+      }
+    } else if (options.traceState) {
+      next = Context.add(next, OtelTraceState, options.traceState)
     }
-  } else if (options.traceState) {
-    annotations = ServiceMap.add(annotations, OtelTraceState, options.traceState)
-  }
+
+    return next
+  })
 
   return {
     _tag: "ExternalSpan",
@@ -131,8 +163,10 @@ export const makeExternalSpan = (options: {
 // =============================================================================
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Layer that provides the current global OpenTelemetry tracer provider.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerGlobalProvider: Layer.Layer<OtelTracerProvider> = Layer.sync(
   OtelTracerProvider,
@@ -140,8 +174,10 @@ export const layerGlobalProvider: Layer.Layer<OtelTracerProvider> = Layer.sync(
 )
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Layer that creates an OpenTelemetry tracer from the provided tracer provider and resource metadata.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerTracer: Layer.Layer<OtelTracer, never, OtelTracerProvider | Resource> = Layer.effect(
   OtelTracer,
@@ -156,30 +192,47 @@ export const layerTracer: Layer.Layer<OtelTracer, never, OtelTracerProvider | Re
 )
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Layer that creates an OpenTelemetry tracer from the global tracer provider and the current resource.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerGlobalTracer: Layer.Layer<OtelTracer, never, Resource> = layerTracer.pipe(
   Layer.provide(layerGlobalProvider)
 )
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Layer that installs an Effect tracer backed by the global OpenTelemetry tracer provider.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerGlobal: Layer.Layer<OtelTracer, never, Resource> = Layer.effect(Tracer.Tracer, make).pipe(
   Layer.provideMerge(layerGlobalTracer)
 )
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Layer that installs the Effect tracer using an `OtelTracer` already provided in the environment.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerWithoutOtelTracer: Layer.Layer<never, never, OtelTracer> = Layer.effect(Tracer.Tracer, make)
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Layer that creates an OpenTelemetry tracer from a provider and resource, then installs it as the Effect tracer.
+ *
+ * **When to use**
+ *
+ * Use when you already provide an `OtelTracerProvider` and a `Resource`, and
+ * want Effect spans backed by a tracer derived from them.
+ *
+ * @see {@link layerTracer} for creating only the OpenTelemetry tracer service
+ * @see {@link layerGlobal} for installing the Effect tracer from the global provider
+ * @see {@link layerWithoutOtelTracer} for installing an already-provided `OtelTracer`
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<OtelTracer, never, OtelTracerProvider | Resource> = layerWithoutOtelTracer.pipe(
   Layer.provideMerge(layerTracer)
@@ -193,16 +246,17 @@ const bigint1e6 = BigInt(1_000_000)
 const bigint1e9 = BigInt(1_000_000_000)
 
 /**
- * Get the current OpenTelemetry span.
+ * Gets the current OpenTelemetry span.
  *
- * Works with both the official OpenTelemetry API (via `Tracer.layer`,
- * `NodeSdk.layer`, etc.) and the lightweight OTLP module (`OtlpTracer.layer`).
+ * **Details**
  *
- * When using OTLP, the returned span is a wrapper that conforms to the
- * OpenTelemetry `Span` interface.
+ * This accessor works with both the official OpenTelemetry API, such as
+ * `Tracer.layer` and `NodeSdk.layer`, and the lightweight OTLP module, such as
+ * `OtlpTracer.layer`. When using OTLP, the returned span is a wrapper that
+ * conforms to the OpenTelemetry `Span` interface.
  *
- * @since 1.0.0
  * @category accessors
+ * @since 4.0.0
  */
 export const currentOtelSpan: Effect.Effect<Otel.Span, Cause.NoSuchElementError> = Effect.clockWith((clock) =>
   Effect.map(Effect.currentSpan, (span) =>
@@ -275,7 +329,9 @@ const makeOtelSpan = (span: Tracer.Span, clock: Clock.Clock): Otel.Span => {
     recordException(exception, timeInput) {
       const time = convertOtelTimeInput(timeInput, clock)
       const cause = Cause.fail(exception)
-      const error = Cause.prettyErrors(cause)[0]
+      const error = Cause.prettyErrors(cause, {
+        includeCauseInStack: true
+      })[0]
       span.event(error.message, time, {
         "exception.type": error.name,
         "exception.message": error.message,
@@ -299,35 +355,41 @@ const convertOtelTimeInput = (input: Otel.TimeInput | undefined, clock: Clock.Cl
 }
 
 /**
- * Set the effect's parent span from the given opentelemetry `SpanContext`.
+ * Sets an effect's parent span from the given OpenTelemetry `SpanContext`.
  *
- * This is handy when you set up OpenTelemetry outside of Effect and want to
- * attach to a parent span.
+ * **When to use**
  *
- * @since 1.0.0
- * @category Propagation
+ * Use when you need an effect to continue a trace from a parent span context
+ * produced by OpenTelemetry instrumentation outside Effect.
+ *
+ * @category propagation
+ * @since 4.0.0
  */
 export const withSpanContext: {
   /**
-   * Set the effect's parent span from the given opentelemetry `SpanContext`.
+   * Sets an effect's parent span from the given OpenTelemetry `SpanContext`.
+   *
+   * **When to use**
    *
-   * This is handy when you set up OpenTelemetry outside of Effect and want to
-   * attach to a parent span.
+   * Use when you need an effect to continue a trace from a parent span context
+   * produced by OpenTelemetry instrumentation outside Effect.
    *
-   * @since 1.0.0
-   * @category Propagation
+   * @category propagation
+   * @since 4.0.0
    */
   (spanContext: Otel.SpanContext): <A, E, R>(
     self: Effect.Effect<A, E, R>
   ) => Effect.Effect<A, E, Exclude<R, Tracer.ParentSpan>>
   /**
-   * Set the effect's parent span from the given opentelemetry `SpanContext`.
+   * Sets an effect's parent span from the given OpenTelemetry `SpanContext`.
    *
-   * This is handy when you set up OpenTelemetry outside of Effect and want to
-   * attach to a parent span.
+   * **When to use**
    *
-   * @since 1.0.0
-   * @category Propagation
+   * Use when you need an effect to continue a trace from a parent span context
+   * produced by OpenTelemetry instrumentation outside Effect.
+   *
+   * @category propagation
+   * @since 4.0.0
    */
   <A, E, R>(self: Effect.Effect<A, E, R>, spanContext: Otel.SpanContext): Effect.Effect<A, E, Exclude<R, Tracer.ParentSpan>>
 } = dual(2, <A, E, R>(
@@ -356,14 +418,14 @@ export class OtelSpan implements Tracer.Span {
 
   readonly name: string
   readonly kind: Tracer.SpanKind
-  readonly annotations: ServiceMap.ServiceMap<never>
+  readonly annotations: Context.Context<never>
   readonly links: Array<Tracer.SpanLink>
   readonly span: Otel.Span
   readonly spanId: string
   readonly traceId: string
   readonly attributes = new Map<string, unknown>()
   readonly sampled: boolean
-  readonly parent: Tracer.AnySpan | undefined
+  readonly parent: Option.Option<Tracer.AnySpan>
   status: Tracer.SpanStatus
 
   constructor(
@@ -378,9 +440,9 @@ export class OtelSpan implements Tracer.Span {
     this.links = options.links
     this.kind = options.kind
     const active = contextApi.active()
-    this.parent = options.parent ?? (options?.root !== true) ?
-      getOtelParent(traceApi, active, options.annotations) :
-      undefined
+    this.parent = options.root !== true
+      ? Option.orElse(options.parent, () => getOtelParent(traceApi, active, options.annotations))
+      : options.parent
     this.span = tracer.startSpan(
       options.name,
       {
@@ -393,7 +455,9 @@ export class OtelSpan implements Tracer.Span {
           : undefined as any,
         kind: kindMap[this.kind]
       },
-      this.parent ? populateContext(active, this.parent, options.annotations) : Otel.trace.deleteSpan(active)
+      Option.isSome(this.parent) ?
+        populateContext(active, this.parent.value, options.annotations) :
+        Otel.trace.deleteSpan(active)
     )
     const spanContext = this.span.spanContext()
     this.spanId = spanContext.spanId
@@ -439,7 +503,9 @@ export class OtelSpan implements Tracer.Span {
         this.span.setAttribute("span.label", "⚠︎ Interrupted")
         this.span.setAttribute("status.interrupted", true)
       } else {
-        const errors = Cause.prettyErrors(exit.cause)
+        const errors = Cause.prettyErrors(exit.cause, {
+          includeCauseInStack: true
+        })
         if (errors.length > 0) {
           for (const error of errors) {
             this.span.recordException(error, hrTime)
@@ -469,30 +535,24 @@ export class OtelSpan implements Tracer.Span {
 const isSampled = (traceFlags: Otel.TraceFlags): boolean =>
   (traceFlags & Otel.TraceFlags.SAMPLED) === Otel.TraceFlags.SAMPLED
 
-const nanosToHrTime = (timestamp: bigint): Otel.HrTime => {
-  return [Number(timestamp / bigint1e9), Number(timestamp % bigint1e9)]
-}
-
 const getOtelParent = (
   tracer: Otel.TraceAPI,
   context: Otel.Context,
-  annotations: ServiceMap.ServiceMap<never>
-): Tracer.AnySpan | undefined => {
-  const active = tracer.getSpan(context)
-  const otelParent = active ? active.spanContext() : undefined
-  return otelParent
-    ? Tracer.externalSpan({
-      spanId: otelParent.spanId,
-      traceId: otelParent.traceId,
-      sampled: (otelParent.traceFlags & 1) === 1,
-      annotations
-    })
-    : undefined
+  annotations: Context.Context<never>
+): Option.Option<Tracer.AnySpan> => {
+  const otelParent = tracer.getSpan(context)?.spanContext()
+  if (!otelParent) return Option.none()
+  return Option.some(Tracer.externalSpan({
+    spanId: otelParent.spanId,
+    traceId: otelParent.traceId,
+    sampled: (otelParent.traceFlags & 1) === 1,
+    annotations
+  }))
 }
 
 const makeSpanContext = (
   span: Tracer.AnySpan,
-  annotations?: ServiceMap.ServiceMap<never>
+  annotations?: Context.Context<never>
 ): Otel.SpanContext => {
   const traceFlags = makeTraceFlags(span, annotations)
   const traceState = makeTraceState(span, annotations)!
@@ -507,27 +567,27 @@ const makeSpanContext = (
 
 const makeTraceFlags = (
   span: Tracer.AnySpan,
-  annotations: ServiceMap.ServiceMap<never> | undefined
+  annotations: Context.Context<never> | undefined
 ): Otel.TraceFlags => {
   let traceFlags: Otel.TraceFlags | undefined
   if (Predicate.isNotUndefined(annotations)) {
     traceFlags = extractTraceService(span, annotations, OtelTraceFlags)
     if (Predicate.isUndefined(traceFlags)) {
-      traceFlags = ServiceMap.getOrUndefined(span.annotations, OtelTraceFlags)
+      traceFlags = Context.getOrUndefined(span.annotations, OtelTraceFlags)
     }
   }
-  return traceFlags ?? Otel.TraceFlags.SAMPLED
+  return traceFlags ?? (span.sampled ? Otel.TraceFlags.SAMPLED : Otel.TraceFlags.NONE)
 }
 
 const makeTraceState = (
   span: Tracer.AnySpan,
-  annotations: ServiceMap.ServiceMap<never> | undefined
+  annotations: Context.Context<never> | undefined
 ): Otel.TraceState | undefined => {
   let traceState: Otel.TraceState | undefined
   if (Predicate.isNotUndefined(annotations)) {
     traceState = extractTraceService(span, annotations, OtelTraceState)
     if (Predicate.isUndefined(traceState)) {
-      traceState = ServiceMap.getOrUndefined(span.annotations, OtelTraceState)
+      traceState = Context.getOrUndefined(span.annotations, OtelTraceState)
     }
   }
   return traceState
@@ -535,20 +595,20 @@ const makeTraceState = (
 
 const extractTraceService = <I, S>(
   parent: Tracer.AnySpan,
-  annotations: ServiceMap.ServiceMap<never>,
-  service: ServiceMap.Service<I, S>
+  annotations: Context.Context<never>,
+  service: Context.Service<I, S>
 ) => {
-  const instance = ServiceMap.getOrUndefined(annotations, service)
+  const instance = Context.getOrUndefined(annotations, service)
   if (Predicate.isNotUndefined(instance)) {
     return instance
   }
-  return ServiceMap.getOrUndefined(parent.annotations, service)
+  return Context.getOrUndefined(parent.annotations, service)
 }
 
 const populateContext = (
   context: Otel.Context,
   span: Tracer.AnySpan,
-  annotations?: ServiceMap.ServiceMap<never> | undefined
+  annotations?: Context.Context<never> | undefined
 ): Otel.Context =>
   span instanceof OtelSpan ?
     Otel.trace.setSpan(context, span.span) :

package/src/Resource.ts

@@ -1,27 +1,45 @@
 /**
- * @since 1.0.0
+ * OpenTelemetry resource service and layers.
+ *
+ * An OpenTelemetry resource identifies the process or service that emits spans,
+ * metrics, and logs. This module stores that resource in Effect context and
+ * provides layers for creating it from explicit service metadata, from
+ * `OTEL_SERVICE_NAME` and `OTEL_RESOURCE_ATTRIBUTES`, or as an empty resource.
+ * It also includes `configToAttributes` for turning service metadata into raw
+ * OpenTelemetry attributes.
+ *
+ * @since 4.0.0
  */
 import type * as OtelApi from "@opentelemetry/api"
 import * as Resources from "@opentelemetry/resources"
 import * as OtelSemConv from "@opentelemetry/semantic-conventions"
 import * as Arr from "effect/Array"
 import * as Config from "effect/Config"
+import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
-import * as ServiceMap from "effect/ServiceMap"
 
 /**
- * @since 1.0.0
- * @category Services
+ * Service tag for OpenTelemetry metadata attached to emitted telemetry.
+ *
+ * **When to use**
+ *
+ * Use to provide process, service, and deployment metadata that should be
+ * attached to spans, metrics, and logs.
+ *
+ * @category services
+ * @since 4.0.0
  */
-export class Resource extends ServiceMap.Service<
+export class Resource extends Context.Service<
   Resource,
   Resources.Resource
 >()("@effect/opentelemetry/Resource") {}
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Creates a `Resource` layer from service metadata and additional OpenTelemetry attributes.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer = (config: {
   readonly serviceName: string
@@ -34,8 +52,30 @@ export const layer = (config: {
   )
 
 /**
- * @since 1.0.0
- * @category Configuration
+ * Converts resource configuration into OpenTelemetry attributes, adding service name, optional service version, and telemetry SDK metadata.
+ *
+ * **When to use**
+ *
+ * Use to turn explicit service metadata into a raw OpenTelemetry attribute map
+ * for lower-level resource construction or merging with environment-derived
+ * attributes via `layerFromEnv`.
+ *
+ * **Details**
+ *
+ * The returned record copies `attributes` first, then sets `service.name`,
+ * `telemetry.sdk.name`, and `telemetry.sdk.language`. `service.version` is
+ * included only when `serviceVersion` is provided.
+ *
+ * **Gotchas**
+ *
+ * Custom values for `service.name` and `telemetry.sdk.*` are overwritten by this
+ * helper. An empty `serviceVersion` is treated as absent.
+ *
+ * @see {@link layer} for creating a `Resource` layer from explicit metadata
+ * @see {@link layerFromEnv} for merging attributes with OpenTelemetry environment variables
+ *
+ * @category configuration
+ * @since 4.0.0
  */
 export const configToAttributes = (options: {
   readonly serviceName: string
@@ -57,8 +97,10 @@ export const configToAttributes = (options: {
 }
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Creates a `Resource` layer from OpenTelemetry environment variables, optionally merging additional attributes.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerFromEnv = (
   additionalAttributes?:
@@ -70,7 +112,7 @@ export const layerFromEnv = (
     Effect.gen(function*() {
       const serviceName = yield* Config.option(Config.string("OTEL_SERVICE_NAME"))
       const attributes = yield* Config.string("OTEL_RESOURCE_ATTRIBUTES").pipe(
-        Config.withDefault(() => ""),
+        Config.withDefault(""),
         Config.map((s) => {
           const attrs = s.split(",")
           return Arr.reduce(attrs, {} as OtelApi.Attributes, (acc, attr) => {
@@ -94,8 +136,10 @@ export const layerFromEnv = (
   )
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Layer that provides an empty OpenTelemetry resource.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerEmpty = Layer.succeed(
   Resource,