@smthrs/observability 0.35.0 → 1.0.0-rc.12

package/docs/guides/wire-an-opentelemetry-sdk.md

@@ -0,0 +1,226 @@
+---
+title: "Wire an OpenTelemetry SDK"
+description: "Use NodeOtel, BrowserOtel, or Otel when a collector endpoint is not enough: the Node OTLP/HTTP layer, browser processors you construct, and bridging providers an application already built."
+sidebar:
+  order: 2
+---
+
+[`Otlp`](./export-to-a-collector.md) covers a collector endpoint and nothing
+else. Three builders exist for the cases it does not cover: existing
+OpenTelemetry instrumentation you must feed, a vendor exporter that is not
+OTLP/HTTP JSON, and a provider a framework hands you already constructed.
+
+All three validate `Resource.Configuration`. `NodeOtel` and `BrowserOtel`
+construct providers with that resource. `Otel` supplies it to provider factories
+and metrics; already-created providers retain their own resource.
+
+## Node: build the SDK for me
+
+`NodeOtel.layerOtel` allocates the whole Node OpenTelemetry SDK: a
+`BatchSpanProcessor`, a `BatchLogRecordProcessor`, and a
+`PeriodicExportingMetricReader`, each behind its own OTLP/HTTP exporter.
+
+```ts
+import * as NodeOtel from "@smthrs/observability/NodeOtel"
+import * as Effect from "effect/Effect"
+
+const telemetry = NodeOtel.layerOtel({
+  endpoint: "http://localhost:4318",
+  resource: { serviceName: "deploy-status", serviceVersion: "2.4.1" },
+  exportIntervalMillis: 60_000,
+  shutdownTimeout: "10 seconds"
+})
+
+const outcome = program.pipe(Effect.provide(telemetry), Effect.scoped)
+```
+
+The exporters are created when the scoped layer is built, not when the module
+is imported, so holding the builder costs nothing. Closing the scope
+force-flushes both batch processors and collects the metric reader once, which
+makes release, rather than the interval, the deterministic flush.
+
+The endpoint option is named `endpoint` here and `baseUrl` on `Otlp`; each
+refusal names the option it arrived on, so the message points at your own
+field.
+
+`NodeOtel` takes no `headers` option. The OpenTelemetry exporters read the
+standard `OTEL_EXPORTER_OTLP_HEADERS`, `_TIMEOUT`, `_COMPRESSION`, and TLS
+certificate variables from the process environment and send them to your
+explicit `endpoint`, which always wins over `OTEL_EXPORTER_OTLP_ENDPOINT`.
+Set those variables only for this collector. `Otlp` reads none of them.
+
+Import `NodeOtel` only from code that runs on Node. See
+[the layer map](../concepts/layer-map.md) for why it is absent from the root
+entry point.
+
+## Browser: bring your own processors
+
+`BrowserOtel.layerOtel` builds the web SDK around processors and readers the
+application constructs. That keeps browser exporter policy, and every exporter
+package a bundle would have to carry, in the application rather than in this
+one.
+
+```ts
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http"
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base"
+import * as BrowserOtel from "@smthrs/observability/BrowserOtel"
+
+const telemetry = BrowserOtel.layerOtel({
+  resource: { serviceName: "console-ui" },
+  spanProcessor: () =>
+    new BatchSpanProcessor(
+      new OTLPTraceExporter({ url: "https://otlp.example.com/v1/traces" })
+    )
+})
+```
+
+Every processor field is optional, and a layer with none still builds: it
+provides the resource and bridges nothing. Return an array to install several
+processors for one signal. Each field is a factory because the layer owns what
+it returns: the factory runs once at acquisition, and the web SDK shuts down
+every processor and reader when the scope closes.
+
+If all you need in a browser is OTLP delivery, use `Otlp.layerFetch` instead.
+It is smaller, needs no SDK, and is browser-safe by construction.
+
+## Bridge providers you control
+
+`Otel.layerOtel` allocates no exporter at all. It takes an OpenTelemetry
+`TracerProvider` and `LoggerProvider`, plus a factory that builds the metric
+readers, and bridges Effect's tracer, logger, and metrics onto them. Provider
+fields also accept synchronous factories. Every factory runs during layer
+acquisition, after resource validation, and the provider factories receive the
+same resource as the metric producer. Pass it to the SDK constructor to export
+all signals with the configured service identity:
+
+```ts
+import { LoggerProvider } from "@opentelemetry/sdk-logs"
+import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics"
+import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base"
+import * as Otel from "@smthrs/observability/Otel"
+import * as Effect from "effect/Effect"
+
+let tracerProvider: BasicTracerProvider | undefined
+let loggerProvider: LoggerProvider | undefined
+const telemetry = Otel.layerOtel({
+  resource: {
+    serviceName: "deploy-status",
+    serviceVersion: "2.4.1",
+    attributes: { region: "us-west" }
+  },
+  tracerProvider: (resource) =>
+    tracerProvider = new BasicTracerProvider({
+      resource,
+      spanProcessors: [spanProcessor]
+    }),
+  loggerProvider: (resource) =>
+    loggerProvider = new LoggerProvider({
+      resource,
+      processors: [logRecordProcessor]
+    }),
+  metricReader: () => new PeriodicExportingMetricReader({ exporter: metricExporter }),
+  metricTemporality: "cumulative"
+})
+
+try {
+  await Effect.runPromise(program.pipe(Effect.provide(telemetry), Effect.scoped))
+} finally {
+  await Promise.all([tracerProvider?.shutdown(), loggerProvider?.shutdown()])
+}
+```
+
+Ownership splits between the two kinds of field. Providers are borrowed: the
+application owns their flushing and shutdown, including providers returned by
+factories, and this layer never shuts one down. Readers are owned: the
+`metricReader` factory runs once during acquisition, and closing the scope shuts
+down every reader it returned. Build the readers inside the factory rather than
+handing over one a longer-lived composition still exports through, which that
+shutdown would disable. Construct `spanProcessor` and `logRecordProcessor` with
+your exporters and give them to the provider you build.
+
+You can still pass existing providers directly. The layer cannot change the
+resource they captured at construction. In that form, the resource option
+controls only the metric resource, not log or span resource attributes.
+Whichever form you use, spans and log records carry the instrumentation scope
+`effect` with the Effect version, and the span status and log attributes
+described in
+[What the collector receives](./export-to-a-collector.md#what-the-collector-receives). Construct both providers with the intended resource before injection,
+or use the factories above to receive the validated resource.
+
+Each of the three is optional and each is bridged only when supplied, so a
+composition with a tracer and no meter installs only the tracer bridge. A
+`metricReader` factory that returns an empty array registers no reader at all
+rather than a misconfigured one.
+
+Two options control merge behavior: `loggerMergeWithExisting` keeps the ambient
+Effect loggers alongside the OpenTelemetry logger, and `metricTemporality`
+selects the temporality preference the metric bridge reports.
+
+`Otel.layerNoop` is the explicit empty slot for a composition that wants the
+option without the wiring.
+
+## Provide only the resource
+
+`Resource.layer` provides the validated OpenTelemetry resource by itself, for a
+composition that assembles the rest of the SDK on its own:
+
+```ts
+import * as Resource from "@smthrs/observability/Resource"
+
+const resource = Resource.layer({
+  serviceName: "deploy-status",
+  attributes: { "deployment.environment.name": "production" }
+})
+```
+
+`Resource.configToAttributes` is the pure projection of the same configuration
+into OpenTelemetry attributes, for code that needs the attribute record rather
+than a layer. It reads no environment variables: attributes come from your
+configuration and the SDK's `telemetry.sdk.name`, `telemetry.sdk.language` and
+`telemetry.sdk.version` fields, which are included in the admission budget. An
+attribute of yours with one of those three names replaces the SDK's value.
+
+## Default OTLP export limits
+
+`Otlp.layer` and `Otlp.layerFetch` share a limit of four active HTTP requests
+across logs, traces, and metrics within each layer acquisition. Each request has
+a ten-second timeout that interrupts the transport and aborts a stalled fetch.
+A request ends when the collector's status arrives: the response body is not
+read, so a collector that never finishes its answer holds no slot.
+`shutdownTimeout` separately bounds the final scope flush.
+
+Logs and traces flush at 1,000 records or the export interval. The transport has
+no waiting queue: a batch arriving while all four slots are occupied is dropped.
+Serialized JSON payloads larger than 1 MiB are also dropped, limiting active
+request payloads to 4 MiB. This limit applies after serialization; it does not
+bound individual application records, temporary serialization allocations, or
+the application's metric registry.
+
+Resource admission caps cumulative encoded metadata at 128 KiB and bounds
+arrays at 256 elements. The byte budget includes SDK-added telemetry fields,
+reserved even for the default Effect exporter. Both the default exporter and
+the Node SDK layer isolate ambient resource configuration after validation.
+The default exporter also budgets the request envelope
+at 8 KiB and reserves `Otlp.reservedBatchBytes` (888 KiB) for signals: roughly
+900 bytes per record
+in a 1,000-record log or span batch. Every layer validates these resource limits
+before allocating exporters, including injected SDK layers.
+
+The Effect counter `flows_observability_otlp_dropped` increments once per batch
+discarded for saturation, payload size, or timeout. Discards are terminal and
+are not retried. Read the counter locally
+with `Metric.value(Metric.counter("flows_observability_otlp_dropped"))` during an
+outage. Its exported value becomes available when the collector recovers.
+
+Because that counter shares the export path, each acquisition also emits at
+most one warning every 60 seconds through the ambient loggers captured before
+installing the OTLP logger. The warning has code `otlp_export_discarded`, reason
+`oversized`, `saturated`, or `stalled`, encoded bytes, request limit, and total
+discarded batches. It includes no payload, URL, or inherited annotations and
+cannot re-enter this exporter even during an application-triggered flush. Keep
+an ambient logger installed if loss diagnostics should remain visible during
+an export outage.
+
+Ordinary HTTP and network failures retain Effect's retry policy. These limits
+apply to the default `Otlp` layers; SDK processors supplied to the other builders
+retain their own export policies.

package/docs/installation.md

@@ -0,0 +1,102 @@
+---
+title: "Installation"
+description: "Install @smthrs/observability, its runtime requirements and Effect version, its import forms, and the rule that keeps the root entry point bundling for a browser."
+sidebar:
+  order: 1
+---
+
+## Install the package
+
+```bash
+npm install @smthrs/observability@next effect
+```
+
+The `next` tag carries the 1.0 release candidates.
+
+The package requires Node.js 26.4.0 or later and ships as both ESM and
+CommonJS with TypeScript declarations.
+
+## Install one Effect release
+
+Effect services are identified by module identity, so a composition that
+resolves two copies of `effect` splits its context and a provided layer stops
+satisfying a requirement. Install one `effect` in the range `^4.0.4`.
+
+`Otlp` is written entirely against `effect`, including its HTTP client and its
+`effect/observability/Otlp` exporters. The `@effect/opentelemetry@4.0.4`
+dependency, the required `@opentelemetry/api@1.9.1` peer, and the logs and
+metrics dependencies support the root `Otel` and `Resource` modules. They
+install with ordinary peer-aware package managers. `@effect/opentelemetry`
+4.0.4 accepts any `effect` in `^4.0.4`. The default install includes no HTTP exporters or trace SDK.
+
+`NodeOtel` selects the optional Node trace SDK and three HTTP exporters:
+
+```bash
+pnpm add @opentelemetry/exporter-logs-otlp-http@0.222.0 @opentelemetry/exporter-metrics-otlp-http@0.222.0 @opentelemetry/exporter-trace-otlp-http@0.222.0 @opentelemetry/sdk-trace-base@2.11.0 @opentelemetry/sdk-trace-node@2.11.0
+```
+
+`BrowserOtel` selects the optional browser trace SDK instead:
+
+```bash
+pnpm add @opentelemetry/sdk-trace-base@2.11.0 @opentelemetry/sdk-trace-web@2.11.0
+```
+
+The browser adapter accepts the exporters you supply; those HTTP exporter
+packages are not prerequisites for constructing its layer.
+
+## Import forms
+
+The root entry point re-exports seven modules as namespaces:
+
+```ts
+import { Endpoint, JournalLogger, Logger, Metric, Otel, Otlp, Resource } from "@smthrs/observability"
+```
+
+Each is also importable from its own subpath, which is the form the
+[API reference](./api.md) uses:
+
+```ts
+import * as JournalLogger from "@smthrs/observability/JournalLogger"
+import * as Otlp from "@smthrs/observability/Otlp"
+```
+
+`@smthrs/observability/package.json` is exported.
+
+## The two subpath-only modules
+
+`NodeOtel` and `BrowserOtel` are not re-exported from the root, and importing
+them by subpath is the only way to reach them:
+
+```ts
+import * as BrowserOtel from "@smthrs/observability/BrowserOtel"
+import * as NodeOtel from "@smthrs/observability/NodeOtel"
+```
+
+`NodeOtel` resolves Node-only host modules: `@effect/opentelemetry/NodeSdk` and
+`@opentelemetry/sdk-trace-node`, which reaches the bare `async_hooks` specifier
+through `@opentelemetry/context-async-hooks`. Re-exporting it from the root
+would put a module a browser bundler cannot resolve in the entry point, and
+break the browser bundle the root guarantees. Nothing the root entry point
+reaches resolves a `node:` built-in, so it bundles for a browser as it is.
+
+Import `NodeOtel` only from code that runs on Node, and `BrowserOtel` only from
+code that runs in a browser. `Otlp` is safe in both, because it exports over
+Effect's `HttpClient` and never touches a `node:` built-in.
+
+## What a real composition adds
+
+The exporter alone needs nothing else. Two features have a dependency:
+
+- `Otlp.layer` requires an Effect `HttpClient` from
+  `effect/http/HttpClient`. `Otlp.layerFetch` supplies the host's
+  global `fetch` and is the usual choice; a Node host that wants Undici instead
+  provides `NodeHttpClient.layerUndici`, re-exported by
+  [`@smthrs/platform-node`](/api/platform-node) as `NodeHost.NodeHttpClient`.
+- `JournalLogger.layerJournalForwarding` requires a `Journal.Journal` service
+  from [`@smthrs/journal`](/api/journal). A durable engine composition already
+  provides one.
+
+## Next step
+
+Export your first trace, log record, and metric series in the
+[Quickstart](./quickstart.md).

package/docs/quickstart.md

@@ -0,0 +1,145 @@
+---
+title: "Quickstart"
+description: "Export a trace, a log record, and a metric series to a collector you can watch, using a thirty-line collector stand-in and one Effect layer."
+sidebar:
+  order: 2
+---
+
+This quickstart exports all three signals from one small program and shows you
+what arrived. It needs no Docker, no vendor account, and no OpenTelemetry SDK:
+a twelve-line Node server stands in for the collector so you can read the
+delivery with your own eyes, and swapping in a real collector is a one-line
+change at the end.
+
+## Prerequisites
+
+- Node.js 26.4.0 or later, which runs a `.ts` file directly by stripping its
+  types.
+- A package whose `package.json` sets `"type": "module"`, with the
+  dependencies installed: `npm install @smthrs/observability@next effect`.
+
+## Start a collector stand-in
+
+An OTLP/HTTP collector is an HTTP server that accepts JSON on three paths.
+Create `collector.mjs`:
+
+```js
+import { createServer } from "node:http"
+
+createServer((request, response) => {
+  const chunks = []
+  request.on("data", (chunk) => chunks.push(chunk))
+  request.on("end", () => {
+    const body = JSON.parse(Buffer.concat(chunks).toString("utf8"))
+    console.log(request.url, Object.keys(body).join(" "))
+    response.writeHead(200, { "content-type": "application/json" })
+    response.end("{}")
+  })
+}).listen(4318, "127.0.0.1")
+```
+
+Run it in its own terminal, and leave it running:
+
+```bash
+node collector.mjs
+```
+
+## Write the program
+
+Create `quickstart.ts`. The program opens a span, writes a log record, and
+advances a counter. None of those three lines mentions telemetry: they are
+ordinary Effect, and they are exactly what the Smithers packages already do on
+their own hot paths.
+
+```ts
+import * as Otlp from "@smthrs/observability/Otlp"
+import * as Effect from "effect/Effect"
+import * as Metric from "effect/Metric"
+
+const deployments = Metric.counter("quickstart/deployments", {
+  description: "Deployments this program recorded"
+})
+
+const deploy = Effect.gen(function*() {
+  yield* Effect.logInfo("deploying the API")
+  yield* Metric.update(deployments, 1)
+}).pipe(Effect.withSpan("deploy"))
+```
+
+Now add the exporter and run it. `layerFetch` posts over the host's global
+`fetch`, so there is nothing else to provide:
+
+```ts
+const telemetry = Otlp.layerFetch({
+  baseUrl: "http://localhost:4318",
+  serviceName: "quickstart",
+  serviceVersion: "1.0.0"
+})
+
+await Effect.runPromise(
+  deploy.pipe(Effect.provide(telemetry), Effect.orDie, Effect.scoped)
+)
+```
+
+`Effect.orDie` says that an unusable collector endpoint is a startup defect
+rather than something this program recovers from. The layer is scoped, so
+`Effect.scoped` gives it a lifetime, and closing that scope is what flushes.
+
+## Run it
+
+```bash
+node quickstart.ts
+```
+
+The collector terminal prints one line per signal. The three arrive in
+whatever order the exporters flush:
+
+```text
+/v1/traces resourceSpans
+/v1/logs resourceLogs
+/v1/metrics resourceMetrics
+```
+
+If you print a whole body instead of its top-level key, every payload carries
+the resource you named: `service.name` is `quickstart` and `service.version` is
+`1.0.0`.
+
+## What just happened
+
+One layer installed three of Effect's own OTLP exporters against your base URL.
+Each signal posts below it on its own path, so `http://localhost:4318` becomes
+`/v1/traces`, `/v1/logs`, and `/v1/metrics`. The exporters batch, so nothing
+was delivered while the program ran; closing the layer's scope force-flushed
+all three, which is why `Effect.scoped` is where the output comes from.
+
+The program never mentioned a tracer, a meter, or a logger provider. Effect's
+own tracer and metric registry were already collecting; the layer is only the
+delivery.
+
+## Point it at a real collector
+
+Change one field:
+
+```ts
+const telemetry = Otlp.layerFetch({
+  baseUrl: "https://otlp.example.com",
+  serviceName: "quickstart",
+  headers: { authorization: "Bearer YOUR_TOKEN" }
+})
+```
+
+Replace `YOUR_TOKEN` with the token your vendor issued. The endpoint must be an
+absolute `http:` or `https:` URL carrying no credentials; anything else refuses
+the layer at acquisition rather than failing silently later. See
+[Export to an OTLP collector](./guides/export-to-a-collector.md) for the rest
+of the options.
+
+## Next steps
+
+- [Export to an OTLP collector](./guides/export-to-a-collector.md): service
+  identity, authentication headers, export cadence, and what happens when a
+  collector is down.
+- [Instrumentation and export](./concepts/instrumentation-and-export.md): why
+  the exporter is one layer and what is already instrumented without it.
+- [Forward logs to the run journal](./guides/forward-logs-to-the-journal.md):
+  the second delivery path, durable and readable in process.

package/docs/troubleshooting.md

@@ -0,0 +1,168 @@
+---
+title: "Troubleshooting"
+description: "The typed refusals @smthrs/observability reports and the silent failures it cannot: nothing arriving at a collector, a bundler that cannot resolve async_hooks, logs that stopped, and a counter that reads zero."
+---
+
+Two kinds of problem show up here. A typed refusal names its own cause and
+happens while the layer is built. A silent failure is the harder one, because
+export is absorbed by design and a broken exporter looks exactly like a working
+one.
+
+## InvalidExporterEndpoint
+
+**What happened.** A builder was handed a collector endpoint it will not
+export to. The failure carries `code` `invalid_exporter_endpoint`, the `path`
+of the option it arrived on (`baseUrl` for `Otlp`, `endpoint` for `NodeOtel`),
+and a message. The rejected value is not in the error.
+
+**What to change.** Pass an absolute `http:` or `https:` URL of at most 2,048
+characters that carries no username or password and no spaces or control
+characters. The usual culprits, in order:
+
+- A trailing newline off a config file, or a leading space off a paste. Trim
+  the value. This one is refused rather than repaired precisely because the
+  URL parser would repair it into a URL nobody typed.
+- A missing scheme: `collector:4318` instead of `http://collector:4318`.
+- A signal path already appended. Pass the base URL; the builder adds
+  `/v1/traces`, `/v1/metrics`, and `/v1/logs`.
+- Credentials in the URL. Move them to the `headers` option.
+
+## InvalidResourceConfiguration
+
+**What happened.** The service identity or the resource attributes failed
+decoding. The failure carries `code` `invalid_resource_configuration` and a
+`path` naming the offending field, such as `serviceName` or an attribute key.
+
+**What to change.** Check the value against the bounds: a non-empty service
+name and version of at most 1,024 UTF-16 code units, at most 256 attributes,
+attribute values that are strings of at most 65,536 code units, finite numbers,
+booleans, or homogeneous arrays of those with at most 256 elements. The complete
+resource must fit 128 KiB of OTLP JSON, including keys, identity, the SDK-added
+`telemetry.sdk.name`, `telemetry.sdk.language` and `telemetry.sdk.version`
+fields, wrappers, escaping and UTF-8. Many individually valid values can exceed this budget;
+remove or shorten attributes. The refusal names `attributes`, the measured
+lower bound in bytes and the limit, without retaining values. NUL and unpaired surrogates are
+refused anywhere. An empty `serviceName` is the common one, usually an
+environment variable that was not set.
+
+## InvalidJournalLoggerOptions
+
+**What happened.** `JournalLogger.layerJournalForwarding` was given a run id or
+a capacity it will not start a worker for. The failure carries `code`
+`invalid_journal_logger_options` and the offending `path`.
+
+**What to change.** Decode the run id through `JournalEvent.RunId` rather than
+casting a string, and keep `capacity` between 1 and 65,536. The refusal happens
+before any record is queued, so nothing was silently dropped.
+
+## Nothing arrives at the collector
+
+**What happened.** The layer built, the program ran, and the collector holds
+nothing. Export failure is absorbed by design, so this is not reported anywhere
+by default.
+
+**What to check, in order.**
+
+1. **Did the scope close?** Exporters batch. A short program delivers on the
+   shutdown flush, so read the collector only after `Effect.scoped` completes.
+   A program killed with `SIGKILL` never flushes.
+2. **Is the base URL what you think?** Signals post below it, so
+   `http://collector:4318` posts to `http://collector:4318/v1/traces`. If your
+   collector expects a prefix, include it in `baseUrl`.
+3. **Is the collector answering?** Run at `Debug`. The exporter logs
+   `Disabling exporter for 60 seconds` when it gives up after three retries.
+4. **Is the layer actually provided?** A composition that swapped in
+   `Otlp.layerNoop` behaves exactly like a healthy one that delivers nothing.
+
+## An OTLP export batch was discarded
+
+A `Warn` record with code `otlp_export_discarded` means the transport discarded
+a batch because it exceeded 1 MiB (`oversized`), stalled for ten seconds
+(`stalled`), or found all four request slots occupied (`saturated`). The
+`flows_observability_otlp_dropped` counter records every discarded batch. The
+warning carries the request byte size, limit and running drop count, and is
+limited to one per minute per transport.
+
+Warnings go only to the loggers captured before exporter acquisition, without
+logging into this exporter. Keep an ambient sink outside OTLP at level `Warn`
+or lower: it remains useful even when the drop counter cannot reach the
+collector. An empty ambient logger set or a higher minimum level suppresses
+warnings. Reduce unusually large records or metric cardinality for oversized
+batches; check collector availability and latency for stalls and saturation.
+The resource budget reserves 888 KiB for ordinary batches, but cannot bound
+application record sizes.
+
+## Log records stopped reaching the collector
+
+**What happened.** Spans and metric series still arrive, and logs do not, after
+a `Logger` layer was added.
+
+**What to change.** `Otlp` adds its log exporter to the ambient logger set, and
+a `Logger` layer with the default `mergeWithExisting: false` replaces that set.
+Whether the exporter survives depends on which layer the composition builds
+last, which is not worth reasoning about: pass `mergeWithExisting: true` on the
+`Logger` layer whenever another sink is installed. See
+[Install a logger](./guides/install-a-logger.md).
+
+## A bundler cannot resolve `async_hooks`
+
+**What happened.** A browser or edge build failed on `async_hooks`,
+`node:async_hooks`, or a module under `@opentelemetry/context-async-hooks`.
+
+**What to change.** Something in the graph imports
+`@smthrs/observability/NodeOtel`, directly or through a module that does.
+`NodeOtel` binds the Node OpenTelemetry SDK and cannot bundle for a browser.
+Use `Otlp.layerFetch` for browser delivery, or `BrowserOtel` when you need the
+web SDK, and keep the `NodeOtel` import behind a Node-only entry point. The
+root entry point itself resolves no `node:` built-in and bundles for a browser
+as it is.
+
+## `Metric.value` reads zero
+
+**What happened.** The system is clearly doing work, and a counter reads zero.
+
+**What to check.**
+
+- **A dimensioned counter read through its bare handle.** Some packages update
+  only an attribute-tagged series, so the attribute-less parent stays at zero.
+  Read the exported view, for example `EngineStoreMetrics.dispatch.Success`
+  from [`@smthrs/engine-store`](/api/engine-store).
+- **A registry provided per test.** Providing `Metric.MetricRegistry` with a
+  fresh map isolates state; a read outside that scope sees a different
+  registry.
+- **A gauge read as a counter.** A gauge's value is `value`, a counter's is
+  `count`.
+
+## `droppedLogRecords` keeps climbing
+
+**What happened.** `flows_observability_log_dropped` advances during a run,
+which means log records are not reaching the journal.
+
+**What to change.** The counter advances for three distinct losses, and the
+last two also emit a warning annotated with the run id:
+
+- **Queue overflow**, with no warning. Raise `capacity` above the default 256,
+  up to 65,536.
+- **A journal delivery failure.** Read the warning; the journal itself is the
+  problem, not the logger.
+- **A defect from the journal implementation.** Read the warning. The worker
+  keeps draining, so the run continues with gaps.
+
+Records queued behind an in-flight write can also be dropped when the layer's
+scope closes, and the forwarder exposes no drain barrier. `journal.flush`
+settles only the entries the journal has already admitted, so it returns while
+a record is still waiting in the forwarder's queue. Poll the journal for the
+records you expect while the layer's scope is open, as
+[Forward logs to the run journal](./guides/forward-logs-to-the-journal.md#assert-on-a-short-lived-run)
+shows.
+
+## Reading a refusal's path
+
+`path` is a dotted route into the value that failed, built from the decoder's
+own issue path. `serviceName` names the identity field;
+`attributes.region` names the `region` entry inside the `attributes` record. When the decoder cannot attribute the failure to a field,
+the path is the bare `resource`, which means the whole configuration was
+malformed: `null`, or not an object at all.
+
+Neither refusal carries the rejected value, so pair the path with the value you
+passed on that field.