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

package/dist/WebSdk.js.map

@@ -1 +1 @@
-{"version":3,"file":"WebSdk.js","names":["WebTracerProvider","Effect","constant","Layer","isNonEmpty","Logger","Metrics","Resource","Tracer","layerTracerProvider","processor","config","effect","OtelTracerProvider","gen","resource","acquireRelease","sync","provider","undefined","spanProcessors","Array","isArray","ignore","promise","forceFlush","then","shutdown","layer","evaluate","unwrap","isEffect","ResourceLive","TracerLive","spanProcessor","provide","tracerConfig","empty","LoggerLive","logRecordProcessor","mergeWithExisting","loggerMergeWithExisting","layerLoggerProvider","loggerProviderConfig","MetricsLive","metricReader","temporality","metricTemporality","mergeAll","pipe","provideMerge"],"sources":["../src/WebSdk.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"WebSdk.js","names":["WebTracerProvider","Effect","constant","Layer","isNonEmpty","Logger","Metrics","Resource","Tracer","layerTracerProvider","processor","config","effect","OtelTracerProvider","gen","resource","acquireRelease","sync","provider","undefined","spanProcessors","Array","isArray","ignore","promise","forceFlush","then","shutdown","layer","evaluate","unwrap","isEffect","ResourceLive","TracerLive","spanProcessor","provide","tracerConfig","empty","LoggerLive","logRecordProcessor","mergeWithExisting","loggerMergeWithExisting","layerLoggerProvider","loggerProviderConfig","MetricsLive","metricReader","temporality","metricTemporality","mergeAll","pipe","provideMerge"],"sources":["../src/WebSdk.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/index.d.ts

@@ -1,28 +1,147 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 /**
- * @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";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;GAEG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC;;GAEG;AACH,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAEvC;;GAEG;AACH,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAEvC;;GAEG;AACH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;GAEG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC;;GAEG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -1,29 +1,148 @@
 /**
- * @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.js";
 /**
- * @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.js";
 /**
- * @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.js";
 /**
- * @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.js";
 /**
- * @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.js";
 /**
- * @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.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["Logger","Metrics","NodeSdk","Resource","Tracer","WebSdk"],"sources":["../src/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAIA;AAEA;;;AAGA,OAAO,KAAKA,MAAM,MAAM,aAAa;AAErC;;;AAGA,OAAO,KAAKC,OAAO,MAAM,cAAc;AAEvC;;;AAGA,OAAO,KAAKC,OAAO,MAAM,cAAc;AAEvC;;;AAGA,OAAO,KAAKC,QAAQ,MAAM,eAAe;AAEzC;;;AAGA,OAAO,KAAKC,MAAM,MAAM,aAAa;AAErC;;;AAGA,OAAO,KAAKC,MAAM,MAAM,aAAa","ignoreList":[]}
+{"version":3,"file":"index.js","names":["Logger","Metrics","NodeSdk","Resource","Tracer","WebSdk"],"sources":["../src/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAIA;AAEA;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,OAAO,KAAKA,MAAM,MAAM,aAAa;AAErC;;;;;;;;;;;;;;;;;;;AAmBA,OAAO,KAAKC,OAAO,MAAM,cAAc;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,KAAKC,OAAO,MAAM,cAAc;AAEvC;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,KAAKC,QAAQ,MAAM,eAAe;AAEzC;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,KAAKC,MAAM,MAAM,aAAa;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,OAAO,KAAKC,MAAM,MAAM,aAAa","ignoreList":[]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@effect/opentelemetry",
   "type": "module",
-  "version": "4.0.0-beta.66",
+  "version": "4.0.0-beta.68",
   "license": "MIT",
   "description": "OpenTelemetry integration for Effect",
   "homepage": "https://effect.website",
@@ -63,7 +63,7 @@
     "@opentelemetry/sdk-trace-node": "^2.0.0",
     "@opentelemetry/sdk-trace-web": "^2.0.0",
     "@opentelemetry/semantic-conventions": "^1.33.0",
-    "effect": "^4.0.0-beta.66"
+    "effect": "^4.0.0-beta.68"
   },
   "peerDependenciesMeta": {
     "@opentelemetry/api": {
@@ -93,18 +93,18 @@
   },
   "devDependencies": {
     "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/api-logs": "^0.214.0",
-    "@opentelemetry/context-async-hooks": "^2.6.1",
-    "@opentelemetry/exporter-metrics-otlp-http": "0.214.0",
-    "@opentelemetry/exporter-prometheus": "^0.214.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.214.0",
-    "@opentelemetry/otlp-exporter-base": "^0.214.0",
-    "@opentelemetry/resources": "^2.6.1",
-    "@opentelemetry/sdk-logs": "^0.214.0",
-    "@opentelemetry/sdk-metrics": "^2.6.1",
-    "@opentelemetry/sdk-trace-base": "^2.6.1",
-    "@opentelemetry/sdk-trace-node": "^2.6.1",
-    "@opentelemetry/sdk-trace-web": "^2.6.1",
+    "@opentelemetry/api-logs": "^0.217.0",
+    "@opentelemetry/context-async-hooks": "^2.7.1",
+    "@opentelemetry/exporter-metrics-otlp-http": "0.217.0",
+    "@opentelemetry/exporter-prometheus": "^0.217.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.217.0",
+    "@opentelemetry/otlp-exporter-base": "^0.217.0",
+    "@opentelemetry/resources": "^2.7.1",
+    "@opentelemetry/sdk-logs": "^0.217.0",
+    "@opentelemetry/sdk-metrics": "^2.7.1",
+    "@opentelemetry/sdk-trace-base": "^2.7.1",
+    "@opentelemetry/sdk-trace-node": "^2.7.1",
+    "@opentelemetry/sdk-trace-web": "^2.7.1",
     "@opentelemetry/semantic-conventions": "^1.40.0"
   },
   "scripts": {

package/src/Logger.ts

@@ -1,5 +1,26 @@
 /**
- * @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
  */
 import { SeverityNumber } from "@opentelemetry/api-logs"
 import * as Otel from "@opentelemetry/sdk-logs"
@@ -19,8 +40,10 @@ 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 Context.Service<
   OtelLoggerProvider,
@@ -35,8 +58,8 @@ export class OtelLoggerProvider extends Context.Service<
  * (e.g. Info=20000), which falls outside the OTel spec — backends that
  * validate the field map such values to `UNSPECIFIED`.
  *
- * @since 1.0.0
- * @category Conversions
+ * @category converting
+ * @since 4.0.0
  */
 export const logLevelToSeverityNumber = (level: LogLevel.LogLevel): SeverityNumber => {
   switch (level) {
@@ -58,8 +81,10 @@ export const logLevelToSeverityNumber = (level: LogLevel.LogLevel): SeverityNumb
 }
 
 /**
- * @since 1.0.0
- * @category Constructors
+ * 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>,
@@ -104,8 +129,10 @@ export const make: Effect.Effect<
 })
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Creates a layer that installs the OpenTelemetry-backed Effect logger, merging with existing loggers by default.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer = (options: {
   /**
@@ -124,8 +151,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,21 @@
 /**
- * @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
  */
 import type { MetricProducer, MetricReader } from "@opentelemetry/sdk-metrics"
 import type * as Arr from "effect/Array"
@@ -21,16 +37,16 @@ import { Resource } from "./Resource.ts"
  * - `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
+ * @category constructors
+ * @since 4.0.0
  */
 export const makeProducer = (temporality?: TemporalityPreference): Effect.Effect<MetricProducer, never, Resource> =>
   Effect.gen(function*() {
@@ -42,8 +58,8 @@ export const makeProducer = (temporality?: TemporalityPreference): Effect.Effect
 /**
  * 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 +90,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 +115,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,24 @@ 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.
+ *
+ * @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.
+   *
+   * @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.
+   *
+   * @category layers
+   * @since 4.0.0
    */
   <R, E>(evaluate: Effect.Effect<Configuration, E, R>): Layer.Layer<Resource.Resource, E, R>
 } = (
@@ -130,7 +162,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