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

package/src/Logger.ts

@@ -1,24 +1,35 @@
 /**
- * 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.
+ * 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
  */
@@ -134,6 +145,20 @@ export const make: Effect.Effect<
 /**
  * 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
  */

package/src/Metrics.ts

@@ -1,19 +1,35 @@
 /**
- * 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.
+ * 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
  */
@@ -46,6 +62,20 @@ export type TemporalityPreference = "cumulative" | "delta"
 /**
  * Creates an OpenTelemetry metric producer from Effect metrics.
  *
+ * **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
  */

package/src/NodeSdk.ts

@@ -99,6 +99,23 @@ export const layerTracerProvider = (
 /**
  * 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
  */
@@ -106,6 +123,23 @@ export const layer: {
   /**
    * 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
    */
@@ -113,6 +147,23 @@ export const layer: {
   /**
    * 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
    */

package/src/Resource.ts

@@ -1,20 +1,33 @@
 /**
- * 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.
+ * 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
  */
@@ -57,6 +70,26 @@ export const layer = (config: {
 /**
  * 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
  */

package/src/Tracer.ts

@@ -222,6 +222,16 @@ export const layerWithoutOtelTracer: Layer.Layer<never, never, OtelTracer> = Lay
 /**
  * Layer that creates an OpenTelemetry tracer from a provider and resource, then installs it as the Effect tracer.
  *
+ * **When to use**
+ *
+ * Use when your application already supplies an `OtelTracerProvider` and a
+ * `Resource`, and you want Effect spans to be created by an OpenTelemetry
+ * tracer derived from those services.
+ *
+ * @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
  */
@@ -348,7 +358,7 @@ const convertOtelTimeInput = (input: Otel.TimeInput | undefined, clock: Clock.Cl
  *
  * **When to use**
  *
- * Use this when OpenTelemetry instrumentation outside Effect has already
+ * Use when OpenTelemetry instrumentation outside Effect has already
  * produced a parent span context and an effect should continue that trace.
  *
  * @category propagation
@@ -360,7 +370,7 @@ export const withSpanContext: {
    *
    * **When to use**
    *
-   * Use this when OpenTelemetry instrumentation outside Effect has already
+   * Use when OpenTelemetry instrumentation outside Effect has already
    * produced a parent span context and an effect should continue that trace.
    *
    * @category propagation
@@ -374,7 +384,7 @@ export const withSpanContext: {
    *
    * **When to use**
    *
-   * Use this when OpenTelemetry instrumentation outside Effect has already
+   * Use when OpenTelemetry instrumentation outside Effect has already
    * produced a parent span context and an effect should continue that trace.
    *
    * @category propagation

package/src/WebSdk.ts

@@ -97,6 +97,25 @@ export const layerTracerProvider = (
 /**
  * Creates a Web OpenTelemetry layer from configuration, providing the resource and enabling tracing, metrics, and logging when configured.
  *
+ * **When to use**
+ *
+ * Use to install browser OpenTelemetry support for an Effect application when
+ * service metadata is provided in code and tracing, metrics, or logging should
+ * be enabled from supplied span processors, metric readers, or log record
+ * processors.
+ *
+ * **Details**
+ *
+ * The configuration can be provided lazily or effectfully. The layer always
+ * provides `Resource.Resource`; tracing, metrics, and logging are installed only
+ * when the corresponding processors or readers are non-empty.
+ *
+ * **Gotchas**
+ *
+ * Browser resource metadata is explicit; this layer does not read
+ * OpenTelemetry environment variables. Empty processor or reader arrays are
+ * treated as not configured.
+ *
  * @category layers
  * @since 4.0.0
  */
@@ -104,6 +123,25 @@ export const layer: {
   /**
    * Creates a Web OpenTelemetry layer from configuration, providing the resource and enabling tracing, metrics, and logging when configured.
    *
+   * **When to use**
+   *
+   * Use to install browser OpenTelemetry support for an Effect application when
+   * service metadata is provided in code and tracing, metrics, or logging should
+   * be enabled from supplied span processors, metric readers, or log record
+   * processors.
+   *
+   * **Details**
+   *
+   * The configuration can be provided lazily or effectfully. The layer always
+   * provides `Resource.Resource`; tracing, metrics, and logging are installed only
+   * when the corresponding processors or readers are non-empty.
+   *
+   * **Gotchas**
+   *
+   * Browser resource metadata is explicit; this layer does not read
+   * OpenTelemetry environment variables. Empty processor or reader arrays are
+   * treated as not configured.
+   *
    * @category layers
    * @since 4.0.0
    */
@@ -111,6 +149,25 @@ export const layer: {
   /**
    * Creates a Web OpenTelemetry layer from configuration, providing the resource and enabling tracing, metrics, and logging when configured.
    *
+   * **When to use**
+   *
+   * Use to install browser OpenTelemetry support for an Effect application when
+   * service metadata is provided in code and tracing, metrics, or logging should
+   * be enabled from supplied span processors, metric readers, or log record
+   * processors.
+   *
+   * **Details**
+   *
+   * The configuration can be provided lazily or effectfully. The layer always
+   * provides `Resource.Resource`; tracing, metrics, and logging are installed only
+   * when the corresponding processors or readers are non-empty.
+   *
+   * **Gotchas**
+   *
+   * Browser resource metadata is explicit; this layer does not read
+   * OpenTelemetry environment variables. Empty processor or reader arrays are
+   * treated as not configured.
+   *
    * @category layers
    * @since 4.0.0
    */

package/src/index.ts

@@ -5,150 +5,31 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
- * 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"
 
 /**
- * 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"
 
 /**
- * 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"
 
 /**
- * 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"
 
 /**
- * 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"
 
 /**
- * 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"