effect 4.0.0-beta.66 → 4.0.0-beta.67

package/src/unstable/observability/OtlpExporter.ts

@@ -1,4 +1,28 @@
 /**
+ * Low-level OTLP/HTTP batch exporter used by the observability modules for
+ * logs, metrics, and traces.
+ *
+ * This module owns the scoped transport loop for already-encoded telemetry
+ * payloads: callers provide the OTLP endpoint, request headers, a body encoder,
+ * and batching settings, then push records that should be delivered to a
+ * collector. It is useful when implementing a concrete signal exporter, such
+ * as the OTLP logger or tracer, or when wiring a snapshot-based exporter like
+ * metrics into the same lifecycle and retry behavior.
+ *
+ * The exporter sends HTTP POST requests with the provided `HttpClient`, disables
+ * tracer propagation for its own traffic, retries transient failures, and
+ * honors numeric `retry-after` values on 429 responses. Exports run on
+ * `exportInterval`, flush during scope finalization up to `shutdownTimeout`,
+ * and can also be triggered early when the buffered item count reaches
+ * `maxBatchSize`.
+ *
+ * Use `maxBatchSize: "disabled"` only for pull-style exporters whose `body`
+ * callback builds a fresh payload without relying on drained buffered items,
+ * because pushed data is not cleared in that mode. After an unrecovered export
+ * failure the exporter drops the buffered batch and disables exporting for 60
+ * seconds, so choose intervals, batch sizes, headers, and shutdown timeouts with
+ * collector limits and process shutdown behavior in mind.
+ *
  * @since 4.0.0
  */
 import { Clock } from "../../Clock.ts"
@@ -35,8 +59,15 @@ const policy = Schedule.forever.pipe(
 )
 
 /**
- * @since 4.0.0
+ * Creates a scoped OTLP batch exporter.
+ *
+ * The exporter buffers pushed data, periodically posts encoded batches to the
+ * configured URL, retries transient failures, temporarily disables exporting
+ * after unhandled failures, and flushes during scope finalization up to
+ * `shutdownTimeout`.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export const make: (
   options: {

package/src/unstable/observability/OtlpLogger.ts

@@ -1,4 +1,21 @@
 /**
+ * Exports Effect log records to an OpenTelemetry Protocol (OTLP) logs endpoint.
+ *
+ * Use this module to send Effect log messages, annotations, fiber identifiers,
+ * causes, and active span identifiers to an OpenTelemetry Collector or OTLP
+ * compatible observability backend. `make` is useful for custom logger wiring,
+ * while `layer` installs the logger for an application and can merge it with
+ * any existing loggers.
+ *
+ * Records are buffered by the shared OTLP exporter. `exportInterval`,
+ * `maxBatchSize`, and `shutdownTimeout` control periodic exports, early batch
+ * flushes, and how long scope finalization waits for the final flush. Resource
+ * options are attached to every export and override OpenTelemetry resource
+ * environment variables, so ensure a `service.name` is available through the
+ * options, `OTEL_RESOURCE_ATTRIBUTES`, or `OTEL_SERVICE_NAME`; use `headers`
+ * for collector authentication and `excludeLogSpans` when log span duration
+ * attributes would be too noisy.
+ *
  * @since 4.0.0
  */
 import * as Arr from "../../Array.ts"
@@ -19,8 +36,14 @@ import * as OtlpResource from "./OtlpResource.ts"
 import { OtlpSerialization } from "./OtlpSerialization.ts"
 
 /**
- * @since 4.0.0
+ * Creates an Effect `Logger` that exports log records through OTLP.
+ *
+ * The logger serializes records with the configured resource, sends them
+ * through the OTLP exporter, and requires `Scope` so pending records can be
+ * flushed on shutdown.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export const make: (
   options: {
@@ -76,8 +99,12 @@ export const make: (
 })
 
 /**
- * @since 4.0.0
+ * Installs the OTLP logger created by `make` as an Effect logging layer.
+ *
+ * By default the OTLP logger is merged with any existing loggers.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layer = (options: {
   readonly url: string
@@ -98,6 +125,8 @@ export const layer = (options: {
   })
 
 /**
+ * OTLP logs payload serialized by `OtlpLogger`.
+ *
  * @since 4.0.0
  */
 export interface LogsData {

package/src/unstable/observability/OtlpMetrics.ts

@@ -1,4 +1,26 @@
 /**
+ * OTLP/HTTP metrics exporter for Effect's Metric system.
+ *
+ * This module periodically snapshots the metrics registered in the current
+ * Effect context, serializes them as OTLP resource metrics, and posts them to a
+ * metrics endpoint such as an OpenTelemetry Collector or vendor OTLP intake.
+ * It is typically installed with `layer` in long-running services that already
+ * update `Metric` counters, gauges, histograms, frequencies, or summaries and
+ * need those values exported without adding instrumentation-specific plumbing
+ * to the application code.
+ *
+ * Pass the concrete `/v1/metrics` endpoint to `make` or `layer`, or use the
+ * higher-level `Otlp` module when you want `baseUrl` path construction for all
+ * signals. The exporter requires an `HttpClient` and an `OtlpSerialization`
+ * implementation, takes resource metadata from explicit options or standard
+ * OTEL resource environment variables, and uses the resource `service.name` as
+ * the instrumentation scope name. Choose `temporality` for the target backend:
+ * cumulative is the default, while delta derives per-export changes from the
+ * previous snapshot. Gauges always report their current value, and delta
+ * histograms and summaries keep interval counts and sums from previous
+ * snapshots, so tune export intervals and shutdown timeouts with backend
+ * expectations and process shutdown behavior in mind.
+ *
  * @since 4.0.0
  */
 import * as Arr from "../../Array.ts"
@@ -26,7 +48,8 @@ import { OtlpSerialization } from "./OtlpSerialization.ts"
  * - `"delta"`: Reports changes since the last export. Each interval is
  *   independent with no dependency on previous measurements.
  *
- * @example
+ * **Example** (Configuring aggregation temporality)
+ *
  * ```ts
  * import * as OtlpMetrics from "effect/unstable/observability/OtlpMetrics"
  *
@@ -43,14 +66,20 @@ import { OtlpSerialization } from "./OtlpSerialization.ts"
  * })
  * ```
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export type AggregationTemporality = "cumulative" | "delta"
 
 /**
- * @since 4.0.0
+ * Starts a scoped OTLP metrics exporter.
+ *
+ * The exporter snapshots registered Effect metrics on the configured interval,
+ * serializes them with the selected aggregation temporality, and flushes during
+ * scope finalization up to `shutdownTimeout`.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export const make: (options: {
   readonly url: string
@@ -429,8 +458,10 @@ export const make: (options: {
 })
 
 /**
- * @since 4.0.0
+ * Layer that starts the OTLP metrics exporter created by `make`.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layer = (options: {
   readonly url: string
@@ -446,6 +477,8 @@ export const layer = (options: {
 }): Layer.Layer<never, never, HttpClient.HttpClient | OtlpSerialization> => Layer.effectDiscard(make(options))
 
 /**
+ * OTLP metrics payload serialized by `OtlpMetrics`.
+ *
  * @since 4.0.0
  */
 export interface MetricsData {

package/src/unstable/observability/OtlpResource.ts

@@ -1,4 +1,23 @@
 /**
+ * Helpers and data types for describing the OTLP resource attached to exported
+ * logs, metrics, and traces.
+ *
+ * A resource identifies the service that produced telemetry and carries
+ * process- or deployment-level attributes that should be shared across every
+ * signal sent by the Effect OTLP logger, metrics exporter, and tracer. Use this
+ * module when building explicit resource metadata, reading the standard OTEL
+ * resource environment variables, or converting application metadata into OTLP
+ * `KeyValue` / `AnyValue` shapes before serialization.
+ *
+ * `service.name` is required because the signal exporters also use it as the
+ * instrumentation scope name. Explicit resource options take precedence over
+ * `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_SERVICE_NAME`, and
+ * `OTEL_SERVICE_VERSION`; `service.name` and `service.version` are normalized
+ * through the service metadata inputs and re-added as canonical OTLP
+ * attributes rather than left in the custom attribute map. Attribute values are
+ * converted to OTLP scalar or array values where possible, with unsupported
+ * runtime values formatted as strings.
+ *
  * @since 4.0.0
  */
 import * as Config from "../../Config.ts"
@@ -7,8 +26,10 @@ import { format } from "../../Formatter.ts"
 import * as Schema from "../../Schema.ts"
 
 /**
- * @since 4.0.0
+ * OTLP resource metadata attached to exported logs, metrics, and traces.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export interface Resource {
   /** Resource attributes */
@@ -18,8 +39,13 @@ export interface Resource {
 }
 
 /**
- * @since 4.0.0
+ * Creates an OTLP resource from service metadata and additional attributes.
+ *
+ * The resource always includes `service.name`, includes `service.version` when
+ * provided, and converts custom attributes into OTLP attribute values.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export const make = (options: {
   readonly serviceName: string
@@ -51,8 +77,15 @@ export const make = (options: {
 }
 
 /**
- * @since 4.0.0
+ * Creates an OTLP resource from explicit options and OpenTelemetry
+ * configuration.
+ *
+ * Explicit options override `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_SERVICE_NAME`,
+ * and `OTEL_SERVICE_VERSION`; missing required configuration is converted to a
+ * defect.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export const fromConfig: (
   options?: {
@@ -86,8 +119,12 @@ export const fromConfig: (
 }, Effect.orDie)
 
 /**
- * @since 4.0.0
+ * Returns the `service.name` attribute from an OTLP resource.
+ *
+ * Throws if the resource does not contain a string `service.name` attribute.
+ *
  * @category Attributes
+ * @since 4.0.0
  */
 export const serviceNameUnsafe = (resource: Resource): string => {
   const serviceNameAttribute = resource.attributes.find(
@@ -100,8 +137,10 @@ export const serviceNameUnsafe = (resource: Resource): string => {
 }
 
 /**
- * @since 4.0.0
+ * Converts key/value entries into OTLP `KeyValue` attributes.
+ *
  * @category Attributes
+ * @since 4.0.0
  */
 export const entriesToAttributes = (entries: Iterable<[string, unknown]>): Array<KeyValue> => {
   const attributes: Array<KeyValue> = []
@@ -115,8 +154,13 @@ export const entriesToAttributes = (entries: Iterable<[string, unknown]>): Array
 }
 
 /**
- * @since 4.0.0
+ * Converts an arbitrary JavaScript value into an OTLP `AnyValue`.
+ *
+ * Arrays are converted recursively, primitive values use their matching OTLP
+ * fields, and unsupported values are formatted as strings.
+ *
  * @category Attributes
+ * @since 4.0.0
  */
 export const unknownToAttributeValue = (value: unknown): AnyValue => {
   if (Array.isArray(value)) {
@@ -155,8 +199,10 @@ export const unknownToAttributeValue = (value: unknown): AnyValue => {
 }
 
 /**
- * @since 4.0.0
+ * An OTLP attribute represented as a string key and typed value.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export interface KeyValue {
   /** KeyValue key */
@@ -166,8 +212,10 @@ export interface KeyValue {
 }
 
 /**
- * @since 4.0.0
+ * OTLP `AnyValue` payload for scalar, array, key/value-list, or byte values.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export interface AnyValue {
   /** AnyValue stringValue */
@@ -187,8 +235,10 @@ export interface AnyValue {
 }
 
 /**
- * @since 4.0.0
+ * OTLP array value containing nested `AnyValue` entries.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export interface ArrayValue {
   /** ArrayValue values */
@@ -196,8 +246,10 @@ export interface ArrayValue {
 }
 
 /**
- * @since 4.0.0
+ * OTLP key/value-list value containing nested attributes.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export interface KeyValueList {
   /** KeyValueList values */
@@ -205,8 +257,10 @@ export interface KeyValueList {
 }
 
 /**
- * @since 4.0.0
+ * Low and high 32-bit parts of a 64-bit integer value.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export interface LongBits {
   low: number
@@ -214,7 +268,9 @@ export interface LongBits {
 }
 
 /**
- * @since 4.0.0
+ * Accepted runtime representations for an OTLP/protobuf fixed 64-bit value.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export type Fixed64 = LongBits | string | number

package/src/unstable/observability/OtlpSerialization.ts

@@ -1,4 +1,21 @@
 /**
+ * Defines the serialization boundary used by the OTLP observability layers.
+ *
+ * `OtlpSerialization` converts Effect's in-memory OTLP trace, metric, and log
+ * data into `HttpBody` values so exporters can send them to collectors over
+ * OTLP/HTTP. Use this module to choose between the JSON encoding that is useful
+ * for debugging and collector endpoints that explicitly accept OTLP/HTTP JSON,
+ * and the protobuf encoding commonly expected by production OpenTelemetry
+ * collectors.
+ *
+ * The JSON layer writes the telemetry structures directly with
+ * `HttpBody.jsonUnsafe`; the protobuf layer encodes the same structures with
+ * the internal OTLP protobuf encoder and sets the `application/x-protobuf`
+ * content type. Endpoint paths, authentication headers, batching, retries, and
+ * shutdown flushing are handled by the OTLP exporter layers that consume this
+ * service, while this module focuses only on preserving the wire format chosen
+ * for traces, metrics, and logs.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -10,8 +27,11 @@ import type { MetricsData } from "./OtlpMetrics.ts"
 import type { TraceData } from "./OtlpTracer.ts"
 
 /**
- * @since 4.0.0
+ * Service for serializing OTLP traces, metrics, and logs into HTTP request
+ * bodies.
+ *
  * @category Services
+ * @since 4.0.0
  */
 export class OtlpSerialization extends Context.Service<OtlpSerialization, {
   readonly traces: (data: TraceData) => HttpBody.HttpBody
@@ -20,8 +40,10 @@ export class OtlpSerialization extends Context.Service<OtlpSerialization, {
 }>()("effect/observability/OtlpSerialization") {}
 
 /**
- * @since 4.0.0
+ * Provides `OtlpSerialization` using OTLP/HTTP JSON bodies.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerJson = Layer.succeed(OtlpSerialization, {
   traces: (spans) => HttpBody.jsonUnsafe(spans),
@@ -30,8 +52,11 @@ export const layerJson = Layer.succeed(OtlpSerialization, {
 })
 
 /**
- * @since 4.0.0
+ * Provides `OtlpSerialization` using protobuf-encoded OTLP bodies with the
+ * `application/x-protobuf` content type.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerProtobuf = Layer.succeed(OtlpSerialization, {
   traces: (spans) =>

package/src/unstable/observability/OtlpTracer.ts

@@ -1,4 +1,26 @@
 /**
+ * Exports Effect spans to an OpenTelemetry Protocol (OTLP) traces endpoint.
+ *
+ * This module creates a `Tracer.Tracer` backed by the shared OTLP/HTTP batch
+ * exporter, so Effect spans created with tracing APIs can be delivered to an
+ * OpenTelemetry Collector, vendor OTLP intake, or local development collector.
+ * Use `make` when you need to install the tracer manually, or `layer` when an
+ * application should provide it through the Effect environment.
+ *
+ * Pass a concrete traces endpoint, typically `/v1/traces`, or use the
+ * higher-level `Otlp` module when you want `baseUrl` path construction for all
+ * observability signals. The tracer exports only ended sampled spans, converts
+ * span attributes, events, links, status, parent identifiers, and failure
+ * causes into OTLP trace data, and groups every batch under the configured
+ * resource. Resource options are resolved through `OtlpResource`, so ensure a
+ * stable `service.name` is available through options or standard OTEL resource
+ * environment variables because it is also used as the instrumentation scope
+ * name. Tune `exportInterval`, `maxBatchSize`, and `shutdownTimeout` for the
+ * target backend and process shutdown behavior, provide `headers` for
+ * authentication or routing, choose an `OtlpSerialization` layer accepted by
+ * the endpoint, and use `context` only when a backend needs custom evaluation
+ * around the active span.
+ *
  * @since 4.0.0
  */
 import * as Cause from "../../Cause.ts"
@@ -21,8 +43,14 @@ import * as OtlpResource from "./OtlpResource.ts"
 import { OtlpSerialization } from "./OtlpSerialization.ts"
 
 /**
- * @since 4.0.0
+ * Creates a `Tracer` that exports ended sampled spans to an OTLP traces
+ * endpoint.
+ *
+ * Spans are batched using the configured interval and batch size, serialized
+ * with `OtlpSerialization`, and flushed when the surrounding `Scope` closes.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export const make: (
   options: {
@@ -99,8 +127,10 @@ export const make: (
 })
 
 /**
- * @since 4.0.0
+ * Provides `Tracer.Tracer` using the OTLP tracer created by `make`.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layer: (options: {
   readonly url: string
@@ -274,6 +304,8 @@ const makeOtlpSpan = (self: SpanImpl): OtlpSpan => {
 }
 
 /**
+ * Root OTLP traces payload containing spans grouped by resource.
+ *
  * @since 4.0.0
  */
 export interface TraceData {
@@ -281,6 +313,8 @@ export interface TraceData {
 }
 
 /**
+ * Group of OTLP scope spans associated with a single resource.
+ *
  * @since 4.0.0
  */
 export interface ResourceSpan {
@@ -290,6 +324,8 @@ export interface ResourceSpan {
 }
 
 /**
+ * Group of OTLP spans emitted by a single instrumentation scope.
+ *
  * @since 4.0.0
  */
 export interface ScopeSpan {

package/src/unstable/observability/PrometheusMetrics.ts

@@ -1,10 +1,27 @@
 /**
  * Prometheus metrics exporter for Effect's Metric system.
  *
- * This module provides functionality to export Effect metrics in the Prometheus
- * exposition format, making them scrapeable by Prometheus servers.
+ * This module snapshots the metrics registered in the current Effect context
+ * and renders them in the Prometheus text exposition format. It is intended for
+ * services that already record `Metric` counters, gauges, histograms,
+ * frequencies, or summaries and need a pull-based `/metrics` endpoint, or for
+ * integrations that want the formatted scrape body for a custom HTTP server.
+ *
+ * Use `format` when you need the current runtime's registry rendered as a
+ * string, `formatUnsafe` when you already have the `Context`, and `layerHttp`
+ * when an `HttpRouter` should serve `GET /metrics` directly. Formatting happens
+ * at scrape time; the module does not push metrics, schedule exports, or start
+ * an HTTP server on its own. Make sure the route is installed in the same
+ * application context that records the metrics you want to expose.
+ *
+ * Metric and label names are sanitized for Prometheus, optional prefixes and
+ * name mappers are applied before output, and metric attributes become labels.
+ * Keep attributes low-cardinality, avoid relying on invalid characters being
+ * preserved exactly, and configure Prometheus to scrape the route served by
+ * `layerHttp` with the expected `text/plain; version=0.0.4` response.
+ *
+ * **Example** (Exporting Prometheus metrics)
  *
- * @example
  * ```ts
  * import { Effect, Metric } from "effect"
  * import * as PrometheusMetrics from "effect/unstable/observability/PrometheusMetrics"
@@ -37,7 +54,8 @@ import * as HttpServerResponse from "../http/HttpServerResponse.ts"
 /**
  * A function that transforms metric names before formatting.
  *
- * @example
+ * **Example** (Mapping metric names)
+ *
  * ```ts
  * import type * as PrometheusMetrics from "effect/unstable/observability/PrometheusMetrics"
  *
@@ -46,16 +64,16 @@ import * as HttpServerResponse from "../http/HttpServerResponse.ts"
  *   name.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase()
  * ```
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export type MetricNameMapper = (name: string) => string
 
 /**
  * Options for formatting metrics.
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export interface FormatOptions {
   /**
@@ -72,8 +90,8 @@ export interface FormatOptions {
 /**
  * Options for exporting Prometheus metrics over HTTP.
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export interface HttpOptions extends FormatOptions {
   /**
@@ -85,7 +103,8 @@ export interface HttpOptions extends FormatOptions {
 /**
  * Format all metrics in the registry to Prometheus exposition format.
  *
- * @example
+ * **Example** (Formatting metrics)
+ *
  * ```ts
  * import { Effect, Metric } from "effect"
  * import * as PrometheusMetrics from "effect/unstable/observability/PrometheusMetrics"
@@ -109,8 +128,8 @@ export interface HttpOptions extends FormatOptions {
  * })
  * ```
  *
- * @since 4.0.0
  * @category Formatting
+ * @since 4.0.0
  */
 export const format: (options?: FormatOptions | undefined) => Effect.Effect<string> = Effect.fnUntraced(
   function*(options) {
@@ -125,8 +144,8 @@ export const format: (options?: FormatOptions | undefined) => Effect.Effect<stri
  * This is a low-level function that requires access to the context.
  * Most users should use `format` instead.
  *
- * @since 4.0.0
  * @category Formatting
+ * @since 4.0.0
  */
 export const formatUnsafe = (
   context: Context.Context<never>,
@@ -166,7 +185,8 @@ export const formatUnsafe = (
  * metrics in Prometheus exposition format. By default, the endpoint is
  * registered at `/metrics`, but this can be customized via the `path` option.
  *
- * @example
+ * **Example** (Serving metrics over HTTP)
+ *
  * ```ts
  * import * as PrometheusMetrics from "effect/unstable/observability/PrometheusMetrics"
  *
@@ -180,8 +200,8 @@ export const formatUnsafe = (
  * })
  * ```
  *
- * @since 4.0.0
  * @category Http
+ * @since 4.0.0
  */
 export const layerHttp = (
   options?: HttpOptions | undefined

package/src/unstable/observability/index.ts

@@ -45,7 +45,8 @@ export * as OtlpTracer from "./OtlpTracer.ts"
  * This module provides functionality to export Effect metrics in the Prometheus
  * exposition format, making them scrapeable by Prometheus servers.
  *
- * @example
+ * **Example** (Exporting Prometheus metrics)
+ *
  * ```ts
  * import { Effect, Metric } from "effect"
  * import * as PrometheusMetrics from "effect/unstable/observability/PrometheusMetrics"