@smthrs/observability 0.35.0 → 1.0.0-rc.4

package/docs/api.md

@@ -0,0 +1,768 @@
+---
+title: "API reference"
+description: "Every public export of @smthrs/observability: the Otlp exporter layers, endpoint and resource validation, the logger layers, the journal forwarder and its durable schema, the runtime metric handles, and the three OpenTelemetry SDK bridges."
+---
+
+`@smthrs/observability` exports seven modules from its root entry point, and
+each is also importable from `@smthrs/observability/<Module>`:
+
+```ts
+import { Endpoint, JournalLogger, Logger, Metric, Otel, Otlp, Resource } from "@smthrs/observability"
+// or
+import * as Otlp from "@smthrs/observability/Otlp"
+```
+
+Two more modules are subpath-only, because each binds a host-specific
+OpenTelemetry SDK. `@smthrs/observability/package.json` is exported.
+
+| Import                              | Source                                                                                                                          | Platform |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------- |
+| `@smthrs/observability`             | [src/index.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/observability/src/index.ts)             | any      |
+| `@smthrs/observability/NodeOtel`    | [src/NodeOtel.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/observability/src/NodeOtel.ts)       | Node     |
+| `@smthrs/observability/BrowserOtel` | [src/BrowserOtel.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/observability/src/BrowserOtel.ts) | browser  |
+
+The package is tested with `effect@4.0.0-rc.115`. Layers, services, and schemas
+are Effect constructs: a `Layer` provides services, a scoped layer releases on
+scope close, and a schema decodes to an `Effect`.
+
+## Example
+
+```ts
+import * as Otlp from "@smthrs/observability/Otlp"
+
+const telemetry = Otlp.layerFetch({ baseUrl: "http://localhost:4318", serviceName: "deploy-status" })
+const program = Effect.logInfo("deploying the API").pipe(Effect.withSpan("deploy"))
+
+await Effect.runPromise(program.pipe(Effect.provide(telemetry), Effect.orDie, Effect.scoped))
+```
+
+## Otlp
+
+The default exporter. `Otlp` composes `effect/unstable/observability/Otlp` and
+nothing else, so it allocates no OpenTelemetry SDK and never resolves a `node:`
+built-in. All three signals are JSON-serialized and posted below the configured
+base URL at `/v1/logs`, `/v1/metrics`, and `/v1/traces`.
+
+### Otlp.Options
+
+```ts
+interface Options {
+  readonly baseUrl: string
+  readonly serviceName?: string | undefined
+  readonly serviceVersion?: string | undefined
+  readonly attributes?: Record<string, unknown> | undefined
+  readonly headers?: Headers.Input | undefined
+  readonly exportInterval?: Duration.Input | undefined
+  readonly shutdownTimeout?: Duration.Input | undefined
+}
+```
+
+- `baseUrl`: the collector base URL, for example `http://localhost:4318`. It
+  must be an absolute `http://` or `https://` URL without credentials, query,
+  fragment, backslashes, spaces, or controls; anything else fails acquisition with
+  `Endpoint.InvalidExporterEndpoint` on path `baseUrl`.
+- `serviceName`, `serviceVersion`: the `service.name` and `service.version`
+  resource attributes. Default to `defaultServiceName` and
+  `defaultServiceVersion`.
+- `attributes`: additional resource attributes attached to every exported
+  signal, decoded by `Resource.Attributes`.
+- `headers`: sent with every export request, which is where vendor
+  authentication goes. A header whose name names a credential
+  (`authorization`, `x-api-key`, `x-honeycomb-team`, any name
+  `Redaction.isSensitiveKey` recognizes) requires an `https://` `baseUrl` unless the host is `localhost`,
+  `127.0.0.0/8`, or `[::1]`; otherwise acquisition fails with
+  `Endpoint.InvalidExporterEndpoint` on path `baseUrl`. The check reads
+  header names only: a credential under any other name is sent as given, so
+  use `https://` for every remote collector.
+- `exportInterval`: the export cadence applied to all three signals. Omitted,
+  each signal keeps Effect's own default.
+- `shutdownTimeout`: upper bound on the flush performed when the layer's scope
+  closes.
+
+### Otlp.layer
+
+```ts
+const layer: (options: Options) => Layer.Layer<
+  never,
+  Resource.InvalidResourceConfiguration | Endpoint.InvalidExporterEndpoint,
+  HttpClient.HttpClient
+>
+```
+
+Installs the OTLP logs, metrics, and traces exporters with the flows resource
+defaults filled in. It requires an Effect `HttpClient`, which is how it stays
+platform-neutral: a Node host may provide Undici, a browser or a test provides
+something else. Both configuration inputs are decoded during acquisition, so
+the returned layer either exports or refuses. Ambient `OTEL_RESOURCE_ATTRIBUTES`
+cannot add unvalidated metadata to these explicit resources.
+
+Requests over `maxRequestBytes` (1 MiB), stalled for ten seconds, or exceeding
+four in-flight requests are discarded locally. Each discard increments
+`flows_observability_otlp_dropped`. A `Warn` diagnostic with code
+`otlp_export_discarded` reports `reason` (`oversized`, `stalled`, or `saturated`),
+`bytes`, `limit`, and cumulative `dropped` at most once per minute per transport.
+It uses the logger set captured before this exporter is installed, so it cannot
+re-enter this exporter. Request bodies, headers, URLs, and ambient log
+annotations are omitted. Keep an ambient sink outside OTLP at level `Warn` or
+lower to observe loss independently; empty or filtered loggers cannot report it.
+
+### Otlp transport constants
+
+```ts
+const maxRequestBytes: number // 1048576 (1 MiB)
+const maximumEnvelopeBytes: number // 8192 (8 KiB)
+const reservedBatchBytes: number // 909312 (888 KiB)
+```
+
+The resource ceiling is 128 KiB. Another 8 KiB covers JSON wrappers and the
+instrumentation scope, which repeats the service name (at most 6 KiB after
+escaping). The remaining 888 KiB gives each record in the upstream 1,000-record
+log or span batch about 909 bytes, several times a bare record. This guarantees
+room for ordinary signal batches, not arbitrary record sizes or metric registry
+cardinality.
+
+### Otlp.layerFetch
+
+```ts
+const layerFetch: (options: Options) => Layer.Layer<
+  never,
+  Resource.InvalidResourceConfiguration | Endpoint.InvalidExporterEndpoint
+>
+```
+
+`layer` with `FetchHttpClient.layer` already provided, which binds the host's
+global `fetch`. This is the default wiring on Node 26 and the only one that is
+browser-safe by construction.
+
+```ts
+const Telemetry = Otlp.layerFetch({ baseUrl: "http://localhost:4318" })
+```
+
+### Otlp.layerEnvironment
+
+```ts
+const layerEnvironment: (
+  environment: Readonly<Record<string, string | undefined>>,
+  options?: Omit<Options, "baseUrl" | "headers">
+) => Layer.Layer<never, Otlp.LayerError>
+```
+
+`layerFetch` against `OTEL_EXPORTER_OTLP_ENDPOINT` with the headers
+`Otlp.parseHeaders` reads from `OTEL_EXPORTER_OTLP_HEADERS`. An unset or blank
+endpoint returns `layerNoop`, so no exporter is installed. `LayerError` is
+`Resource.InvalidResourceConfiguration | Endpoint.InvalidExporterEndpoint`.
+
+### Otlp.parseHeaders
+
+```ts
+const parseHeaders: (value: string | undefined) => Record<string, string>
+```
+
+Reads the OpenTelemetry `key=value,key=value` header list and percent-decodes
+each value. Pairs without `=` or with an empty key are skipped; a malformed
+escape is kept verbatim.
+
+### Otlp.layerNoop
+
+```ts
+const layerNoop: Layer.Layer<never>
+```
+
+Provides nothing and exports nothing. The explicit stand-in for a host with no
+collector, so wiring code switches layers rather than branching.
+
+### Otlp.defaultServiceName
+
+```ts
+const defaultServiceName: string // "flows"
+```
+
+The `service.name` attribute installed when the caller supplies none.
+
+### Otlp.defaultServiceVersion
+
+```ts
+const defaultServiceVersion: string // "1.0.0-rc.0"
+```
+
+The `service.version` attribute installed when the caller supplies none. It
+mirrors this package's release version, held as a literal because a published
+package cannot read its own manifest on every runtime it supports.
+
+### Delivery behavior
+
+Effect's exporter retries a transient failure three times, honoring a
+`retry-after` response header when one is present, then disables that exporter
+for 60 seconds and logs a `Debug` record. Export failure never fails the
+application effect and never surfaces as an unhandled rejection. Closing the
+layer's scope performs the final flush, bounded by `shutdownTimeout`.
+
+## Endpoint
+
+Validated collector endpoints, shared by every OTLP builder. The endpoint is
+the field an operator most often gets wrong, and a wrong one is invisible after
+acquisition, so it is decoded before any exporter exists.
+
+### Endpoint.Endpoint
+
+```ts
+const Endpoint: Schema.String.check(...)
+```
+
+Runtime schema for an absolute `http:` or `https:` collector endpoint of at
+most `maximumEndpointLength` characters that carries no credentials, query,
+fragment, backslashes, spaces, or controls. A base path is allowed;
+authentication belongs in exporter headers. Query and fragment suffixes are
+rejected because appending `/v1/traces` to them does not change the request
+path. A value the WHATWG URL parser would repair rather
+than parse as written is refused, because the repaired URL is not the one the
+exporter would post to.
+
+### Endpoint.maximumEndpointLength
+
+```ts
+const maximumEndpointLength: number // 2048
+```
+
+Largest collector endpoint accepted by a builder.
+
+### Endpoint.decode
+
+```ts
+const decode: (endpoint: unknown, path: string) => Effect.Effect<string, InvalidExporterEndpoint>
+```
+
+Decodes one endpoint into its normalized form. `path` names the option the
+endpoint arrived on, so the refusal points at the caller's own field rather
+than at a shared internal name. The rejected value is not retained in the
+error.
+
+### Endpoint.InvalidExporterEndpoint
+
+```ts
+class InvalidExporterEndpoint {
+  readonly code: "invalid_exporter_endpoint"
+  readonly path: string
+  readonly message: string
+}
+```
+
+The stable exporter-endpoint refusal shared by `Otlp.layer`,
+`Otlp.layerFetch` (`path` is `baseUrl`), and `NodeOtel.layerOtel` (`path` is
+`endpoint`).
+
+### Endpoint.normalize
+
+```ts
+const normalize: (endpoint: string) => string
+```
+
+Removes repeated trailing separators, so `http://host//` and `http://host` both
+produce one signal URL.
+
+### Endpoint.signalUrl
+
+```ts
+const signalUrl: (endpoint: string, signal: "traces" | "metrics" | "logs") => string
+```
+
+Builds the OTLP/HTTP URL one signal is posted to below a decoded endpoint:
+`signalUrl("http://host", "traces")` is `http://host/v1/traces`.
+
+## Resource
+
+Explicit, validated OpenTelemetry resource metadata. Every public OTEL builder
+in this package decodes the same `Configuration`. Resource metadata comes from
+the caller and the SDK's fixed telemetry fields. Neither the default exporter
+nor the Node SDK layer merges ambient resource configuration after validation.
+
+### Resource.Configuration
+
+```ts
+const Configuration: Schema.Struct<{
+  serviceName: Schema.String
+  serviceVersion: Schema.optional<Schema.String>
+  attributes: Schema.optional<typeof Attributes>
+}>
+type Configuration = typeof Configuration.Type
+```
+
+The service identity attached to exported telemetry. `serviceName` and
+`serviceVersion` are non-empty, well formed, and at most
+`maximumIdentityLength` UTF-16 code units.
+
+### Resource.Attributes and Resource.AttributeValue
+
+```ts
+const AttributeValue: Schema.Union<[...]>
+const Attributes: Schema.Record<Schema.String, typeof AttributeValue>
+```
+
+`AttributeValue` accepts a string of at most `maximumAttributeStringLength`
+code units, a finite number, a boolean, or a homogeneous array of one of those
+scalar types, with at most `maximumAttributeArrayLength` elements. `Attributes` bounds the record at `maximumAttributes` entries
+with non-empty, well formed keys of at most `maximumAttributeKeyLength` code
+units. NUL and unpaired UTF-16 surrogates are refused in keys and in values;
+valid astral Unicode is preserved.
+
+### Resource constants
+
+```ts
+const maximumIdentityLength: number // 1024
+const maximumAttributeKeyLength: number // 1024
+const maximumAttributeStringLength: number // 65536
+const maximumAttributes: number // 256
+const maximumAttributeArrayLength: number // 256
+const maximumResourceBytes: number // 131072 (128 KiB)
+```
+
+The resource byte limit counts the complete OTLP JSON resource, including
+identity, SDK-added `telemetry.sdk.name` and `telemetry.sdk.language`, attribute
+keys, scalar and array wrappers, escaping, and UTF-8. SDK fields are reserved
+even for the default Effect exporter, and caller attributes that the SDK
+overwrites are conservatively counted too.
+Counting stops at the first fragment over budget to bound intermediate
+allocations; the error reports the measured lower bound and byte limit at path
+`attributes`. Array-length errors report the measured element count and limit
+at the attribute path. No rejected attribute values are retained.
+
+All resource-accepting layers and `decode`, `decodeSync`, and
+`configToAttributes` enforce these bounds before exporter acquisition.
+Explicit `serviceName` and `serviceVersion` take precedence over attributes
+with those keys. Admission conservatively counts those redundant attributes.
+
+### Resource.decode
+
+```ts
+const decode: (configuration: unknown) => Effect.Effect<Configuration, InvalidResourceConfiguration>
+```
+
+Decodes one resource configuration without retaining rejected values.
+
+### Resource.decodeSync
+
+```ts
+const decodeSync: (configuration: unknown) => Configuration
+```
+
+The same decoding for the package's pure projection API. Throws
+`InvalidResourceConfiguration` rather than failing an effect.
+
+### Resource.InvalidResourceConfiguration
+
+```ts
+class InvalidResourceConfiguration {
+  readonly code: "invalid_resource_configuration"
+  readonly path: string
+  readonly message: string
+}
+```
+
+The stable resource refusal shared by every layer here. `path` is a dotted
+route into the offending field, such as `serviceName` or `attributes.region`,
+and is the bare `resource` when the whole configuration was malformed.
+
+### Resource.toOpenTelemetryConfiguration
+
+```ts
+const toOpenTelemetryConfiguration: (configuration: Configuration) => {
+  readonly serviceName: string
+  readonly serviceVersion?: string
+  readonly attributes?: Attributes
+}
+```
+
+Projects a decoded resource into the exact optional-property shape the
+OpenTelemetry SDK expects, omitting absent optional fields rather than setting
+them to `undefined`.
+
+### Resource.configToAttributes
+
+```ts
+const configToAttributes: (configuration: Configuration) => Attributes
+```
+
+Converts explicit service metadata into OpenTelemetry resource attributes.
+Invalid metadata throws the same typed `InvalidResourceConfiguration` a layer
+returns during acquisition.
+
+### Resource.layer
+
+```ts
+const layer: (configuration: Configuration) => Layer.Layer<Resource, InvalidResourceConfiguration>
+```
+
+Provides an explicitly validated OpenTelemetry resource, for a composition that
+assembles the rest of the SDK itself.
+
+### Resource.Resource
+
+The OpenTelemetry resource service tag, re-exported from
+`@effect/opentelemetry/Resource`.
+
+## Logger
+
+Effect logger layers. All four follow two rules: `mergeWithExisting` defaults
+to `false`, so installing one replaces the ambient logger set, and
+`minimumLogLevel` is applied only when the caller names it.
+
+### Logger.Options
+
+```ts
+interface Options {
+  readonly minimumLogLevel?: LogLevel.LogLevel | undefined
+  readonly mergeWithExisting?: boolean | undefined
+}
+```
+
+- `minimumLogLevel`: pins `References.MinimumLogLevel` for the whole
+  application. Omitted, the layer leaves that reference alone and Effect's own
+  `Info` default applies.
+- `mergeWithExisting`: keeps the ambient loggers alongside this one. Defaults
+  to `false`.
+
+### Logger.layerPrettyDev
+
+```ts
+const layerPrettyDev: (options?: Options) => Layer.Layer<never>
+```
+
+A human-readable development logger, with colors and mode chosen from the
+output it finds.
+
+### Logger.layerStructuredJson
+
+```ts
+const layerStructuredJson: (options?: Options) => Layer.Layer<never>
+```
+
+One structured JSON object per log line.
+
+### Logger.layerNoop
+
+```ts
+const layerNoop: (options?: Pick<Options, "minimumLogLevel">) => Layer.Layer<never>
+```
+
+Removes the active logger set. This is the one exception to the second rule:
+silencing is its purpose, so it pins `None` unless the caller names another
+level.
+
+### Logger.layer
+
+```ts
+const layer: (logger: Logger.Logger<unknown, unknown>, options?: Options) => Layer.Layer<never>
+```
+
+Installs a caller-supplied logger under the same two rules.
+
+## JournalLogger
+
+Non-blocking forwarding of bounded operational logs to the durable journal. The
+callback reads the queue's remaining room, snapshots and redacts a bounded
+record synchronously only when a slot is free, then performs only queue
+admission; a forked worker drains the queue into the journal. A record a full
+queue cannot take is counted and discarded without being snapshotted.
+
+### JournalLogger.Options
+
+```ts
+interface Options {
+  readonly runId: JournalEvent.RunId
+  readonly capacity?: number | undefined
+  readonly minimumLogLevel?: LogLevel.LogLevel | undefined
+  readonly mergeWithExisting?: boolean | undefined
+}
+```
+
+- `runId`: the run every forwarded record is attributed to.
+- `capacity`: queue depth, 1 through `maximumCapacity`. Defaults to 256.
+- `minimumLogLevel` and `mergeWithExisting`: as on `Logger.Options`.
+
+### JournalLogger.layerJournalForwarding
+
+```ts
+const layerJournalForwarding: (
+  options: Options
+) => Layer.Layer<never, InvalidJournalLoggerOptions, Journal.Journal>
+```
+
+Installs a bounded, drop-on-overflow forwarder for one explicit run.
+Configuration is decoded before a worker starts, so an invalid run id or
+capacity fails acquisition rather than being routed through the lossy worker.
+
+Each record becomes one journal entry on the lossy channel, with `eventType`
+`telemetry.log`, source `flows/observability/logger`, and a `TelemetryLog`
+payload. The durable journal allocates the per-source sequence, so a rebuilt or
+concurrently running layer for one run cannot reuse an identity.
+
+Overflow, journal delivery failures, and journal defects are telemetry losses
+rather than application failures. Each advances `Metric.droppedLogRecords`; the
+two failure paths also log a warning annotated with the run id, and the worker
+keeps draining. Interruption stays fatal, and closing the scope may drop
+records queued behind an in-flight write.
+
+### JournalLogger.TelemetryLog
+
+```ts
+const TelemetryLog: Schema.Struct<{
+  version: Schema.Literal<1>
+  level: Schema.Literals<["All", "Fatal", "Error", "Warn", "Info", "Debug", "Trace", "None"]>
+  message: Schema.Unknown
+  annotations: Schema.Record<Schema.String, Schema.Unknown>
+  cause: typeof TelemetryCause
+  fiberId: Schema.Int
+  traceId: Schema.optionalKey<Schema.String>
+  spanId: Schema.optionalKey<Schema.String>
+  timestamp: Schema.String
+}>
+type TelemetryLog = typeof TelemetryLog.Type
+```
+
+The durable wire shape of one forwarded log record. `traceId` and `spanId` are
+present only when a span was active. `timestamp` is ISO-8601. Every persisted
+`telemetry.log` payload decodes with this schema: a projection that would not
+degrades to a total record with an empty cause rather than to a payload
+consumers throw on.
+
+### JournalLogger.TelemetryCause
+
+```ts
+const TelemetryCause: Schema.Struct<{
+  version: Schema.Literal<1>
+  reasons: Schema.Array<typeof TelemetryCauseReason>
+}>
+type TelemetryCause = typeof TelemetryCause.Type
+```
+
+A versioned structural Effect cause. Effect stores composed failures as an
+ordered reason list, and the projection preserves that order and each
+discriminator.
+
+### JournalLogger.TelemetryCauseReason
+
+```ts
+const TelemetryCauseReason: Schema.Union<[
+  typeof TelemetryFail,
+  typeof TelemetryDie,
+  typeof TelemetryInterrupt
+]>
+type TelemetryCauseReason = typeof TelemetryCauseReason.Type
+```
+
+One reason in a persisted cause. `TelemetryFail` carries `error`,
+`TelemetryDie` carries `defect`, and `TelemetryInterrupt` carries a
+non-negative `fiberId` or `null`. All three are exported individually.
+
+### JournalLogger.InvalidJournalLoggerOptions
+
+```ts
+class InvalidJournalLoggerOptions {
+  readonly code: "invalid_journal_logger_options"
+  readonly path: string
+  readonly message: string
+}
+```
+
+The stable logger-configuration refusal, raised during layer acquisition.
+
+### JournalLogger constants
+
+```ts
+const maximumCapacity: number // 65536
+const maximumSnapshotBytes: number // 1048576
+const maximumSnapshotMembers: number // 4096
+const maximumSnapshotDepth: number // 64
+const unrenderableMarker: string // "[Unrenderable]"
+const truncatedMarker: string // "[Truncated]"
+```
+
+A snapshot admits at most `maximumSnapshotBytes` of encoded data,
+`maximumSnapshotMembers` container members, and `maximumSnapshotDepth`
+container edges. Unreadable values become `unrenderableMarker`, values past a
+ceiling become `truncatedMarker`, and deeper values become the journal's
+`[Deep]` marker. Container-shaped fields keep their shape, so annotations that
+spent the whole budget arrive as `{ "[Truncated]": "[Truncated]" }` rather than
+as a scalar. Text is bounded in one pass that never cuts a surrogate pair, and
+the journal's own redaction rules run before queue admission.
+
+## Metric
+
+The runtime signals that cross package boundaries. Producers live in the
+packages that know when to advance them; this module owns only the identifiers
+and the handles.
+
+### Metric handles
+
+```ts
+const runThroughput: Metric.Counter // "flows_run_throughput"
+const activeSeats: Metric.Gauge // "flows_seat_active"
+const quotaParks: Metric.Counter // "flows_quota_park"
+const structuredOutputRejections: Metric.Counter // "flows_agent_structured_output_rejections"
+const structuredOutputExhausted: Metric.Counter // "flows_agent_structured_output_exhausted"
+const droppedLogRecords: Metric.Counter // "flows_observability_log_dropped"
+```
+
+- `runThroughput` advances after a terminal run transition commits in
+  [`@smthrs/run-store`](/api/run-store).
+- `activeSeats` is held for the lifetime of a production `Agent.run` stream in
+  [`@smthrs/agent`](/api/agent) and released on success, failure, or
+  interruption.
+- `quotaParks` advances when a sealed quota decision is first executed, not
+  when it is replayed after a wake or a process restart.
+- `structuredOutputRejections` advances once per agent answer its declared
+  output schema refuses, in the same session or a fresh one.
+- `structuredOutputExhausted` advances once per agent step that fails after
+  spending every output correction and its repair.
+- `droppedLogRecords` advances once per record lost by `JournalLogger`.
+
+Step-cache lookup and write counters remain owned by
+[`@smthrs/step-cache`](/api/step-cache); this package does not duplicate those
+handles.
+
+### Metric.registry
+
+```ts
+const registry: {
+  readonly runThroughput: typeof runThroughput
+  readonly activeSeats: typeof activeSeats
+  readonly quotaParks: typeof quotaParks
+  readonly structuredOutputRejections: typeof structuredOutputRejections
+  readonly structuredOutputExhausted: typeof structuredOutputExhausted
+  readonly droppedLogRecords: typeof droppedLogRecords
+}
+```
+
+All six handles as one object, for a host that enumerates them. The six
+series names are the dashboard contract; treat them as public API.
+
+## Otel
+
+Provider-neutral composition for OpenTelemetry providers the application
+already built. This module allocates no exporter.
+
+### Otel.Options
+
+```ts
+interface Options {
+  readonly resource: Resource.Configuration
+  readonly tracerProvider?:
+    | Api.TracerProvider
+    | ((resource: Resource) => Api.TracerProvider)
+    | undefined
+  readonly loggerProvider?:
+    | LoggerProvider
+    | ((resource: Resource) => LoggerProvider)
+    | undefined
+  readonly metricReader?: (() => MetricReader | ReadonlyArray<MetricReader>) | undefined
+  readonly loggerMergeWithExisting?: boolean | undefined
+  readonly metricTemporality?: OtelMetrics.TemporalityPreference | undefined
+}
+```
+
+`metricTemporality` is `"cumulative"` or `"delta"`.
+
+Ownership differs by field. `tracerProvider` and `loggerProvider` are borrowed:
+the layer bridges onto them and never flushes or shuts one down, including a
+provider a factory returned. `metricReader` is owned: the factory runs once
+during layer acquisition, after resource validation, and closing the layer's
+scope shuts down every reader it returned. Build the readers inside the
+factory. Returning a reader that a longer-lived composition still exports
+through disables that reader when this scope closes.
+
+### Otel.layerOtel
+
+```ts
+const layerOtel: (options: Options) => Layer.Layer<never, Resource.InvalidResourceConfiguration>
+```
+
+Bridges Effect's tracer, logger, and metrics onto the supplied providers and
+the readers the `metricReader` factory returns, over the validated resource.
+Each bridge is installed only when its provider or factory is supplied, and a
+factory that returns an empty array registers no reader at all.
+
+### Otel.layerNoop
+
+```ts
+const layerNoop: Layer.Layer<never>
+```
+
+A no-op OTEL layer, for callers that want an explicit optional slot.
+
+## NodeOtel
+
+Node-only OTLP/HTTP OpenTelemetry SDK setup. Import it from
+`@smthrs/observability/NodeOtel`; it is not re-exported from the root, because
+it resolves Node-only host modules and would break the root's browser bundle.
+
+### NodeOtel.Options
+
+```ts
+interface Options {
+  readonly endpoint: string
+  readonly resource: Resource.Configuration
+  readonly shutdownTimeout?: Duration.Input | undefined
+  readonly exportIntervalMillis?: number | undefined
+}
+```
+
+`endpoint` is decoded exactly as `Otlp.Options.baseUrl` is, and a refusal names
+the path `endpoint`.
+
+### NodeOtel.layerOtel
+
+```ts
+const layerOtel: (options: Options) => Layer.Layer<
+  never,
+  Resource.InvalidResourceConfiguration | Endpoint.InvalidExporterEndpoint
+>
+```
+
+Builds a scoped Node OTLP/HTTP layer for all three signals: a
+`BatchSpanProcessor`, a `BatchLogRecordProcessor`, and a
+`PeriodicExportingMetricReader`, each behind its own OTLP exporter. Exporter
+objects are created only when the layer is built. `OTEL_SERVICE_NAME` and
+`OTEL_RESOURCE_ATTRIBUTES` cannot add resource metadata after validation,
+whether supplied by the process environment or an Effect `ConfigProvider`.
+The OpenTelemetry exporters still read the standard transport variables
+(`OTEL_EXPORTER_OTLP_HEADERS`, `_TIMEOUT`, `_COMPRESSION`, `_CERTIFICATE`,
+`_CLIENT_CERTIFICATE`, `_CLIENT_KEY`, and their per-signal forms) from the
+process environment; the explicit `endpoint` always wins over
+`OTEL_EXPORTER_OTLP_ENDPOINT`. Headers set there reach this `endpoint`, so do
+not set them for a different collector. `Otlp.layer` reads none of these.
+Closing the scope
+force-flushes both batch processors and collects the metric reader once, so
+release rather than the interval is the deterministic flush.
+
+## BrowserOtel
+
+Browser OpenTelemetry SDK setup with explicitly injected processors. Import it
+from `@smthrs/observability/BrowserOtel`.
+
+### BrowserOtel.Options
+
+```ts
+interface Options {
+  readonly resource: Resource.Configuration
+  readonly spanProcessor?: (() => SpanProcessor | ReadonlyArray<SpanProcessor>) | undefined
+  readonly logRecordProcessor?: (() => LogRecordProcessor | ReadonlyArray<LogRecordProcessor>) | undefined
+  readonly metricReader?: (() => MetricReader | ReadonlyArray<MetricReader>) | undefined
+  readonly loggerMergeWithExisting?: boolean | undefined
+}
+```
+
+Processors and readers are created by the caller's factories, which keeps this
+module free of Node imports and free of browser exporter policy. Every factory
+is owned: it runs once during layer acquisition, after resource validation, and
+the web SDK shuts down everything it returned when the scope closes. A factory
+that returns an empty array installs nothing for that signal.
+
+### BrowserOtel.layerOtel
+
+```ts
+const layerOtel: (options: Options) => Layer.Layer<never, Resource.InvalidResourceConfiguration>
+```
+
+Builds a scoped browser OpenTelemetry layer over the validated resource. A
+layer with no processor factories at all still builds; it provides the resource
+and bridges nothing.