effect 4.0.0-beta.101 → 4.0.0-beta.103

package/src/unstable/observability/OtlpExporter.ts

@@ -13,6 +13,9 @@ import * as Context from "../../Context.ts"
 import * as Duration from "../../Duration.ts"
 import * as Effect from "../../Effect.ts"
 import * as Fiber from "../../Fiber.ts"
+import * as FiberSet from "../../FiberSet.ts"
+import { identity } from "../../Function.ts"
+import * as Layer from "../../Layer.ts"
 import * as Num from "../../Number.ts"
 import * as Option from "../../Option.ts"
 import * as Schedule from "../../Schedule.ts"
@@ -23,6 +26,24 @@ import * as HttpClientError from "../../unstable/http/HttpClientError.ts"
 import * as HttpClientRequest from "../../unstable/http/HttpClientRequest.ts"
 import type { HttpBody } from "../http/HttpBody.ts"
 
+const retryAfterDelay = (value: string | undefined): Effect.Effect<Duration.Duration> => {
+  const seconds = Option.fromUndefinedOr(value).pipe(Option.flatMap(Num.parse))
+  if (Option.isSome(seconds)) {
+    return Effect.succeed(Duration.seconds(seconds.value))
+  }
+  if (value === undefined) {
+    return Effect.succeed(Duration.seconds(5))
+  }
+  const timestamp = Date.parse(value)
+  if (Number.isNaN(timestamp)) {
+    return Effect.succeed(Duration.seconds(5))
+  }
+  return Effect.map(
+    Clock,
+    (clock) => Duration.millis(Math.max(timestamp - clock.currentTimeMillisUnsafe(), 1))
+  )
+}
+
 const policy = Schedule.forever.pipe(
   Schedule.passthrough,
   Schedule.addDelay(({ output: error }) => {
@@ -31,16 +52,101 @@ const policy = Schedule.forever.pipe(
       && error.reason._tag === "StatusCodeError"
       && error.reason.response.status === 429
     ) {
-      const retryAfter = Option.fromUndefinedOr(error.reason.response.headers["retry-after"]).pipe(
-        Option.flatMap(Num.parse),
-        Option.getOrElse(() => 5)
-      )
-      return Effect.succeed(Duration.seconds(retryAfter))
+      return retryAfterDelay(error.reason.response.headers["retry-after"])
     }
     return Effect.succeed(Duration.seconds(1))
   })
 )
 
+/**
+ * Registry of exporter flush operations, used to manually drain buffered
+ * telemetry before the surrounding scope closes.
+ *
+ * **Details**
+ *
+ * Every exporter created by `make` registers its export operation here, so a
+ * single `flush` drains all signals sharing the registry. `flush` returns only
+ * after the exports it initiated have settled, cannot fail, and respects each
+ * exporter's temporary-disable window. Wrap it with `Effect.timeoutOption` to
+ * bound its duration at the call site.
+ *
+ * @category services
+ * @since 4.0.0
+ */
+export class Flusher extends Context.Service<Flusher, {
+  /**
+   * Drains all registered exporters concurrently and cannot fail.
+   *
+   * **Details**
+   *
+   * There is no built-in timeout; use `Effect.timeoutOption` to bound the
+   * operation. Exporters in their 60-second `disabledUntil` window are skipped.
+   *
+   * **Example** (Flushing exporters)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect } from "effect"
+   * import { OtlpExporter } from "effect/unstable/observability"
+   *
+   * const program = Effect.gen(function*() {
+   *   const flusher = yield* OtlpExporter.Flusher
+   *   yield* flusher.flush
+   *   return "flushed"
+   * }).pipe(Effect.provide(OtlpExporter.layerFlusher))
+   *
+   * await Effect.runPromise(program) // => "flushed"
+   * ```
+   */
+  readonly flush: Effect.Effect<void>
+  readonly register: (run: Effect.Effect<void>) => Effect.Effect<void, never, Scope.Scope>
+}>()(
+  "effect/observability/OtlpExporter/Flusher"
+) {}
+
+/**
+ * Provides a `Flusher` backed by a fresh registry.
+ *
+ * **Details**
+ *
+ * This is intentionally a single module-level constant rather than a factory:
+ * layer memoization is keyed by layer instance, so every signal layer
+ * referencing this same constant shares one registry per layer build, and one
+ * `flush` drains traces, logs and metrics together. A factory returning a new
+ * layer per call would silently create one registry per signal.
+ *
+ * Registration is scoped — an exporter is removed from the registry when its
+ * own scope closes. Flushing with an empty registry is a no-op.
+ *
+ * Note that `flush` cannot await an export that was already in flight when it
+ * was called (for example one started by the export interval); it only waits
+ * for the exports it initiates.
+ *
+ * @category layers
+ * @since 4.0.0
+ */
+export const layerFlusher: Layer.Layer<Flusher> = Layer.sync(Flusher, () => {
+  const registry = new Set<Effect.Effect<void>>()
+  return {
+    flush: Effect.suspend(() => {
+      if (registry.size === 0) {
+        return Effect.void
+      }
+      return Effect.forEach(registry, identity, {
+        concurrency: "unbounded",
+        discard: true
+      })
+    }),
+    register: (run) =>
+      Effect.flatMap(Scope.Scope, (scope) => {
+        registry.add(run)
+        return Scope.addFinalizer(
+          scope,
+          Effect.sync(() => registry.delete(run))
+        )
+      })
+  }
+})
+
 /**
  * Creates a scoped OTLP batch exporter.
  *
@@ -67,12 +173,11 @@ export const make: (
 ) => Effect.Effect<
   { readonly push: (data: unknown) => void },
   never,
-  HttpClient.HttpClient | Scope.Scope
+  Flusher | HttpClient.HttpClient | Scope.Scope
 > = Effect.fnUntraced(function*(options) {
   const services = yield* Effect.context<Scope.Scope | HttpClient.HttpClient>()
   const clock = Context.get(services, Clock)
   const scope = Context.get(services, Scope.Scope)
-  const runFork = Effect.runForkWith(services)
   const exportInterval = Duration.max(Duration.fromInputUnsafe(options.exportInterval), Duration.zero)
   let disabledUntil: number | undefined = undefined
 
@@ -122,9 +227,19 @@ export const make: (
     })
   )
 
+  const exportFibers = yield* FiberSet.make<void, never>()
+  const runExportFork = yield* FiberSet.runtime(exportFibers)<never>()
+
+  const flusher = yield* Flusher
+  yield* flusher.register(runExport)
+
   yield* Scope.addFinalizer(
     scope,
-    runExport.pipe(
+    Effect.suspend(() => {
+      if (disabledUntil !== undefined) return Effect.void
+      runExportFork(runExport)
+      return FiberSet.awaitEmpty(exportFibers)
+    }).pipe(
       Effect.ignore,
       Effect.interruptible,
       Effect.timeoutOption(options.shutdownTimeout)
@@ -132,7 +247,8 @@ export const make: (
   )
 
   yield* Effect.sleep(exportInterval).pipe(
-    Effect.andThen(runExport),
+    Effect.andThen(FiberSet.run(exportFibers, runExport)),
+    Effect.flatMap(Fiber.await),
     Effect.forever,
     Effect.forkIn(scope)
   )
@@ -142,7 +258,7 @@ export const make: (
       if (disabledUntil !== undefined) return
       buffer.push(data)
       if (options.maxBatchSize !== "disabled" && buffer.length >= options.maxBatchSize) {
-        Fiber.runIn(runFork(runExport), scope)
+        runExportFork(runExport)
       }
     }
   }

package/src/unstable/observability/OtlpLogger.ts

@@ -57,7 +57,7 @@ export const make: (
 ) => Effect.Effect<
   Logger.Logger<unknown, void>,
   never,
-  OtlpSerialization | HttpClient.HttpClient | Scope.Scope
+  Exporter.Flusher | OtlpSerialization | HttpClient.HttpClient | Scope.Scope
 > = Effect.fnUntraced(function*(options) {
   const serialization = yield* OtlpSerialization
   const otelResource = yield* OtlpResource.fromConfig(options.resource)
@@ -116,10 +116,10 @@ export const layer = (options: {
   readonly shutdownTimeout?: Duration.Input | undefined
   readonly excludeLogSpans?: boolean | undefined
   readonly mergeWithExisting?: boolean | undefined
-}): Layer.Layer<never, never, HttpClient.HttpClient | OtlpSerialization> =>
+}): Layer.Layer<Exporter.Flusher, never, HttpClient.HttpClient | OtlpSerialization> =>
   Logger.layer([make(options)], {
     mergeWithExisting: options.mergeWithExisting ?? true
-  })
+  }).pipe(Layer.provideMerge(Exporter.layerFlusher))
 
 /**
  * Creates an OTLP logs layer from OpenTelemetry configuration.
@@ -136,7 +136,7 @@ export const layerFromConfig = (options?: {
   readonly headers?: Headers.Input | undefined
   readonly excludeLogSpans?: boolean | undefined
   readonly mergeWithExisting?: boolean | undefined
-}): Layer.Layer<never, never, HttpClient.HttpClient | OtlpSerialization> =>
+}): Layer.Layer<Exporter.Flusher, never, HttpClient.HttpClient | OtlpSerialization> =>
   Effect.gen(function*() {
     const { disabled, endpoint, exporters } = yield* Config.all({
       disabled: Config.boolean("OTEL_SDK_DISABLED").pipe(Config.withDefault(false)),
@@ -145,7 +145,7 @@ export const layerFromConfig = (options?: {
     })
 
     if (disabled || !endpoint || !exporters.includes("otlp")) {
-      return Layer.empty
+      return Exporter.layerFlusher
     }
 
     const { baseTimeout, logsTimeout, exportTimeout, scheduleDelay, maxBatchSize } = yield* Config.all({

package/src/unstable/observability/OtlpMetrics.ts

@@ -40,7 +40,8 @@ import { OtlpSerialization } from "./OtlpSerialization.ts"
  *
  * **Example** (Configuring aggregation temporality)
  *
- * ```ts
+ * ```ts import.meta.vitest
+ * import { Layer } from "effect"
  * import { OtlpMetrics } from "effect/unstable/observability"
  *
  * // Use delta temporality for backends that prefer it (e.g., Datadog, Dynatrace)
@@ -54,6 +55,8 @@ import { OtlpSerialization } from "./OtlpSerialization.ts"
  *   url: "http://localhost:4318/v1/metrics",
  *   temporality: "cumulative" // This is the default
  * })
+ *
+ * const result = [Layer.isLayer(metricsLayer), Layer.isLayer(cumulativeLayer)] // => [true, true]
  * ```
  *
  * @category models
@@ -67,6 +70,9 @@ export type AggregationTemporality = "cumulative" | "delta"
  * **Details**
  *
  * 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`.
+ * Manual flushing also triggers a snapshot. With delta temporality, each
+ * snapshot advances the previous-export state, so frequent flushes narrow the
+ * delta aggregation windows.
  *
  * @category constructors
  * @since 4.0.0
@@ -85,7 +91,7 @@ export const make: (options: {
 }) => Effect.Effect<
   void,
   never,
-  HttpClient.HttpClient | OtlpSerialization | Scope.Scope
+  Exporter.Flusher | HttpClient.HttpClient | OtlpSerialization | Scope.Scope
 > = Effect.fnUntraced(function*(options) {
   const clock = yield* Clock
   const serialization = yield* OtlpSerialization
@@ -464,7 +470,8 @@ export const layer = (options: {
   readonly exportInterval?: Duration.Input | undefined
   readonly shutdownTimeout?: Duration.Input | undefined
   readonly temporality?: AggregationTemporality | undefined
-}): Layer.Layer<never, never, HttpClient.HttpClient | OtlpSerialization> => Layer.effectDiscard(make(options))
+}): Layer.Layer<Exporter.Flusher, never, HttpClient.HttpClient | OtlpSerialization> =>
+  Layer.effectDiscard(make(options)).pipe(Layer.provideMerge(Exporter.layerFlusher))
 
 /**
  * Creates an OTLP metrics layer from OpenTelemetry configuration.
@@ -479,7 +486,7 @@ export const layerFromConfig = (options?: {
     readonly attributes?: Record<string, unknown>
   } | undefined
   readonly headers?: Headers.Input | undefined
-}): Layer.Layer<never, never, HttpClient.HttpClient | OtlpSerialization> =>
+}): Layer.Layer<Exporter.Flusher, never, HttpClient.HttpClient | OtlpSerialization> =>
   Effect.gen(function*() {
     const { disabled, endpoint, exporters } = yield* Config.all({
       disabled: Config.boolean("OTEL_SDK_DISABLED").pipe(Config.withDefault(false)),
@@ -487,7 +494,7 @@ export const layerFromConfig = (options?: {
       exporters: OtlpEnv.exporters("METRICS")
     })
     if (disabled || !endpoint || !exporters.includes("otlp")) {
-      return Layer.empty
+      return Exporter.layerFlusher
     }
 
     const { baseTimeout, metricsTimeout, exportTimeout, exportInterval, temporalityPreference } = yield* Config.all({

package/src/unstable/observability/OtlpResource.ts

@@ -70,11 +70,20 @@ export const make = (options: {
  * Creates an OTLP resource from explicit options and OpenTelemetry
  * configuration.
  *
+ * **When to use**
+ *
+ * Use when resource metadata may be configured in code or by the deployment
+ * environment. To let operators set the service identity, omit `serviceName`,
+ * `serviceVersion`, and their matching attributes, then use
+ * `OTEL_SERVICE_NAME` and `OTEL_RESOURCE_ATTRIBUTES`.
+ *
  * **Details**
  *
- * `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_SERVICE_NAME`, and
- * `OTEL_SERVICE_VERSION` override explicit options; missing required
- * configuration is converted to a defect.
+ * Explicit `serviceName` and `serviceVersion` options take precedence over
+ * matching explicit attributes. Explicit attributes take precedence over
+ * environment variables. `OTEL_SERVICE_NAME` and `OTEL_SERVICE_VERSION` take
+ * precedence over matching attributes in `OTEL_RESOURCE_ATTRIBUTES`. Missing
+ * required configuration is converted to a defect.
  *
  * @category constructors
  * @since 4.0.0
@@ -91,24 +100,24 @@ export const fromConfig: (
   readonly attributes?: Record<string, unknown> | undefined
 }) {
   const env = yield* Config.schema(
-    Schema.UndefinedOr(Config.Record(Schema.String, Schema.String)),
+    Schema.UndefinedOr(Config.Record(Schema.StringFromUriComponent, Schema.StringFromUriComponent)),
     "OTEL_RESOURCE_ATTRIBUTES"
   )
 
-  const serviceName = (yield* Config.schema(Schema.UndefinedOr(Schema.String), "OTEL_SERVICE_NAME"))
-    ?? env?.["service.name"] as string | undefined
+  const serviceName = options?.serviceName
     ?? options?.attributes?.["service.name"] as string | undefined
-    ?? options?.serviceName
+    ?? (yield* Config.schema(Schema.UndefinedOr(Schema.String), "OTEL_SERVICE_NAME"))
+    ?? env?.["service.name"] as string | undefined
     ?? (yield* Config.string("OTEL_SERVICE_NAME"))
 
-  const serviceVersion = (yield* Config.schema(Schema.UndefinedOr(Schema.String), "OTEL_SERVICE_VERSION"))
-    ?? env?.["service.version"] as string | undefined
+  const serviceVersion = options?.serviceVersion
     ?? options?.attributes?.["service.version"] as string | undefined
-    ?? options?.serviceVersion
+    ?? (yield* Config.schema(Schema.UndefinedOr(Schema.String), "OTEL_SERVICE_VERSION"))
+    ?? env?.["service.version"] as string | undefined
 
   const attributes = {
-    ...options?.attributes,
-    ...env
+    ...env,
+    ...options?.attributes
   }
 
   delete attributes["service.name"]
@@ -133,7 +142,7 @@ export const fromConfig: (
  *
  * Throws if the resource does not contain a string `service.name` attribute.
  *
- * @category Attributes
+ * @category attributes
  * @since 4.0.0
  */
 export const serviceNameUnsafe = (resource: Resource): string => {
@@ -149,7 +158,7 @@ export const serviceNameUnsafe = (resource: Resource): string => {
 /**
  * Converts key/value entries into OTLP `KeyValue` attributes.
  *
- * @category Attributes
+ * @category attributes
  * @since 4.0.0
  */
 export const entriesToAttributes = (entries: Iterable<[string, unknown]>): Array<KeyValue> => {
@@ -171,7 +180,7 @@ export const entriesToAttributes = (entries: Iterable<[string, unknown]>): Array
  * Arrays are converted recursively, primitive values use their matching OTLP
  * fields, and unsupported values are formatted as strings.
  *
- * @category Attributes
+ * @category attributes
  * @since 4.0.0
  */
 export const unknownToAttributeValue = (value: unknown): AnyValue => {
@@ -189,7 +198,7 @@ export const unknownToAttributeValue = (value: unknown): AnyValue => {
       }
     case "bigint":
       return {
-        intValue: Number(value)
+        intValue: String(value)
       }
     case "number":
       return Number.isInteger(value)
@@ -235,7 +244,7 @@ export interface AnyValue {
   /** AnyValue boolValue */
   boolValue?: boolean | null
   /** AnyValue intValue */
-  intValue?: number | null
+  intValue?: string | number | null
   /** AnyValue doubleValue */
   doubleValue?: number | null
   /** AnyValue arrayValue */

package/src/unstable/observability/OtlpTracer.ts

@@ -59,7 +59,7 @@ export const make: (
 ) => Effect.Effect<
   Tracer.Tracer,
   never,
-  OtlpSerialization | HttpClient.HttpClient | Scope.Scope
+  Exporter.Flusher | OtlpSerialization | HttpClient.HttpClient | Scope.Scope
 > = Effect.fnUntraced(function*(options) {
   const otelResource = yield* OtlpResource.fromConfig(options.resource)
   const serialization = yield* OtlpSerialization
@@ -134,7 +134,11 @@ export const layer: (options: {
   readonly maxBatchSize?: number | undefined
   readonly context?: (<X>(primitive: Tracer.EffectPrimitive<X>, span: Tracer.AnySpan) => X) | undefined
   readonly shutdownTimeout?: Duration.Input | undefined
-}) => Layer.Layer<never, never, OtlpSerialization | HttpClient.HttpClient> = flow(make, Layer.effect(Tracer.Tracer))
+}) => Layer.Layer<Exporter.Flusher, never, OtlpSerialization | HttpClient.HttpClient> = flow(
+  make,
+  Layer.effect(Tracer.Tracer),
+  Layer.provideMerge(Exporter.layerFlusher)
+)
 
 /**
  * Creates an OTLP traces layer from OpenTelemetry configuration.
@@ -150,7 +154,7 @@ export const layerFromConfig = (options?: {
   } | undefined
   readonly headers?: Headers.Input | undefined
   readonly context?: (<X>(primitive: Tracer.EffectPrimitive<X>, span: Tracer.AnySpan) => X) | undefined
-}): Layer.Layer<never, never, HttpClient.HttpClient | OtlpSerialization> =>
+}): Layer.Layer<Exporter.Flusher, never, HttpClient.HttpClient | OtlpSerialization> =>
   Effect.gen(function*() {
     const { disabled, endpoint, exporters } = yield* Config.all({
       disabled: Config.boolean("OTEL_SDK_DISABLED").pipe(Config.withDefault(false)),
@@ -159,7 +163,7 @@ export const layerFromConfig = (options?: {
     })
 
     if (disabled || !endpoint || !exporters.includes("otlp")) {
-      return Layer.empty
+      return Exporter.layerFlusher
     }
 
     const { baseTimeout, tracesTimeout, exportTimeout, scheduleDelay, maxBatchSize } = yield* Config.all({

package/src/unstable/observability/PrometheusMetrics.ts

@@ -19,12 +19,14 @@ import * as HttpServerResponse from "../http/HttpServerResponse.ts"
  *
  * **Example** (Mapping metric names)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { PrometheusMetrics } from "effect/unstable/observability"
  *
  * // Convert camelCase to snake_case
  * const mapper: PrometheusMetrics.MetricNameMapper = (name) =>
  *   name.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase()
+ *
+ * mapper("httpRequests") // => "http_requests"
  * ```
  *
  * @category models
@@ -68,7 +70,7 @@ export interface HttpOptions extends FormatOptions {
  *
  * **Example** (Formatting metrics)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Metric } from "effect"
  * import { PrometheusMetrics } from "effect/unstable/observability"
  *
@@ -88,7 +90,11 @@ export interface HttpOptions extends FormatOptions {
  *
  *   // Format with prefix
  *   const output2 = yield* PrometheusMetrics.format({ prefix: "myapp" })
+ *
+ *   return [output1.includes("api_requests_total"), output2.includes("myapp_active_connections")]
  * })
+ *
+ * Effect.runSync(program) // => [true, true]
  * ```
  *
  * @category formatting
@@ -156,7 +162,8 @@ export const formatUnsafe = (
  *
  * **Example** (Serving metrics over HTTP)
  *
- * ```ts
+ * ```ts import.meta.vitest
+ * import { Layer } from "effect"
  * import { PrometheusMetrics } from "effect/unstable/observability"
  *
  * // Create a layer that adds /metrics endpoint to the router
@@ -167,9 +174,11 @@ export const formatUnsafe = (
  *   path: "/prometheus/metrics",
  *   prefix: "myapp"
  * })
+ *
+ * const result = [Layer.isLayer(PrometheusLayer), Layer.isLayer(CustomPrometheusLayer)] // => [true, true]
  * ```
  *
- * @category Http
+ * @category layers
  * @since 4.0.0
  */
 export const layerHttp = (

package/src/unstable/observability/internal/otlpEnv.ts

@@ -11,7 +11,7 @@ const ExporterList = Config.Array(Schema.String).pipe(
   })
 )
 
-const HeadersRecord = Config.Record(Schema.String, Schema.String)
+const HeadersRecord = Config.Record(Schema.String, Schema.StringFromUriComponent)
 
 export const headers = (signal: Signal) =>
   Config.schema(HeadersRecord, `OTEL_EXPORTER_OTLP_${signal}_HEADERS`).pipe(

package/src/unstable/observability/internal/protobuf.ts

@@ -29,6 +29,9 @@ const encodeTag = (fieldNumber: number, wireType: WireType): number => (fieldNum
 export const encodeVarint = (value: number | bigint): Uint8Array => {
   const bytes: Array<number> = []
   let n = typeof value === "bigint" ? value : BigInt(value)
+  if (n < BigInt(0)) {
+    n = BigInt.asUintN(64, n)
+  }
   while (n > BigInt(127)) {
     bytes.push(Number(n & BigInt(127)) | 0x80)
     n >>= BigInt(7)