@smthrs/observability 0.35.0 → 1.0.0-rc.3

package/docs/guides/install-a-logger.md

@@ -0,0 +1,111 @@
+---
+title: "Install a logger"
+description: "Pick a Logger layer for a development shell, a production process, or a silent test, and understand the two rules every one of them follows: the ambient set is replaced, and the minimum level is left alone."
+sidebar:
+  order: 4
+---
+
+`Logger` ships four layers over Effect's own logger machinery. They differ in
+the sink; they agree on the two rules that decide what installing one does to
+the rest of the application.
+
+## Pick a layer
+
+```ts
+import * as Logger from "@smthrs/observability/Logger"
+
+// A development shell: colored, human-readable lines.
+const development = Logger.layerPrettyDev()
+
+// A production process: one structured JSON object per line.
+const production = Logger.layerStructuredJson()
+
+// A test that should print nothing.
+const silent = Logger.layerNoop()
+```
+
+`Logger.layerPrettyDev` chooses colors and mode from the terminal it finds, so
+it degrades to plain text when the output is not a TTY.
+`Logger.layerStructuredJson` is the one to ship: a log shipper can parse it, and
+it is what a collector's log pipeline expects.
+
+To install a logger you wrote, or one from another package, use `Logger.layer`:
+
+```ts
+import * as EffectLogger from "effect/Logger"
+
+const custom = Logger.layer(
+  EffectLogger.make((options) => {
+    /* your sink */
+  })
+)
+```
+
+## Rule one: the ambient set is replaced
+
+`mergeWithExisting` defaults to `false`, matching Effect's own `Logger.layer`,
+so installing one of these layers replaces the ambient logger set rather than
+adding to it. That is what you want for a process that has exactly one sink,
+and it is the usual explanation for logs disappearing after a layer was added.
+
+Pass `true` to keep the loggers already installed:
+
+```ts
+const both = Logger.layerStructuredJson({ mergeWithExisting: true })
+```
+
+The same option is on
+[`JournalLogger.layerJournalForwarding`](./forward-logs-to-the-journal.md), and
+merging is how a control-plane run gets console output and durable
+`telemetry.log` rows from one log call.
+
+## Rule two: the minimum level is left alone
+
+A layer that adds a sink has no business overriding the level an application
+chose elsewhere, so `References.MinimumLogLevel` is provided only when you name
+`minimumLogLevel`. Omitted, whatever the application set stands, and Effect's
+own `Info` default applies when nothing set it.
+
+```ts
+// Leaves the application's chosen level in place.
+const inherits = Logger.layerStructuredJson()
+
+// Pins Warn for the whole application.
+const pinned = Logger.layerStructuredJson({ minimumLogLevel: "Warn" })
+```
+
+`Logger.layerNoop` is the deliberate exception. Silence is its purpose, so it
+pins `None` unless you name another level. Passing one is how a test silences
+output while keeping a level assertion meaningful:
+
+```ts
+const quietButFiltered = Logger.layerNoop({ minimumLogLevel: "Debug" })
+```
+
+## Merge when you install more than one sink
+
+Installing a logger decides what is rendered locally. It exports nothing on its
+own: log records reach a collector because [`Otlp`](./export-to-a-collector.md)
+adds its own log exporter to the same ambient set, and they reach a run's
+history because
+[`JournalLogger`](./forward-logs-to-the-journal.md) adds a forwarder to it.
+
+That shared set is why rule one matters here. A `Logger` layer with the default
+`mergeWithExisting: false` discards every logger the set already held, and
+whether that includes the OTLP exporter depends on which layer the composition
+builds last. Pass `mergeWithExisting: true` on the `Logger` layer whenever
+another sink is installed, and the ordering question does not arise:
+
+```ts
+import * as Effect from "effect/Effect"
+
+const outcome = program.pipe(
+  Effect.provide(Logger.layerStructuredJson({ mergeWithExisting: true })),
+  Effect.provide(telemetry),
+  Effect.scoped
+)
+```
+
+One `Effect.logInfo` call then renders locally, posts to the collector's
+`/v1/logs` path, and, with the journal forwarder installed, lands on the run's
+durable history.

package/docs/guides/read-runtime-metrics.md

@@ -0,0 +1,83 @@
+---
+title: "Read the runtime metrics"
+description: "The four runtime metric handles this package declares, the exact series names a dashboard binds to, which package advances each one, and how to read a counter in process without an exporter."
+sidebar:
+  order: 5
+---
+
+`Metric` declares the runtime signals that cross package boundaries: the
+handles a producer updates and a dashboard reads. Every other metric in
+Smithers belongs to the package that owns the behavior it measures.
+
+## The six handles
+
+| Handle                       | Series name                                | Kind    | Advances when                                                                                                                                                      |
+| ---------------------------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `runThroughput`              | `flows_run_throughput`                     | counter | A run's terminal transition commits in [`@smthrs/run-store`](/api/run-store).                                                                                      |
+| `activeSeats`                | `flows_seat_active`                        | gauge   | Held for the lifetime of a production `Agent.run` stream in [`@smthrs/agent`](/api/agent), and released on success, failure, or interruption.                      |
+| `quotaParks`                 | `flows_quota_park`                         | counter | A sealed quota decision is first executed, and not when that decision is replayed after a wake or a process restart.                                               |
+| `structuredOutputRejections` | `flows_agent_structured_output_rejections` | counter | An agent answer is refused by its declared output schema, in the same session or a fresh one.                                                                      |
+| `structuredOutputExhausted`  | `flows_agent_structured_output_exhausted`  | counter | An agent step fails after spending every output correction and its repair.                                                                                         |
+| `droppedLogRecords`          | `flows_observability_log_dropped`          | counter | A log record is lost before durable delivery: once per queue overflow, once per journal delivery failure, and once per defect the forwarding worker recovers from. |
+
+`Metric.registry` is the same six as one object, so a host can enumerate them.
+The series names are the dashboard contract; treat them as public API.
+
+Step-cache lookup and write counters belong to
+[`@smthrs/step-cache`](/api/step-cache), and the store packages keep their own
+handles. This package does not duplicate any of them.
+
+## Read a counter in process
+
+A metric handle is readable without an exporter, which makes it a fine
+assertion target in a test and a fine health check in a host:
+
+```ts
+import * as ObservabilityMetric from "@smthrs/observability/Metric"
+import * as Effect from "effect/Effect"
+import * as Metric from "effect/Metric"
+
+const dropped = Effect.gen(function*() {
+  const value = yield* Metric.value(ObservabilityMetric.droppedLogRecords)
+  return value.count
+})
+```
+
+A counter's value carries `count`; a gauge's carries `value`.
+
+## Read a dimensioned counter through its attribute view
+
+Some packages update a counter through a tagged view rather than the bare
+handle. The dispatch counter in [`@smthrs/engine-store`](/api/engine-store) is
+the common example: it updates only the series tagged with the outcome, so
+reading the bare handle reads the attribute-less series and always sees zero.
+
+```ts
+import { EngineStoreMetrics } from "@smthrs/engine-store"
+
+const dispatches = Effect.gen(function*() {
+  const value = yield* Metric.value(EngineStoreMetrics.dispatch.Success)
+  return value.count
+})
+```
+
+Read the exported view, not the parent handle, whenever the owning package
+exports one.
+
+## Isolate the registry in a test
+
+Effect keeps metric state in a `MetricRegistry` reference with a
+process-default value, so counters accumulate across tests in one process.
+Provide a fresh map to isolate one run:
+
+```ts
+Effect.provideService(Metric.MetricRegistry, new Map())
+```
+
+## Where the series go
+
+Every registered series exports with the rest of the telemetry: with
+[`Otlp` provided](./export-to-a-collector.md), they post to the collector's
+`/v1/metrics` path under the `service.name` you configured. With no exporter
+installed, they are still collected and still readable in process, and nothing
+leaves the machine.

package/docs/guides/testing.md

@@ -0,0 +1,134 @@
+---
+title: "Test telemetry without a collector"
+description: "Assert on what would have been exported: a recording fetch for OTLP payloads, TestJournal for forwarded log records, a fresh metric registry, and the noop layers that stand in for absent telemetry."
+sidebar:
+  order: 6
+---
+
+Telemetry is testable because every outbound edge is a service. Replace the
+edge, keep the wiring, and the assertions are about the payloads a collector
+would have received.
+
+## Record what the exporter posts
+
+`Otlp.layerFetch` delivers over the `FetchHttpClient.Fetch` service, so
+providing your own function captures every export request and touches no
+network:
+
+```ts
+import * as Otlp from "@smthrs/observability/Otlp"
+import * as Effect from "effect/Effect"
+import * as Metric from "effect/Metric"
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient"
+
+const recordingFetch = () => {
+  const requests: Array<{ url: string; body: string }> = []
+  const fetch: typeof globalThis.fetch = (input, init) => {
+    const body = typeof init?.body === "string"
+      ? init.body
+      : new TextDecoder().decode(init?.body as Uint8Array)
+    requests.push({ url: String(input), body })
+    return Promise.resolve(new Response("{}", { status: 200 }))
+  }
+  return { requests, fetch }
+}
+
+const collector = recordingFetch()
+
+await Effect.runPromise(
+  program.pipe(
+    Effect.provide(Otlp.layerFetch({ baseUrl: "http://collector.invalid:4318" })),
+    Effect.provideService(FetchHttpClient.Fetch, collector.fetch),
+    Effect.provideService(Metric.MetricRegistry, new Map()),
+    Effect.orDie,
+    Effect.scoped
+  )
+)
+```
+
+Assert after the scope closes, because the shutdown flush is what delivers a
+short program's signals. Filter `collector.requests` by URL suffix to separate
+the three signals, and parse a body to read span or series names. An
+unresolvable host such as `collector.invalid` is a deliberate choice: if the
+service is ever missed, the test fails rather than reaching the network.
+
+The fresh `Metric.MetricRegistry` map keeps one test's counters out of the
+next test's export.
+
+## Test the journal forwarder
+
+`TestJournal.layer()` from [`@smthrs/journal`](/api/journal) provides the
+production SQLite journal over an in-memory database, so a forwarding test
+exercises the real write path:
+
+```ts
+import * as Journal from "@smthrs/journal/Journal"
+import * as TestJournal from "@smthrs/journal/test/TestJournal"
+import * as JournalLogger from "@smthrs/observability/JournalLogger"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+
+// `runId` is a decoded JournalEvent.RunId, as in the forwarding guide.
+const entries = Effect.gen(function*() {
+  const journal = yield* Journal.Journal
+  yield* Effect.logInfo("hello")
+  const page = yield* journal.entries({ runId, limit: 100 })
+  return page.entries
+}).pipe(
+  Effect.provide(Layer.provideMerge(JournalLogger.layerJournalForwarding({ runId }), TestJournal.layer())),
+  Effect.scoped
+)
+```
+
+Forwarding is asynchronous, so poll until the expected number of entries has
+landed rather than sleeping a fixed interval. To assert on a loss instead,
+read `Metric.value(ObservabilityMetric.droppedLogRecords)`.
+
+## Control time for the retry window
+
+Export retries and the 60-second disable window run on Effect's clock, so
+`TestClock` makes them deterministic:
+
+```ts
+import { TestClock } from "effect/testing"
+
+const exported = Effect.gen(function*() {
+  yield* Effect.void.pipe(Effect.withSpan("exported"))
+  // One initial request plus three transient retries completes within four seconds.
+  yield* TestClock.adjust("5 seconds")
+})
+```
+
+Provide `TestClock.layer()` alongside the exporter, then advance the clock and
+count the recorded requests.
+
+## Stand telemetry down explicitly
+
+A test that is not about telemetry should say so rather than leave the layer
+out and let a type error decide:
+
+| Layer                | What it does                                                    |
+| -------------------- | --------------------------------------------------------------- |
+| `Otlp.layerNoop`     | Provides nothing and exports nothing.                           |
+| `Otel.layerNoop`     | The empty provider-neutral OTEL slot.                           |
+| `Logger.layerNoop()` | Removes the logger set and pins `None` unless you name a level. |
+
+`Journal.layerNoop` from [`@smthrs/journal`](/api/journal) is the matching stub
+for the forwarder when the assertion is about queue behavior rather than about
+persistence.
+
+## Assert on refusals at acquisition
+
+Both configuration refusals happen while the layer is built, so a test builds
+the layer and inspects the exit rather than running a program:
+
+```ts
+import * as Layer from "effect/Layer"
+
+const exit = await Effect.runPromiseExit(
+  Effect.scoped(Layer.build(Otlp.layerFetch({ baseUrl: "collector:4318" })))
+)
+```
+
+The failure is an `Endpoint.InvalidExporterEndpoint` whose `path` is `baseUrl`.
+See [Troubleshooting](../troubleshooting.md) for the catalog.

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

@@ -0,0 +1,220 @@
+---
+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 metrics and tracer instrumentation scope, not log or span resource
+attributes. 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 fixed `telemetry.sdk.name` and
+`telemetry.sdk.language` fields, which are included in the admission budget.
+
+## 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.
+`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,98 @@
+---
+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
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+The package requires Node.js 26.4.0 or later and ships as both ESM and
+CommonJS with TypeScript declarations.
+
+## Pin the same 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. Pin `effect` at exactly `4.0.0-rc.115`.
+
+`Otlp` is written entirely against `effect`, including its HTTP client and its
+`effect/unstable/observability/Otlp` exporters. The required peers
+`@effect/opentelemetry@4.0.0-rc.115` and `@opentelemetry/api@1.9.1`, plus
+the logs and metrics dependencies, support
+the root `Otel` and `Resource` modules. They install with ordinary peer-aware
+package managers. 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/unstable/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).