@effect/opentelemetry 4.0.0-beta.7 → 4.0.0-beta.71

package/src/Logger.ts

@@ -1,33 +1,104 @@
 /**
- * @since 1.0.0
+ * Connects Effect logging to the OpenTelemetry Logs SDK.
+ *
+ * This module turns Effect log events into OpenTelemetry log records. It
+ * provides the `OtelLoggerProvider` service, a `Logger` implementation created
+ * by {@link make}, a {@link layer} that installs it into Effect logging, and
+ * {@link layerLoggerProvider} for creating a scoped SDK `LoggerProvider` from
+ * one or more `LogRecordProcessor`s.
+ *
+ * **Mental model**
+ *
+ * Effect decides when a log is emitted and supplies the message, fiber id, log
+ * level, annotations, log spans, and active parent span. This module maps that
+ * data into an OpenTelemetry log record, including severity text/number, trace
+ * and span identifiers when available, and timestamps from the Effect `Clock`.
+ *
+ * **Common tasks**
+ *
+ * Use {@link layerLoggerProvider} when the application wants this package to own
+ * the OpenTelemetry logger provider lifecycle. Provide it with processors such
+ * as OTLP, console, or vendor-specific exporters, then install {@link layer} so
+ * regular Effect logging emits records through that provider. If the provider is
+ * created elsewhere, supply `OtelLoggerProvider` yourself and still use
+ * {@link layer} or {@link make}.
+ *
+ * **Gotchas**
+ *
+ * This module does not choose an exporter. Export behavior, batching, retries,
+ * and delivery guarantees come from the configured OpenTelemetry processors.
+ * The scoped provider is force-flushed and shut down when the layer is released,
+ * using the configured shutdown timeout; externally managed providers should be
+ * flushed and shut down by the owner to avoid dropping buffered logs.
+ *
+ * @since 4.0.0
  */
+import { SeverityNumber } from "@opentelemetry/api-logs"
 import * as Otel from "@opentelemetry/sdk-logs"
 import type { NonEmptyReadonlyArray } from "effect/Array"
 import * as Arr from "effect/Array"
 import * as Clock from "effect/Clock"
+import * as Context from "effect/Context"
 import type * as Duration from "effect/Duration"
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
 import * as Logger from "effect/Logger"
-import * as LogLevel from "effect/LogLevel"
+import type * as LogLevel from "effect/LogLevel"
 import * as Predicate from "effect/Predicate"
-import * as ServiceMap from "effect/ServiceMap"
+import * as References from "effect/References"
 import * as Tracer from "effect/Tracer"
-import { unknownToAttributeValue } from "./internal/attributes.ts"
+import { nanosToHrTime, unknownToAttributeValue } from "./internal/attributes.ts"
 import { Resource } from "./Resource.ts"
 
 /**
- * @since 1.0.0
- * @category Services
+ * Context service containing the OpenTelemetry `LoggerProvider` used to emit Effect log records.
+ *
+ * @category services
+ * @since 4.0.0
  */
-export class OtelLoggerProvider extends ServiceMap.Service<
+export class OtelLoggerProvider extends Context.Service<
   OtelLoggerProvider,
   Otel.LoggerProvider
 >()("@effect/opentelemetry/Logger/OtelLoggerProvider") {}
 
 /**
- * @since 1.0.0
- * @category Constructors
+ * Maps an Effect `LogLevel` to the corresponding OpenTelemetry `SeverityNumber`.
+ *
+ * **Details**
+ *
+ * OpenTelemetry log severity numbers are in the range `1` through `24`. This
+ * function maps from Effect's log levels instead of using
+ * `LogLevel.getOrdinal`, whose internal sort ordinals, such as the `Info`
+ * ordinal `20000`, fall outside the OpenTelemetry logs data model and can be
+ * treated as `UNSPECIFIED` by validating backends.
+ *
+ * @category converting
+ * @since 4.0.0
+ */
+export const logLevelToSeverityNumber = (level: LogLevel.LogLevel): SeverityNumber => {
+  switch (level) {
+    case "Trace":
+      return SeverityNumber.TRACE
+    case "Debug":
+      return SeverityNumber.DEBUG
+    case "Info":
+      return SeverityNumber.INFO
+    case "Warn":
+      return SeverityNumber.WARN
+    case "Error":
+      return SeverityNumber.ERROR
+    case "Fatal":
+      return SeverityNumber.FATAL
+    default:
+      return SeverityNumber.UNSPECIFIED
+  }
+}
+
+/**
+ * Creates an Effect logger that emits log records through the configured OpenTelemetry logger provider.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const make: Effect.Effect<
   Logger.Logger<unknown, void>,
@@ -43,40 +114,60 @@ export const make: Effect.Effect<
       fiberId: options.fiber.id
     }
 
-    const span = ServiceMap.getOrUndefined(options.fiber.services, Tracer.ParentSpan)
+    const span = Context.getOrUndefined(options.fiber.context, Tracer.ParentSpan)
 
     if (Predicate.isNotUndefined(span)) {
       attributes.spanId = span.spanId
       attributes.traceId = span.traceId
     }
 
-    // TODO: add back after log spans / annotations
-    // for (const [key, value] of options.annotations) {
-    //   attributes[key] = unknownToAttributeValue(value)
-    // }
-    // const now = options.date.getTime()
-    // for (const span of options.spans) {
-    //   attributes[`logSpan.${span.label}`] = `${now - span.startTime}ms`
-    // }
+    for (const [key, value] of Object.entries(options.fiber.getRef(References.CurrentLogAnnotations))) {
+      attributes[key] = unknownToAttributeValue(value)
+    }
+    const now = options.date.getTime()
+    for (const [label, startTime] of options.fiber.getRef(References.CurrentLogSpans)) {
+      attributes[`logSpan.${label}`] = `${now - startTime}ms`
+    }
 
     const message = Arr.ensure(options.message).map(unknownToAttributeValue)
+    const hrTime = nanosToHrTime(clock.currentTimeNanosUnsafe())
     otelLogger.emit({
       body: message.length === 1 ? message[0] : message,
       severityText: options.logLevel,
-      severityNumber: LogLevel.getOrdinal(options.logLevel),
-      timestamp: options.date,
-      observedTimestamp: clock.currentTimeMillisUnsafe(),
+      severityNumber: logLevelToSeverityNumber(options.logLevel),
+      timestamp: hrTime,
+      observedTimestamp: hrTime,
       attributes
     })
   })
 })
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Creates a layer that installs the OpenTelemetry-backed Effect logger, merging with existing loggers by default.
+ *
+ * **When to use**
+ *
+ * Use to install the OpenTelemetry-backed Effect logger in an application that
+ * has an `OtelLoggerProvider`, so standard Effect logging emits OpenTelemetry
+ * log records.
+ *
+ * **Details**
+ *
+ * The layer installs the logger created by `make`. `mergeWithExisting` defaults
+ * to `true`; set it to `false` to replace the current logger set.
+ *
+ * @see {@link make} for constructing the logger directly
+ * @see {@link layerLoggerProvider} for creating the required logger provider
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer = (options: {
   /**
+   * Whether to merge the OpenTelemetry logger with existing loggers.
+   *
+   * **Details**
+   *
    * If set to `true`, the OpenTelemetry logger will be merged with existing
    * loggers in the application.
    *
@@ -92,8 +183,10 @@ export const layer = (options: {
   })
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Creates a scoped OpenTelemetry logger provider from one or more log record processors, using the current `Resource` and flushing and shutting down the provider when the layer is released.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerLoggerProvider = (
   processor: Otel.LogRecordProcessor | NonEmptyReadonlyArray<Otel.LogRecordProcessor>,

package/src/Metrics.ts

@@ -1,5 +1,37 @@
 /**
- * @since 1.0.0
+ * OpenTelemetry metric export bridge for Effect metrics.
+ *
+ * Effect applications record metrics through Effect's metric APIs. This module
+ * exposes the current Effect metric snapshot as an OpenTelemetry
+ * `MetricProducer` and registers it with SDK `MetricReader`s so existing
+ * OpenTelemetry exporters can deliver those metrics to OTLP, Prometheus, or
+ * vendor backends.
+ *
+ * **Mental model**
+ *
+ * {@link makeProducer} captures the current Effect context and `Resource` and
+ * builds a producer that OpenTelemetry readers can pull from.
+ * {@link registerProducer} attaches that producer to one or more readers for
+ * the lifetime of a scope. {@link layer} composes both steps and is the path
+ * used by the Node and Web SDK layers when metric readers are configured.
+ *
+ * **Common tasks**
+ *
+ * - Install Effect metrics into OpenTelemetry with {@link layer}
+ * - Build a producer manually with {@link makeProducer}
+ * - Attach an existing producer to readers with {@link registerProducer}
+ * - Choose cumulative or delta export with {@link TemporalityPreference}
+ *
+ * **Gotchas**
+ *
+ * Readers are shut down when the layer scope closes, so periodic exporters need
+ * the application runtime to stay alive long enough for collection and export.
+ * This module defaults to cumulative temporality; configure
+ * `temporality: "delta"` only when the backend expects interval values. Export
+ * protocol, batching, and delivery behavior come from the OpenTelemetry
+ * reader/exporter, not from this bridge.
+ *
+ * @since 4.0.0
  */
 import type { MetricProducer, MetricReader } from "@opentelemetry/sdk-metrics"
 import type * as Arr from "effect/Array"
@@ -15,35 +47,50 @@ import { Resource } from "./Resource.ts"
  * Determines how metric values relate to the time interval over which they
  * are aggregated.
  *
- * - `cumulative`: Reports total since a fixed start time. Each data point
- *   depends on all previous measurements. This is the default behavior.
+ * **Details**
  *
- * - `delta`: Reports changes since the last export. Each interval is
- *   independent with no dependency on previous measurements.
+ * `cumulative` reports total since a fixed start time. Each data point depends
+ * on all previous measurements. This is the default behavior. `delta` reports
+ * changes since the last export. Each interval is independent with no
+ * dependency on previous measurements.
  *
- * @since 1.0.0
- * @category Models
+ * @category models
+ * @since 4.0.0
  */
 export type TemporalityPreference = "cumulative" | "delta"
 
 /**
  * Creates an OpenTelemetry metric producer from Effect metrics.
  *
- * @since 1.0.0
- * @category Constructors
+ * **When to use**
+ *
+ * Use to create a `MetricProducer` when you need to wire Effect metrics into
+ * OpenTelemetry manually instead of using the scoped `layer` helper.
+ *
+ * **Details**
+ *
+ * Requires the current OpenTelemetry `Resource`, captures the current Effect
+ * context, and uses cumulative temporality by default. Pass `"delta"` for
+ * interval-based values.
+ *
+ * @see {@link registerProducer} for attaching a producer to metric readers
+ * @see {@link layer} for creating and registering a producer in a scoped layer
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const makeProducer = (temporality?: TemporalityPreference): Effect.Effect<MetricProducer, never, Resource> =>
   Effect.gen(function*() {
     const resource = yield* Resource
-    const services = yield* Effect.services<never>()
+    const services = yield* Effect.context<never>()
     return new MetricProducerImpl(resource, services, temporality)
   })
 
 /**
  * Registers a metric producer with one or more metric readers.
  *
- * @since 1.0.0
- * @category Constructors
+ * @category constructors
+ * @since 4.0.0
  */
 export const registerProducer = (
   self: MetricProducer,
@@ -74,7 +121,8 @@ export const registerProducer = (
 /**
  * Creates a Layer that registers a metric producer with metric readers.
  *
- * @example
+ * **Example** (Creating a metrics layer with temporality)
+ *
  * ```ts
  * import { Metrics } from "@effect/opentelemetry"
  * import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics"
@@ -98,8 +146,8 @@ export const registerProducer = (
  * )
  * ```
  *
- * @since 1.0.0
- * @category Layers
+ * @category layers
+ * @since 4.0.0
  */
 export const layer = (
   evaluate: LazyArg<MetricReader | Arr.NonEmptyReadonlyArray<MetricReader>>,

package/src/NodeSdk.ts

@@ -1,5 +1,27 @@
 /**
- * @since 1.0.0
+ * Provides an Effect layer for configuring OpenTelemetry in Node.js
+ * processes. The module wires the Effect tracer, metrics producer, and logger
+ * into OpenTelemetry SDK providers when span processors, metric readers, or log
+ * record processors are supplied, and it builds the shared resource from
+ * `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`, and optional explicit
+ * service metadata.
+ *
+ * Use this module in Node services, workers, CLIs, or server runtimes that need
+ * Effect spans, metrics, and logs exported through OpenTelemetry processors and
+ * exporters. Telemetry is enabled only for the configured signal types, so an
+ * application can install tracing alone, metrics alone, logging alone, or any
+ * combination of them from the same layer.
+ *
+ * The layer is scoped. Tracer and logger providers are force-flushed and shut
+ * down when the scope is released, metric readers are shut down with the same
+ * lifecycle, and all shutdown waits are bounded by `shutdownTimeout` with a
+ * default of three seconds. Keep the layer scope alive for the lifetime of the
+ * process and release it during graceful shutdown so batched exporters have a
+ * chance to export final telemetry. When combining this layer with Node
+ * auto-instrumentations, register instrumentation before importing modules that
+ * should be patched, because many Node instrumentations hook module loading.
+ *
+ * @since 4.0.0
  */
 import type * as Otel from "@opentelemetry/api"
 import type { LoggerProviderConfig, LogRecordProcessor } from "@opentelemetry/sdk-logs"
@@ -18,8 +40,10 @@ import * as Resource from "./Resource.ts"
 import * as Tracer from "./Tracer.ts"
 
 /**
- * @since 1.0.0
- * @category Models
+ * Configuration for the Node OpenTelemetry layer, including optional tracing, metrics, logging, resource, and shutdown settings.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export interface Configuration {
   readonly spanProcessor?: SpanProcessor | ReadonlyArray<SpanProcessor> | undefined
@@ -38,8 +62,10 @@ export interface Configuration {
 }
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Creates a scoped Node OpenTelemetry tracer provider from one or more span processors and shuts it down when the layer is released.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerTracerProvider = (
   processor: SpanProcessor | NonEmptyReadonlyArray<SpanProcessor>,
@@ -71,18 +97,75 @@ export const layerTracerProvider = (
   )
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Creates a Node OpenTelemetry layer from configuration, enabling tracing, metrics, and logging only when their processors or readers are supplied.
+ *
+ * **When to use**
+ *
+ * Use to install OpenTelemetry support for a Node.js Effect application from
+ * one configuration object, enabling tracing, metrics, logging, or any
+ * combination of those signals based on the processors and readers supplied.
+ *
+ * **Details**
+ *
+ * The configuration can be provided lazily or effectfully. The layer always
+ * provides `Resource.Resource`, building it from environment variables and any
+ * explicit resource metadata in the configuration.
+ *
+ * **Gotchas**
+ *
+ * Register Node auto-instrumentations before importing modules that should be
+ * patched, because many Node instrumentations hook module loading.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer: {
   /**
-   * @since 1.0.0
-   * @category Layers
+   * Creates a Node OpenTelemetry layer from configuration, enabling tracing, metrics, and logging only when their processors or readers are supplied.
+   *
+   * **When to use**
+   *
+   * Use to install OpenTelemetry support for a Node.js Effect application from
+   * one configuration object, enabling tracing, metrics, logging, or any
+   * combination of those signals based on the processors and readers supplied.
+   *
+   * **Details**
+   *
+   * The configuration can be provided lazily or effectfully. The layer always
+   * provides `Resource.Resource`, building it from environment variables and any
+   * explicit resource metadata in the configuration.
+   *
+   * **Gotchas**
+   *
+   * Register Node auto-instrumentations before importing modules that should be
+   * patched, because many Node instrumentations hook module loading.
+   *
+   * @category layers
+   * @since 4.0.0
    */
   (evaluate: LazyArg<Configuration>): Layer.Layer<Resource.Resource>
   /**
-   * @since 1.0.0
-   * @category Layers
+   * Creates a Node OpenTelemetry layer from configuration, enabling tracing, metrics, and logging only when their processors or readers are supplied.
+   *
+   * **When to use**
+   *
+   * Use to install OpenTelemetry support for a Node.js Effect application from
+   * one configuration object, enabling tracing, metrics, logging, or any
+   * combination of those signals based on the processors and readers supplied.
+   *
+   * **Details**
+   *
+   * The configuration can be provided lazily or effectfully. The layer always
+   * provides `Resource.Resource`, building it from environment variables and any
+   * explicit resource metadata in the configuration.
+   *
+   * **Gotchas**
+   *
+   * Register Node auto-instrumentations before importing modules that should be
+   * patched, because many Node instrumentations hook module loading.
+   *
+   * @category layers
+   * @since 4.0.0
    */
   <R, E>(evaluate: Effect.Effect<Configuration, E, R>): Layer.Layer<Resource.Resource, E, R>
 } = (
@@ -130,7 +213,9 @@ export const layer: {
   )
 
 /**
+ * Layer that provides an empty OpenTelemetry `Resource`.
+ *
+ * @category layers
  * @since 2.0.0
- * @category layer
  */
 export const layerEmpty: Layer.Layer<Resource.Resource> = Resource.layerEmpty

package/src/Resource.ts

@@ -1,27 +1,61 @@
 /**
- * @since 1.0.0
+ * OpenTelemetry resource service for Effect telemetry layers.
+ *
+ * An OpenTelemetry resource identifies the process or service that emits spans,
+ * metrics, and logs. This module stores that resource in Effect context so
+ * tracer, metric, logger, Node SDK, and Web SDK layers can create providers with
+ * consistent service metadata.
+ *
+ * **Mental model**
+ *
+ * Resource attributes describe stable producer metadata such as `service.name`,
+ * `service.version`, deployment, process, or environment attributes. They are
+ * attached to telemetry providers, not to individual spans or log records.
+ *
+ * **Common tasks**
+ *
+ * Use `layer` when service metadata is configured in code, `layerFromEnv` when
+ * deployment supplies `OTEL_SERVICE_NAME` or `OTEL_RESOURCE_ATTRIBUTES`, and
+ * `layerEmpty` for tests or integrations that intentionally provide no resource
+ * attributes. `configToAttributes` converts the explicit configuration shape
+ * into OpenTelemetry semantic-convention attributes for composition with other
+ * resource sources.
+ *
+ * **Gotchas**
+ *
+ * `layer` merges custom attributes first and then writes `service.name` and
+ * `telemetry.sdk.*`, so those keys are controlled by this package. In
+ * `layerFromEnv`, `OTEL_SERVICE_NAME` overrides `service.name` from
+ * `OTEL_RESOURCE_ATTRIBUTES`, and any additional attributes passed to the layer
+ * are merged last.
+ *
+ * @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
+ * Context service containing the OpenTelemetry `Resource` associated with emitted telemetry.
+ *
+ * @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 +68,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 for 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 +113,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 +128,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 +152,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,