@effect/opentelemetry 4.0.0-beta.66 → 4.0.0-beta.68

package/src/Resource.ts

@@ -1,5 +1,22 @@
 /**
- * @since 1.0.0
+ * Provides the OpenTelemetry resource used by the Effect OpenTelemetry layers.
+ *
+ * A resource describes the entity that produces telemetry, such as a service,
+ * process, deployment, or browser application. The tracing, metrics, logging,
+ * and SDK layers use this module's `Resource` service to configure providers
+ * and identify emitted telemetry with service-level metadata.
+ *
+ * Use `layer` when service metadata is known in code, `layerFromEnv` when
+ * deploying with `OTEL_SERVICE_NAME` and `OTEL_RESOURCE_ATTRIBUTES`, and
+ * `layerEmpty` when no resource attributes should be provided. Resource
+ * attributes are for stable process or service metadata, not per-span or
+ * per-log data. The explicit `layer` helper sets `service.name` and the
+ * `telemetry.sdk.*` attributes after merging custom attributes, so those keys
+ * are controlled by this integration. With `layerFromEnv`, `OTEL_SERVICE_NAME`
+ * overrides `service.name` from `OTEL_RESOURCE_ATTRIBUTES`, and 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"
@@ -11,8 +28,10 @@ import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
 
 /**
- * @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 Context.Service<
   Resource,
@@ -20,8 +39,10 @@ export class Resource extends Context.Service<
 >()("@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 +55,10 @@ 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.
+ *
+ * @category configuration
+ * @since 4.0.0
  */
 export const configToAttributes = (options: {
   readonly serviceName: string
@@ -57,8 +80,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?:
@@ -94,8 +119,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,

package/src/Tracer.ts

@@ -1,5 +1,22 @@
 /**
- * @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"
@@ -21,8 +38,10 @@ 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 Context.Service<
   OtelTracer,
@@ -30,8 +49,10 @@ export class OtelTracer extends Context.Service<
 >()("@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 Context.Service<
   OtelTracerProvider,
@@ -39,8 +60,10 @@ export class OtelTracerProvider extends Context.Service<
 >()("@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 Context.Service<
   OtelTraceFlags,
@@ -48,8 +71,10 @@ export class OtelTraceFlags extends Context.Service<
 >()("@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 Context.Service<
   OtelTraceState,
@@ -61,8 +86,10 @@ export class OtelTraceState extends Context.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),
@@ -92,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
@@ -134,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,
@@ -143,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,
@@ -159,30 +192,38 @@ 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.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<OtelTracer, never, OtelTracerProvider | Resource> = layerWithoutOtelTracer.pipe(
   Layer.provideMerge(layerTracer)
@@ -204,8 +245,8 @@ const bigint1e9 = BigInt(1_000_000_000)
  * 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) =>
@@ -307,8 +348,8 @@ const convertOtelTimeInput = (input: Otel.TimeInput | undefined, clock: Clock.Cl
  * This is handy when you set up OpenTelemetry outside of Effect and want to
  * attach to a parent span.
  *
- * @since 1.0.0
  * @category Propagation
+ * @since 4.0.0
  */
 export const withSpanContext: {
   /**
@@ -317,8 +358,8 @@ export const withSpanContext: {
    * This is handy when you set up OpenTelemetry outside of Effect and want to
    * attach to a parent span.
    *
-   * @since 1.0.0
    * @category Propagation
+   * @since 4.0.0
    */
   (spanContext: Otel.SpanContext): <A, E, R>(
     self: Effect.Effect<A, E, R>
@@ -329,8 +370,8 @@ export const withSpanContext: {
    * This is handy when you set up OpenTelemetry outside of Effect and want to
    * attach to a parent span.
    *
-   * @since 1.0.0
    * @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>(

package/src/WebSdk.ts

@@ -1,5 +1,31 @@
 /**
- * @since 1.0.0
+ * Provides an Effect layer for configuring OpenTelemetry in browser
+ * applications. The module builds a shared resource from explicit service
+ * metadata and wires Effect tracing, metrics, and logging into OpenTelemetry
+ * SDK providers when span processors, metric readers, or log record processors
+ * are supplied.
+ *
+ * Use this module in client-side applications that need Effect spans, metrics,
+ * and logs exported from browser runtimes, such as single-page apps,
+ * multi-page apps with hydrated Effect code, frontend workers, or UI flows
+ * that should be correlated with backend traces. Telemetry is enabled only for
+ * the configured signal types, so tracing, metrics, and logging can be
+ * installed independently from the same layer.
+ *
+ * Browser SDKs cannot rely on process environment resource configuration, so
+ * provide stable service metadata explicitly and use resource attributes for
+ * application, release, deployment, or page-shell identity rather than
+ * per-event data. This module does not create exporters; supply
+ * browser-compatible processors, readers, and exporters yourself, and make sure
+ * their endpoints are reachable from the browser with the required CORS and
+ * authentication behavior. The layer is scoped: tracer providers are
+ * force-flushed and shut down when the scope is released, while metric readers
+ * and logger providers follow their respective layer lifecycles. Keep the
+ * scope alive for the lifetime of the browser application and release it during
+ * application teardown when possible so batched exporters and periodic metric
+ * readers can deliver buffered telemetry before the page is unloaded.
+ *
+ * @since 4.0.0
  */
 import type * as Otel from "@opentelemetry/api"
 import type { LoggerProviderConfig, LogRecordProcessor } from "@opentelemetry/sdk-logs"
@@ -17,8 +43,10 @@ import * as Resource from "./Resource.ts"
 import * as Tracer from "./Tracer.ts"
 
 /**
- * @since 1.0.0
- * @category Models
+ * Configuration for the Web OpenTelemetry layer, including resource metadata and optional tracing, metrics, and logging settings.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export interface Configuration {
   readonly spanProcessor?: SpanProcessor | ReadonlyArray<SpanProcessor> | undefined
@@ -36,8 +64,10 @@ export interface Configuration {
 }
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Creates a scoped Web 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>,
@@ -65,18 +95,24 @@ export const layerTracerProvider = (
   )
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Creates a Web OpenTelemetry layer from configuration, providing the resource and enabling tracing, metrics, and logging when configured.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer: {
   /**
-   * @since 1.0.0
-   * @category Layers
+   * Creates a Web OpenTelemetry layer from configuration, providing the resource and enabling tracing, metrics, and logging when configured.
+   *
+   * @category layers
+   * @since 4.0.0
    */
   (evaluate: LazyArg<Configuration>): Layer.Layer<Resource.Resource>
   /**
-   * @since 1.0.0
-   * @category Layers
+   * Creates a Web OpenTelemetry layer from configuration, providing the resource and enabling tracing, metrics, and logging when configured.
+   *
+   * @category layers
+   * @since 4.0.0
    */
   <E, R>(evaluate: Effect.Effect<Configuration, E, R>): Layer.Layer<Resource.Resource, E, R>
 } = (

package/src/index.ts

@@ -1,35 +1,154 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
- * @since 1.0.0
+ * Connects Effect's logging system to the OpenTelemetry Logs SDK.
+ *
+ * This module provides a logger provider service, an Effect `Logger` that
+ * emits OpenTelemetry log records, and layers for installing that logger in an
+ * application. It is commonly used to send Effect logs to OTLP, console, or
+ * vendor-specific exporters through OpenTelemetry `LogRecordProcessor`s while
+ * keeping logs correlated with Effect fibers and spans. Emitted records include
+ * the current fiber id, span identifiers when a parent span is present, log
+ * annotations, log spans, severity text, and the matching OpenTelemetry
+ * severity number.
+ *
+ * Log export depends on the configured OpenTelemetry processors and exporters;
+ * this module creates the provider and logger, but does not choose an exporter.
+ * Use the `Resource` layer to attach service and deployment metadata to the
+ * provider rather than repeating that data on every log record. When using
+ * `layerLoggerProvider`, the provider is scoped and is force-flushed and shut
+ * down when the layer is released, with a configurable shutdown timeout. If you
+ * supply or manage an OpenTelemetry provider yourself, make sure it is flushed
+ * and shut down during application shutdown, especially when using batching
+ * processors that may otherwise drop buffered logs.
+ *
+ * @since 4.0.0
  */
 export * as Logger from "./Logger.ts"
 
 /**
- * @since 1.0.0
+ * Bridges Effect metrics into OpenTelemetry by exposing the current Effect
+ * metric snapshot as an OpenTelemetry `MetricProducer` and registering it with
+ * one or more SDK `MetricReader`s. Use this module when an application already
+ * records metrics with Effect and needs those counters, gauges, histograms,
+ * frequencies, or summaries exported through OTLP, Prometheus, or another
+ * OpenTelemetry-compatible reader/exporter.
+ *
+ * The `layer` constructor is the usual entry point, and is also used by the
+ * Node and Web SDK layers when `metricReader` configuration is supplied. Metric
+ * readers are acquired inside the layer scope and shut down when the scope is
+ * released, so periodic exporters need the runtime to stay alive long enough to
+ * collect and export data. The exporter or backend determines whether
+ * cumulative or delta aggregation is expected; this module defaults to
+ * cumulative temporality and can be configured with `temporality: "delta"` for
+ * backends that require interval-based values.
+ *
+ * @since 4.0.0
  */
 export * as Metrics from "./Metrics.ts"
 
 /**
- * @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
  */
 export * as NodeSdk from "./NodeSdk.ts"
 
 /**
- * @since 1.0.0
+ * Provides the OpenTelemetry resource used by the Effect OpenTelemetry layers.
+ *
+ * A resource describes the entity that produces telemetry, such as a service,
+ * process, deployment, or browser application. The tracing, metrics, logging,
+ * and SDK layers use this module's `Resource` service to configure providers
+ * and identify emitted telemetry with service-level metadata.
+ *
+ * Use `layer` when service metadata is known in code, `layerFromEnv` when
+ * deploying with `OTEL_SERVICE_NAME` and `OTEL_RESOURCE_ATTRIBUTES`, and
+ * `layerEmpty` when no resource attributes should be provided. Resource
+ * attributes are for stable process or service metadata, not per-span or
+ * per-log data. The explicit `layer` helper sets `service.name` and the
+ * `telemetry.sdk.*` attributes after merging custom attributes, so those keys
+ * are controlled by this integration. With `layerFromEnv`, `OTEL_SERVICE_NAME`
+ * overrides `service.name` from `OTEL_RESOURCE_ATTRIBUTES`, and additional
+ * attributes passed to the layer are merged last.
+ *
+ * @since 4.0.0
  */
 export * as Resource from "./Resource.ts"
 
 /**
- * @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
  */
 export * as Tracer from "./Tracer.ts"
 
 /**
- * @since 1.0.0
+ * Provides an Effect layer for configuring OpenTelemetry in browser
+ * applications. The module builds a shared resource from explicit service
+ * metadata and wires Effect tracing, metrics, and logging into OpenTelemetry
+ * SDK providers when span processors, metric readers, or log record processors
+ * are supplied.
+ *
+ * Use this module in client-side applications that need Effect spans, metrics,
+ * and logs exported from browser runtimes, such as single-page apps,
+ * multi-page apps with hydrated Effect code, frontend workers, or UI flows
+ * that should be correlated with backend traces. Telemetry is enabled only for
+ * the configured signal types, so tracing, metrics, and logging can be
+ * installed independently from the same layer.
+ *
+ * Browser SDKs cannot rely on process environment resource configuration, so
+ * provide stable service metadata explicitly and use resource attributes for
+ * application, release, deployment, or page-shell identity rather than
+ * per-event data. This module does not create exporters; supply
+ * browser-compatible processors, readers, and exporters yourself, and make sure
+ * their endpoints are reachable from the browser with the required CORS and
+ * authentication behavior. The layer is scoped: tracer providers are
+ * force-flushed and shut down when the scope is released, while metric readers
+ * and logger providers follow their respective layer lifecycles. Keep the
+ * scope alive for the lifetime of the browser application and release it during
+ * application teardown when possible so batched exporters and periodic metric
+ * readers can deliver buffered telemetry before the page is unloaded.
+ *
+ * @since 4.0.0
  */
 export * as WebSdk from "./WebSdk.ts"