@btravstack/observability 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benoit TRAVERS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+<!-- doctest: prelude
+import { HttpModule } from "@btravstack/http-server";
+import { Port } from "@btravstack/di";
+import type { AsyncResult } from "unthrown";
+import { orderRouter } from "../../module.js";
+import { otel } from "@btravstack/observability/otel";
+import { cache } from "@btravstack/cache";
+import { redisCache } from "@btravstack/cache/redis";
+import { CustomersSlice } from "../../slices/customers/module.js";
+import { OrdersSlice } from "../../slices/orders/module.js";
+class PlaceOrder extends Port("PlaceOrder")<{
+  readonly execute: (id: string, quantity: number) => AsyncResult<void, never>;
+}> {}
+class OrderRepository extends Port("OrderRepository")<{
+  readonly save: (order: {
+    readonly id: string;
+    readonly quantity: number;
+  }) => AsyncResult<void, never>;
+}> {}
+-->
+
+# @btravstack/observability
+
+> Observability for [`@btravstack/core`](../core), starting with logging: a
+> **strict** `Logger` port — no `any`, no printf, no mutable context, no static
+> instance — a default implementation that stamps every line with the ambient
+> unit's trace id, a dependency-free JSON sink, pino behind a subpath, and the
+> kernel's nine lifecycle events as log lines in the same stream.
+
+📖 **[Documentation](https://btravstack.github.io/btravstack/reference/observability)** ·
+[How-to](https://btravstack.github.io/btravstack/how-to/log-and-correlate) ·
+[API Reference](https://btravstack.github.io/btravstack/api/observability/)
+
+```sh
+pnpm add @btravstack/observability @btravstack/core @btravstack/config @btravstack/di unthrown
+```
+
+Those four are peers. `pino` is an **optional** peer, needed only if you import
+`@btravstack/observability/pino`. Node `>=20`.
+
+## A worked example
+
+```ts
+import { runMain, Logger } from "@btravstack/core";
+import {
+  createLogger,
+  jsonSink,
+  kernelEvents,
+  observability,
+} from "@btravstack/observability";
+import { Module, Provider } from "@btravstack/di";
+
+// The application depends on the port, like any other service.
+const placeOrder = Provider(PlaceOrder)(
+  { orders: OrderRepository, logger: Logger },
+  {
+    sync: ({ orders, logger }) => ({
+      execute: (id, quantity) =>
+        orders
+          .save({ id, quantity })
+          .tap(() => logger.info("order placed", { id, quantity })),
+    }),
+  },
+);
+
+// The starter provides it. `LOG_LEVEL` is read inside the graph and validated
+// once — `verbose` is a startup failure naming the variable, not a silent
+// fallback to `info`.
+const OrderApi = HttpModule("OrderApi")({
+  router: orderRouter,
+  imports: [
+    OrdersSlice,
+    CustomersSlice,
+    cache({ adapter: redisCache() }),
+    observability(),
+    otel(),
+  ],
+  exports: [Logger],
+});
+
+// The kernel's own events, in the same stream and the same shape. The logger
+// here is built by hand because `building` is emitted while the graph still
+// is: the sink cannot come from the context it is watching.
+await runMain(OrderApi, { onEvent: kernelEvents(createLogger(jsonSink())) });
+```
+
+Every line written inside a unit carries that unit's `traceId`, `unitId` and
+`tenantId` — the logger reads `currentUnit()` **per call**, so one
+application-scope logger is correct for every request without a single
+argument threaded through the call stack.
+
+```json
+{
+  "orderId": "0199a1e0-0000-7000-8000-000000000001",
+  "time": "2026-08-16T09:41:02.113Z",
+  "level": "info",
+  "message": "order placed",
+  "unitId": "u-7",
+  "traceId": "3f9c…"
+}
+```
+
+## What makes the interface strict
+
+| Decision                                 | Why                                                                                                                 |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| A **port**, never a class or a static    | A test provides its own; there is no global to reach past DI with                                                   |
+| `with(attributes)` returns a logger      | Nothing mutates: two scopes cannot interleave each other's context                                                  |
+| `Attributes` is a flat record of scalars | The shape a log backend indexes; no `any`, no printf, no stringifying whatever it is handed                         |
+| A failure goes in `cause`                | An `Error`'s `message` and `stack` are non-enumerable — `JSON.stringify` alone drops exactly the part worth keeping |
+| It cannot throw                          | A broken sink is swallowed: an observability fault must not become an outage                                        |
+| Six levels, fixed                        | `LOG_LEVEL` is validated at startup, and `isEnabled` is a comparison                                                |
+
+## Swapping the implementation
+
+`observability({ sink })` replaces the destination; providing `Logger`
+yourself replaces everything. For a deployment that wants pino's throughput:
+
+<!-- doctest: skip — needs `pino`, which no example workspace installs; held by packages/observability/src/pino.spec.ts instead -->
+
+```ts
+import pino from "pino";
+import { pinoSink } from "@btravstack/observability/pino";
+
+observability({ sink: pinoSink(pino()) });
+```
+
+The level filter stays this package's — `LOG_LEVEL`, validated once — so there
+is one filter in the process rather than two that can disagree.
+
+## Traces and metrics
+
+The other half of the package's name, behind an optional-peer subpath the way
+`pino` is:
+
+```sh
+pnpm add @opentelemetry/api @opentelemetry/sdk-node
+```
+
+<!-- doctest: skip — needs `@opentelemetry/*`, which no example workspace installs; held by packages/observability/src/otel.spec.ts instead -->
+
+```ts
+import { observability } from "@btravstack/observability";
+import { UnitSpanModule, otel } from "@btravstack/observability/otel";
+
+// Beside observability() in the root's imports; the SDK is a resource of the
+// graph — started with the scope, flushed by release on every exit path.
+// Configuration is the OTEL_* environment conventions, read by the SDK itself.
+const AppImports = [observability(), otel()];
+
+// A span per kernel unit, correlated with the same ids the logger stamps:
+// runMain(App, { unit: UnitSpanModule })
+```
+
+Inbound W3C `traceparent` feeds the unit's trace id in `@btravstack/http-server` and
+`@btravstack/amqp-worker`. Auto-instrumentation must be preloaded
+(`node --import @opentelemetry/auto-instrumentations-node/register`) — it
+cannot be a provider, and the package does not pretend otherwise. Full
+semantics on
+[the reference page](https://btravstack.github.io/btravstack/reference/observability).
+
+## License
+
+[MIT](./LICENSE) © Benoit TRAVERS

package/dist/index.cjs

@@ -0,0 +1,213 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _btravstack_config = require("@btravstack/config");
+let _btravstack_core = require("@btravstack/core");
+let unthrown = require("unthrown");
+let _btravstack_di = require("@btravstack/di");
+//#region src/config.ts
+/**
+* `LOG_LEVEL`, as a `ConfigField` of the six levels and nothing else.
+*
+* A value outside the set is a `ConfigInvalid` naming the variable — exit
+* `78` under `runMain`, before a line is written — rather than a silent
+* fallback to `info`: a deployment that meant `debug` and typed `verbose`
+* should be told, not quietly under-logged for a week. Built on
+* `Config.string`, so it inherits the semantics every other variable has: an
+* unset variable takes the default, a set-but-blank one is an error.
+*/
+const logLevel = (options = {}) => {
+	const text = _btravstack_config.Config.string("LOG_LEVEL", { default: options.default ?? "info" });
+	return {
+		variable: text.variable,
+		parse: (raw) => text.parse(raw).flatMap((value) => _btravstack_core.LEVELS.includes(value) ? (0, unthrown.Ok)(value) : (0, unthrown.Err)(new _btravstack_config.ConfigFieldInvalid({ reason: `must be one of ${_btravstack_core.LEVELS.join(", ")}, got ${JSON.stringify(value)}` })))
+	};
+};
+/** The schema `observability()` binds `LoggerConfig` through — one field today, and the place a second one lands. */
+const loggerSchema = (level) => _btravstack_config.Config.object({ level: _btravstack_config.Config.pinned(level, logLevel()) });
+//#endregion
+//#region src/json-sink.ts
+/**
+* An `Error`'s `message` and `stack` are **non-enumerable**, so
+* `JSON.stringify` renders a thrown one as `{}` — the line that exists to carry
+* a failure would carry nothing. Walks `cause` chains so a wrapped failure keeps
+* its origin.
+*/
+const renderCause = (cause, depth = 0) => {
+	if (!(cause instanceof Error)) return cause;
+	return {
+		name: cause.name,
+		message: cause.message,
+		stack: cause.stack,
+		...cause.cause === void 0 || depth >= 4 ? {} : { cause: renderCause(cause.cause, depth + 1) }
+	};
+};
+/**
+* One JSON object per line on `stream`.
+*
+* The caller's attributes are spread FIRST and the line's own fields after them,
+* and that order is the precedence: an `attributes: { level: "info" }` cannot
+* rewrite an `error` line's severity, nor its `traceId`.
+*
+* The unit's ids are spread at the top level rather than nested under `unit`,
+* because `traceId` is the field an operator searches.
+*/
+const jsonSink = (stream = process.stdout) => (line) => {
+	const { level, message, attributes, cause, time, unit } = line;
+	const rendered = {
+		...attributes,
+		time: new Date(time).toISOString(),
+		level,
+		message,
+		...unit === void 0 ? {} : unit,
+		...cause === void 0 ? {} : { cause: renderCause(cause) }
+	};
+	stream.write(`${safeStringify(rendered)}\n`);
+};
+const safeStringify = (rendered) => {
+	try {
+		return JSON.stringify(rendered);
+	} catch {
+		return JSON.stringify({
+			time: rendered["time"],
+			level: rendered["level"],
+			message: rendered["message"],
+			cause: "[unserialisable]"
+		});
+	}
+};
+//#endregion
+//#region src/logger.ts
+const severity = (level) => _btravstack_core.LEVELS.indexOf(level);
+/**
+* A logger over `sink`, filtered at `level` and correlated with the ambient
+* unit.
+*
+* The correlation is read **per call**, not captured: one logger is built per
+* scope and every unit the kernel opens has its own record, so a logger that
+* captured it at construction would stamp the wrong trace id on every line but
+* the first. `with` layers attributes and nothing else, so a child costs one
+* object and shares the sink.
+*
+* Every path is wrapped: a sink that throws is swallowed here, because a
+* logger that takes the process down is worse than a line nobody sees.
+*/
+const createLogger = (sink, level = "info") => {
+	const floor = severity(level);
+	const build = (base) => {
+		const write = (lineLevel, message, attributes, cause) => {
+			if (severity(lineLevel) < floor) return;
+			const unit = (0, _btravstack_core.currentUnit)();
+			try {
+				sink({
+					level: lineLevel,
+					message,
+					attributes: attributes === void 0 ? base : {
+						...base,
+						...attributes
+					},
+					cause,
+					time: Date.now(),
+					unit: unit === void 0 ? void 0 : {
+						unitId: unit.unitId,
+						traceId: unit.traceId,
+						...unit.tenantId === void 0 ? {} : { tenantId: unit.tenantId }
+					}
+				});
+			} catch {}
+		};
+		return {
+			log: (lineLevel, message, attributes, cause) => write(lineLevel, message, attributes, cause),
+			trace: (message, attributes, cause) => write("trace", message, attributes, cause),
+			debug: (message, attributes, cause) => write("debug", message, attributes, cause),
+			info: (message, attributes, cause) => write("info", message, attributes, cause),
+			warn: (message, attributes, cause) => write("warn", message, attributes, cause),
+			error: (message, attributes, cause) => write("error", message, attributes, cause),
+			fatal: (message, attributes, cause) => write("fatal", message, attributes, cause),
+			with: (attributes) => build({
+				...base,
+				...attributes
+			}),
+			isEnabled: (lineLevel) => severity(lineLevel) >= floor
+		};
+	};
+	return build({});
+};
+//#endregion
+//#region src/observability.ts
+/**
+* What the graph bound from the environment: the level every logger in it
+* filters at. A port of its own, like a starter's `HttpConfig`, so anything
+* that wants to know reads it rather than re-deriving it.
+*/
+var LoggerConfig = class extends (0, _btravstack_di.Port)("LoggerConfig") {};
+/**
+* The observability starter: a module providing the application's `Logger` and
+* the `LoggerConfig` it was built from. Import it next to the application and
+* export `Logger`.
+*
+* Every line carries the ambient unit's `traceId`, because the logger reads
+* `currentUnit()` per call — so a request's lines are attributable with no
+* argument threaded through the call stack.
+*/
+const observability = (options = {}) => (0, _btravstack_di.Module)("Observability")({
+	needs: [_btravstack_config.Env],
+	provides: [_btravstack_config.Config.provider(LoggerConfig)(loggerSchema(options.level)), (0, _btravstack_di.Provider)(_btravstack_core.Logger)({ config: LoggerConfig }, { sync: ({ config }) => createLogger(options.sink ?? jsonSink(), config.level) })],
+	exports: [_btravstack_core.Logger, LoggerConfig]
+});
+/**
+* The kernel's nine lifecycle events, as log lines on `logger` — the adapter
+* between `StartOptions.onEvent` and an application's own stream.
+*
+* The mapping is deliberate rather than mechanical: `startFailed` and `uncaught`
+* are `error`, `teardownError` is `warn` (the application is already stopping
+* and the exit code says so), everything else `info`. Each event's own fields
+* become attributes, so a drain is queryable by field.
+*
+* The logger is a PARAMETER, not resolved: `building` is emitted while the graph
+* is still being built, so the sink cannot come from the context it watches.
+*/
+const kernelEvents = (logger) => (event) => {
+	switch (event.type) {
+		case "startFailed":
+			logger.error("the application failed to start", { event: event.type }, event.cause);
+			return;
+		case "uncaught":
+			logger.error("an uncaught exception stopped the application", { event: event.type }, event.cause);
+			return;
+		case "teardownError":
+			logger.warn("a finaliser failed while the application was stopping", {
+				event: event.type,
+				port: event.port
+			}, event.cause);
+			return;
+		case "serving":
+			logger.info("serving", {
+				event: event.type,
+				runtime: event.runtime,
+				probePort: event.probePort,
+				...typeof event.info === "object" && event.info !== null && !Array.isArray(event.info) ? event.info : {}
+			});
+			return;
+		case "draining":
+			logger.info("draining", {
+				event: event.type,
+				inFlight: event.inFlight
+			});
+			return;
+		case "drained":
+			logger.info("drained", {
+				event: event.type,
+				inFlightAtStart: event.report.inFlightAtStart,
+				completed: event.report.completed,
+				abandoned: event.report.abandoned
+			});
+			return;
+		default: logger.info(event.type, { event: event.type });
+	}
+};
+//#endregion
+exports.LoggerConfig = LoggerConfig;
+exports.createLogger = createLogger;
+exports.jsonSink = jsonSink;
+exports.kernelEvents = kernelEvents;
+exports.logLevel = logLevel;
+exports.observability = observability;

package/dist/index.d.cts

@@ -0,0 +1,81 @@
+import { n as Sink, r as createLogger, t as Line } from "./logger-B1-_76ej.cjs";
+import { ConfigField, ConfigInvalid, Env } from "@btravstack/config";
+import { EventSink, Level, Logger, LoggerService } from "@btravstack/core";
+import { Module } from "@btravstack/di";
+//#region src/config.d.ts
+/**
+ * `LOG_LEVEL`, as a `ConfigField` of the six levels and nothing else.
+ *
+ * A value outside the set is a `ConfigInvalid` naming the variable — exit
+ * `78` under `runMain`, before a line is written — rather than a silent
+ * fallback to `info`: a deployment that meant `debug` and typed `verbose`
+ * should be told, not quietly under-logged for a week. Built on
+ * `Config.string`, so it inherits the semantics every other variable has: an
+ * unset variable takes the default, a set-but-blank one is an error.
+ */
+declare const logLevel: (options?: {
+  readonly default?: Level;
+}) => ConfigField<Level>;
+/** What `observability()` binds from the environment. */
+type LoggerSettings = {
+  readonly level: Level;
+};
+//#endregion
+//#region src/json-sink.d.ts
+/**
+ * One JSON object per line on `stream`.
+ *
+ * The caller's attributes are spread FIRST and the line's own fields after them,
+ * and that order is the precedence: an `attributes: { level: "info" }` cannot
+ * rewrite an `error` line's severity, nor its `traceId`.
+ *
+ * The unit's ids are spread at the top level rather than nested under `unit`,
+ * because `traceId` is the field an operator searches.
+ */
+declare const jsonSink: (stream?: {
+  readonly write: (chunk: string) => unknown;
+}) => Sink;
+//#endregion
+//#region src/observability.d.ts
+declare const LoggerConfig_base: import("@btravstack/di").PortClass<"LoggerConfig">;
+/**
+ * What the graph bound from the environment: the level every logger in it
+ * filters at. A port of its own, like a starter's `HttpConfig`, so anything
+ * that wants to know reads it rather than re-deriving it.
+ */
+declare class LoggerConfig extends LoggerConfig_base<LoggerSettings> {}
+type ObservabilityOptions = {
+  /**
+   * Where lines go. Default: one JSON object per line on `stdout`. The
+   * `@btravstack/observability/pino` subpath is the same seam for a deployment
+   * that wants pino's throughput.
+   */
+  readonly sink?: Sink;
+  /** Pins the level instead of reading `LOG_LEVEL` — a test's `"fatal"`, a CLI's `"debug"`. */
+  readonly level?: Level;
+};
+/**
+ * The observability starter: a module providing the application's `Logger` and
+ * the `LoggerConfig` it was built from. Import it next to the application and
+ * export `Logger`.
+ *
+ * Every line carries the ambient unit's `traceId`, because the logger reads
+ * `currentUnit()` per call — so a request's lines are attributable with no
+ * argument threaded through the call stack.
+ */
+declare const observability: (options?: ObservabilityOptions) => Module<Logger | LoggerConfig, ConfigInvalid, Env>;
+/**
+ * The kernel's nine lifecycle events, as log lines on `logger` — the adapter
+ * between `StartOptions.onEvent` and an application's own stream.
+ *
+ * The mapping is deliberate rather than mechanical: `startFailed` and `uncaught`
+ * are `error`, `teardownError` is `warn` (the application is already stopping
+ * and the exit code says so), everything else `info`. Each event's own fields
+ * become attributes, so a drain is queryable by field.
+ *
+ * The logger is a PARAMETER, not resolved: `building` is emitted while the graph
+ * is still being built, so the sink cannot come from the context it watches.
+ */
+declare const kernelEvents: (logger: LoggerService) => EventSink;
+//#endregion
+export { type Line, LoggerConfig, type LoggerSettings, type ObservabilityOptions, type Sink, createLogger, jsonSink, kernelEvents, logLevel, observability };

package/dist/index.d.mts

@@ -0,0 +1,81 @@
+import { n as Sink, r as createLogger, t as Line } from "./logger-B1-_76ej.mjs";
+import { ConfigField, ConfigInvalid, Env } from "@btravstack/config";
+import { EventSink, Level, Logger, LoggerService } from "@btravstack/core";
+import { Module } from "@btravstack/di";
+//#region src/config.d.ts
+/**
+ * `LOG_LEVEL`, as a `ConfigField` of the six levels and nothing else.
+ *
+ * A value outside the set is a `ConfigInvalid` naming the variable — exit
+ * `78` under `runMain`, before a line is written — rather than a silent
+ * fallback to `info`: a deployment that meant `debug` and typed `verbose`
+ * should be told, not quietly under-logged for a week. Built on
+ * `Config.string`, so it inherits the semantics every other variable has: an
+ * unset variable takes the default, a set-but-blank one is an error.
+ */
+declare const logLevel: (options?: {
+  readonly default?: Level;
+}) => ConfigField<Level>;
+/** What `observability()` binds from the environment. */
+type LoggerSettings = {
+  readonly level: Level;
+};
+//#endregion
+//#region src/json-sink.d.ts
+/**
+ * One JSON object per line on `stream`.
+ *
+ * The caller's attributes are spread FIRST and the line's own fields after them,
+ * and that order is the precedence: an `attributes: { level: "info" }` cannot
+ * rewrite an `error` line's severity, nor its `traceId`.
+ *
+ * The unit's ids are spread at the top level rather than nested under `unit`,
+ * because `traceId` is the field an operator searches.
+ */
+declare const jsonSink: (stream?: {
+  readonly write: (chunk: string) => unknown;
+}) => Sink;
+//#endregion
+//#region src/observability.d.ts
+declare const LoggerConfig_base: import("@btravstack/di").PortClass<"LoggerConfig">;
+/**
+ * What the graph bound from the environment: the level every logger in it
+ * filters at. A port of its own, like a starter's `HttpConfig`, so anything
+ * that wants to know reads it rather than re-deriving it.
+ */
+declare class LoggerConfig extends LoggerConfig_base<LoggerSettings> {}
+type ObservabilityOptions = {
+  /**
+   * Where lines go. Default: one JSON object per line on `stdout`. The
+   * `@btravstack/observability/pino` subpath is the same seam for a deployment
+   * that wants pino's throughput.
+   */
+  readonly sink?: Sink;
+  /** Pins the level instead of reading `LOG_LEVEL` — a test's `"fatal"`, a CLI's `"debug"`. */
+  readonly level?: Level;
+};
+/**
+ * The observability starter: a module providing the application's `Logger` and
+ * the `LoggerConfig` it was built from. Import it next to the application and
+ * export `Logger`.
+ *
+ * Every line carries the ambient unit's `traceId`, because the logger reads
+ * `currentUnit()` per call — so a request's lines are attributable with no
+ * argument threaded through the call stack.
+ */
+declare const observability: (options?: ObservabilityOptions) => Module<Logger | LoggerConfig, ConfigInvalid, Env>;
+/**
+ * The kernel's nine lifecycle events, as log lines on `logger` — the adapter
+ * between `StartOptions.onEvent` and an application's own stream.
+ *
+ * The mapping is deliberate rather than mechanical: `startFailed` and `uncaught`
+ * are `error`, `teardownError` is `warn` (the application is already stopping
+ * and the exit code says so), everything else `info`. Each event's own fields
+ * become attributes, so a drain is queryable by field.
+ *
+ * The logger is a PARAMETER, not resolved: `building` is emitted while the graph
+ * is still being built, so the sink cannot come from the context it watches.
+ */
+declare const kernelEvents: (logger: LoggerService) => EventSink;
+//#endregion
+export { type Line, LoggerConfig, type LoggerSettings, type ObservabilityOptions, type Sink, createLogger, jsonSink, kernelEvents, logLevel, observability };

package/dist/index.mjs

@@ -0,0 +1,207 @@
+import { Config, ConfigFieldInvalid, Env } from "@btravstack/config";
+import { LEVELS, Logger, currentUnit } from "@btravstack/core";
+import { Err, Ok } from "unthrown";
+import { Module, Port, Provider } from "@btravstack/di";
+//#region src/config.ts
+/**
+* `LOG_LEVEL`, as a `ConfigField` of the six levels and nothing else.
+*
+* A value outside the set is a `ConfigInvalid` naming the variable — exit
+* `78` under `runMain`, before a line is written — rather than a silent
+* fallback to `info`: a deployment that meant `debug` and typed `verbose`
+* should be told, not quietly under-logged for a week. Built on
+* `Config.string`, so it inherits the semantics every other variable has: an
+* unset variable takes the default, a set-but-blank one is an error.
+*/
+const logLevel = (options = {}) => {
+	const text = Config.string("LOG_LEVEL", { default: options.default ?? "info" });
+	return {
+		variable: text.variable,
+		parse: (raw) => text.parse(raw).flatMap((value) => LEVELS.includes(value) ? Ok(value) : Err(new ConfigFieldInvalid({ reason: `must be one of ${LEVELS.join(", ")}, got ${JSON.stringify(value)}` })))
+	};
+};
+/** The schema `observability()` binds `LoggerConfig` through — one field today, and the place a second one lands. */
+const loggerSchema = (level) => Config.object({ level: Config.pinned(level, logLevel()) });
+//#endregion
+//#region src/json-sink.ts
+/**
+* An `Error`'s `message` and `stack` are **non-enumerable**, so
+* `JSON.stringify` renders a thrown one as `{}` — the line that exists to carry
+* a failure would carry nothing. Walks `cause` chains so a wrapped failure keeps
+* its origin.
+*/
+const renderCause = (cause, depth = 0) => {
+	if (!(cause instanceof Error)) return cause;
+	return {
+		name: cause.name,
+		message: cause.message,
+		stack: cause.stack,
+		...cause.cause === void 0 || depth >= 4 ? {} : { cause: renderCause(cause.cause, depth + 1) }
+	};
+};
+/**
+* One JSON object per line on `stream`.
+*
+* The caller's attributes are spread FIRST and the line's own fields after them,
+* and that order is the precedence: an `attributes: { level: "info" }` cannot
+* rewrite an `error` line's severity, nor its `traceId`.
+*
+* The unit's ids are spread at the top level rather than nested under `unit`,
+* because `traceId` is the field an operator searches.
+*/
+const jsonSink = (stream = process.stdout) => (line) => {
+	const { level, message, attributes, cause, time, unit } = line;
+	const rendered = {
+		...attributes,
+		time: new Date(time).toISOString(),
+		level,
+		message,
+		...unit === void 0 ? {} : unit,
+		...cause === void 0 ? {} : { cause: renderCause(cause) }
+	};
+	stream.write(`${safeStringify(rendered)}\n`);
+};
+const safeStringify = (rendered) => {
+	try {
+		return JSON.stringify(rendered);
+	} catch {
+		return JSON.stringify({
+			time: rendered["time"],
+			level: rendered["level"],
+			message: rendered["message"],
+			cause: "[unserialisable]"
+		});
+	}
+};
+//#endregion
+//#region src/logger.ts
+const severity = (level) => LEVELS.indexOf(level);
+/**
+* A logger over `sink`, filtered at `level` and correlated with the ambient
+* unit.
+*
+* The correlation is read **per call**, not captured: one logger is built per
+* scope and every unit the kernel opens has its own record, so a logger that
+* captured it at construction would stamp the wrong trace id on every line but
+* the first. `with` layers attributes and nothing else, so a child costs one
+* object and shares the sink.
+*
+* Every path is wrapped: a sink that throws is swallowed here, because a
+* logger that takes the process down is worse than a line nobody sees.
+*/
+const createLogger = (sink, level = "info") => {
+	const floor = severity(level);
+	const build = (base) => {
+		const write = (lineLevel, message, attributes, cause) => {
+			if (severity(lineLevel) < floor) return;
+			const unit = currentUnit();
+			try {
+				sink({
+					level: lineLevel,
+					message,
+					attributes: attributes === void 0 ? base : {
+						...base,
+						...attributes
+					},
+					cause,
+					time: Date.now(),
+					unit: unit === void 0 ? void 0 : {
+						unitId: unit.unitId,
+						traceId: unit.traceId,
+						...unit.tenantId === void 0 ? {} : { tenantId: unit.tenantId }
+					}
+				});
+			} catch {}
+		};
+		return {
+			log: (lineLevel, message, attributes, cause) => write(lineLevel, message, attributes, cause),
+			trace: (message, attributes, cause) => write("trace", message, attributes, cause),
+			debug: (message, attributes, cause) => write("debug", message, attributes, cause),
+			info: (message, attributes, cause) => write("info", message, attributes, cause),
+			warn: (message, attributes, cause) => write("warn", message, attributes, cause),
+			error: (message, attributes, cause) => write("error", message, attributes, cause),
+			fatal: (message, attributes, cause) => write("fatal", message, attributes, cause),
+			with: (attributes) => build({
+				...base,
+				...attributes
+			}),
+			isEnabled: (lineLevel) => severity(lineLevel) >= floor
+		};
+	};
+	return build({});
+};
+//#endregion
+//#region src/observability.ts
+/**
+* What the graph bound from the environment: the level every logger in it
+* filters at. A port of its own, like a starter's `HttpConfig`, so anything
+* that wants to know reads it rather than re-deriving it.
+*/
+var LoggerConfig = class extends Port("LoggerConfig") {};
+/**
+* The observability starter: a module providing the application's `Logger` and
+* the `LoggerConfig` it was built from. Import it next to the application and
+* export `Logger`.
+*
+* Every line carries the ambient unit's `traceId`, because the logger reads
+* `currentUnit()` per call — so a request's lines are attributable with no
+* argument threaded through the call stack.
+*/
+const observability = (options = {}) => Module("Observability")({
+	needs: [Env],
+	provides: [Config.provider(LoggerConfig)(loggerSchema(options.level)), Provider(Logger)({ config: LoggerConfig }, { sync: ({ config }) => createLogger(options.sink ?? jsonSink(), config.level) })],
+	exports: [Logger, LoggerConfig]
+});
+/**
+* The kernel's nine lifecycle events, as log lines on `logger` — the adapter
+* between `StartOptions.onEvent` and an application's own stream.
+*
+* The mapping is deliberate rather than mechanical: `startFailed` and `uncaught`
+* are `error`, `teardownError` is `warn` (the application is already stopping
+* and the exit code says so), everything else `info`. Each event's own fields
+* become attributes, so a drain is queryable by field.
+*
+* The logger is a PARAMETER, not resolved: `building` is emitted while the graph
+* is still being built, so the sink cannot come from the context it watches.
+*/
+const kernelEvents = (logger) => (event) => {
+	switch (event.type) {
+		case "startFailed":
+			logger.error("the application failed to start", { event: event.type }, event.cause);
+			return;
+		case "uncaught":
+			logger.error("an uncaught exception stopped the application", { event: event.type }, event.cause);
+			return;
+		case "teardownError":
+			logger.warn("a finaliser failed while the application was stopping", {
+				event: event.type,
+				port: event.port
+			}, event.cause);
+			return;
+		case "serving":
+			logger.info("serving", {
+				event: event.type,
+				runtime: event.runtime,
+				probePort: event.probePort,
+				...typeof event.info === "object" && event.info !== null && !Array.isArray(event.info) ? event.info : {}
+			});
+			return;
+		case "draining":
+			logger.info("draining", {
+				event: event.type,
+				inFlight: event.inFlight
+			});
+			return;
+		case "drained":
+			logger.info("drained", {
+				event: event.type,
+				inFlightAtStart: event.report.inFlightAtStart,
+				completed: event.report.completed,
+				abandoned: event.report.abandoned
+			});
+			return;
+		default: logger.info(event.type, { event: event.type });
+	}
+};
+//#endregion
+export { LoggerConfig, createLogger, jsonSink, kernelEvents, logLevel, observability };

package/dist/logger-B1-_76ej.d.cts

@@ -0,0 +1,35 @@
+import { Attributes, Level, LoggerService } from "@btravstack/core";
+//#region src/logger.d.ts
+/** One line, as the implementation hands it to a {@link Sink}: the message, its severity, and everything known about it. */
+type Line = {
+  readonly level: Level;
+  readonly message: string;
+  readonly attributes: Attributes;
+  readonly cause: unknown;
+  /** Milliseconds since the epoch, stamped when the line was written. */
+  readonly time: number;
+  /** What `currentUnit()` carried, or `undefined` outside a unit. */
+  readonly unit: {
+    readonly unitId: string;
+    readonly traceId: string;
+    readonly tenantId?: string;
+  } | undefined;
+};
+/** Where a line goes. Given a {@link Line}, writes it — and never throws, which `createLogger` guarantees on its behalf. */
+type Sink = (line: Line) => void;
+/**
+ * A logger over `sink`, filtered at `level` and correlated with the ambient
+ * unit.
+ *
+ * The correlation is read **per call**, not captured: one logger is built per
+ * scope and every unit the kernel opens has its own record, so a logger that
+ * captured it at construction would stamp the wrong trace id on every line but
+ * the first. `with` layers attributes and nothing else, so a child costs one
+ * object and shares the sink.
+ *
+ * Every path is wrapped: a sink that throws is swallowed here, because a
+ * logger that takes the process down is worse than a line nobody sees.
+ */
+declare const createLogger: (sink: Sink, level?: Level) => LoggerService;
+//#endregion
+export { Sink as n, createLogger as r, Line as t };

package/dist/logger-B1-_76ej.d.mts

@@ -0,0 +1,35 @@
+import { Attributes, Level, LoggerService } from "@btravstack/core";
+//#region src/logger.d.ts
+/** One line, as the implementation hands it to a {@link Sink}: the message, its severity, and everything known about it. */
+type Line = {
+  readonly level: Level;
+  readonly message: string;
+  readonly attributes: Attributes;
+  readonly cause: unknown;
+  /** Milliseconds since the epoch, stamped when the line was written. */
+  readonly time: number;
+  /** What `currentUnit()` carried, or `undefined` outside a unit. */
+  readonly unit: {
+    readonly unitId: string;
+    readonly traceId: string;
+    readonly tenantId?: string;
+  } | undefined;
+};
+/** Where a line goes. Given a {@link Line}, writes it — and never throws, which `createLogger` guarantees on its behalf. */
+type Sink = (line: Line) => void;
+/**
+ * A logger over `sink`, filtered at `level` and correlated with the ambient
+ * unit.
+ *
+ * The correlation is read **per call**, not captured: one logger is built per
+ * scope and every unit the kernel opens has its own record, so a logger that
+ * captured it at construction would stamp the wrong trace id on every line but
+ * the first. `with` layers attributes and nothing else, so a child costs one
+ * object and shares the sink.
+ *
+ * Every path is wrapped: a sink that throws is swallowed here, because a
+ * logger that takes the process down is worse than a line nobody sees.
+ */
+declare const createLogger: (sink: Sink, level?: Level) => LoggerService;
+//#endregion
+export { Sink as n, createLogger as r, Line as t };

package/dist/otel.cjs

@@ -0,0 +1,90 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _btravstack_core = require("@btravstack/core");
+let unthrown = require("unthrown");
+let _btravstack_di = require("@btravstack/di");
+let _opentelemetry_api = require("@opentelemetry/api");
+let _opentelemetry_sdk_node = require("@opentelemetry/sdk-node");
+//#region src/otel.ts
+/**
+* The tracing half of observability — the ADAPTER, not the contract. `Tracer`
+* and `Meter` are the kernel's ports, and OTel's presence stops at this subpath,
+* behind an optional peer exactly like `pino`.
+*
+* The ports are narrowings of OTel's own shapes, so what the SDK hands back
+* satisfies them with no translation in between.
+*/
+/**
+* The SDK itself, module-private: providing it is what starts it, and `release`
+* is what flushes it. It rides the graph as a RESOURCE so the kernel closes it
+* on every exit path — a span lost in `shutdown()` becomes a `teardownError` and
+* exit `2`, never silence.
+*/
+var OtelSdk = class extends (0, _btravstack_di.Port)("OtelSdk") {};
+/**
+* The OTel starter: a module providing `Tracer` and `Meter` over a `NodeSDK`
+* opened with the scope and flushed on close. Compose it beside
+* `observability()` in a root's `imports`.
+*
+* **No config slice, deliberately**: the SDK reads the `OTEL_*` environment
+* conventions itself, and re-binding them through `Config` would be a second
+* spelling of names operators already know. Programmatic overrides go through
+* `options`, the SDK's own configuration type.
+*
+* **Auto-instrumentation cannot live here**: the register hook must be
+* preloaded before the instrumented libraries are imported, which no DI
+* provider can promise. Preloading is the deployment's line.
+*/
+const otel = (options) => (0, _btravstack_di.Module)("Otel")({
+	provides: [
+		(0, _btravstack_di.Provider)(OtelSdk)({
+			acquire: () => {
+				const sdk = new _opentelemetry_sdk_node.NodeSDK(options);
+				sdk.start();
+				return (0, unthrown.Ok)(sdk);
+			},
+			release: (sdk) => sdk.shutdown()
+		}),
+		(0, _btravstack_di.Provider)(_btravstack_core.Tracer)({ sdk: OtelSdk }, { sync: () => {
+			const tracer = _opentelemetry_api.trace.getTracer("@btravstack/observability");
+			return { startSpan: (name) => tracer.startSpan(name) };
+		} }),
+		(0, _btravstack_di.Provider)(_btravstack_core.Meter)({ sdk: OtelSdk }, { sync: () => _opentelemetry_api.metrics.getMeter("@btravstack/observability") })
+	],
+	exports: [_btravstack_core.Tracer, _btravstack_core.Meter]
+});
+/** The span a unit rides, ended when the unit's fork closes. */
+var UnitSpan = class extends (0, _btravstack_di.Port)("UnitSpan") {};
+/**
+* A span per kernel unit, as a `StartOptions.unit` module: the kernel forks it
+* per unit and tears it down inside the unit's ambient record, so the span opens
+* when the unit does and `onStop` ends it on every path out.
+*
+* The correlation is the ambient record's own, carried as attributes so a span
+* joins the same query the logger's lines answer. The remote PARENT is
+* deliberately not reconstructed: `UnitMeta.traceId` carries the inbound trace
+* id alone, so this correlates by attribute rather than pretending to a W3C
+* parent-child edge it cannot prove.
+*
+* Compose it as `start`'s `unit`; the root must export `Tracer`.
+*/
+const UnitSpanModule = (0, _btravstack_di.Module)("UnitSpan")({
+	needs: [_btravstack_core.Tracer],
+	provides: [(0, _btravstack_di.Provider)(UnitSpan)({ tracer: _btravstack_core.Tracer }, {
+		sync: ({ tracer }) => {
+			const unit = (0, _btravstack_core.currentUnit)();
+			const span = tracer.startSpan("unit");
+			if (unit !== void 0) span.setAttributes({
+				"btravstack.unit_id": unit.unitId,
+				"btravstack.trace_id": unit.traceId,
+				...unit.tenantId === void 0 ? {} : { "btravstack.tenant_id": unit.tenantId }
+			});
+			return span;
+		},
+		onStop: (span) => span.end()
+	})],
+	exports: [UnitSpan]
+});
+//#endregion
+exports.UnitSpan = UnitSpan;
+exports.UnitSpanModule = UnitSpanModule;
+exports.otel = otel;

package/dist/otel.d.cts

@@ -0,0 +1,38 @@
+import { Meter, Span, Tracer } from "@btravstack/core";
+import { Module, Scope } from "@btravstack/di";
+import { NodeSDKConfiguration } from "@opentelemetry/sdk-node";
+//#region src/otel.d.ts
+/**
+ * The OTel starter: a module providing `Tracer` and `Meter` over a `NodeSDK`
+ * opened with the scope and flushed on close. Compose it beside
+ * `observability()` in a root's `imports`.
+ *
+ * **No config slice, deliberately**: the SDK reads the `OTEL_*` environment
+ * conventions itself, and re-binding them through `Config` would be a second
+ * spelling of names operators already know. Programmatic overrides go through
+ * `options`, the SDK's own configuration type.
+ *
+ * **Auto-instrumentation cannot live here**: the register hook must be
+ * preloaded before the instrumented libraries are imported, which no DI
+ * provider can promise. Preloading is the deployment's line.
+ */
+declare const otel: (options?: Partial<NodeSDKConfiguration>) => Module<Tracer | Meter, never, Scope>;
+declare const UnitSpan_base: import("@btravstack/di").PortClass<"UnitSpan">;
+/** The span a unit rides, ended when the unit's fork closes. */
+declare class UnitSpan extends UnitSpan_base<Span> {}
+/**
+ * A span per kernel unit, as a `StartOptions.unit` module: the kernel forks it
+ * per unit and tears it down inside the unit's ambient record, so the span opens
+ * when the unit does and `onStop` ends it on every path out.
+ *
+ * The correlation is the ambient record's own, carried as attributes so a span
+ * joins the same query the logger's lines answer. The remote PARENT is
+ * deliberately not reconstructed: `UnitMeta.traceId` carries the inbound trace
+ * id alone, so this correlates by attribute rather than pretending to a W3C
+ * parent-child edge it cannot prove.
+ *
+ * Compose it as `start`'s `unit`; the root must export `Tracer`.
+ */
+declare const UnitSpanModule: Module<UnitSpan, never, Scope | Tracer>;
+//#endregion
+export { UnitSpan, UnitSpanModule, otel };

package/dist/otel.d.mts

@@ -0,0 +1,38 @@
+import { Meter, Span, Tracer } from "@btravstack/core";
+import { Module, Scope } from "@btravstack/di";
+import { NodeSDKConfiguration } from "@opentelemetry/sdk-node";
+//#region src/otel.d.ts
+/**
+ * The OTel starter: a module providing `Tracer` and `Meter` over a `NodeSDK`
+ * opened with the scope and flushed on close. Compose it beside
+ * `observability()` in a root's `imports`.
+ *
+ * **No config slice, deliberately**: the SDK reads the `OTEL_*` environment
+ * conventions itself, and re-binding them through `Config` would be a second
+ * spelling of names operators already know. Programmatic overrides go through
+ * `options`, the SDK's own configuration type.
+ *
+ * **Auto-instrumentation cannot live here**: the register hook must be
+ * preloaded before the instrumented libraries are imported, which no DI
+ * provider can promise. Preloading is the deployment's line.
+ */
+declare const otel: (options?: Partial<NodeSDKConfiguration>) => Module<Tracer | Meter, never, Scope>;
+declare const UnitSpan_base: import("@btravstack/di").PortClass<"UnitSpan">;
+/** The span a unit rides, ended when the unit's fork closes. */
+declare class UnitSpan extends UnitSpan_base<Span> {}
+/**
+ * A span per kernel unit, as a `StartOptions.unit` module: the kernel forks it
+ * per unit and tears it down inside the unit's ambient record, so the span opens
+ * when the unit does and `onStop` ends it on every path out.
+ *
+ * The correlation is the ambient record's own, carried as attributes so a span
+ * joins the same query the logger's lines answer. The remote PARENT is
+ * deliberately not reconstructed: `UnitMeta.traceId` carries the inbound trace
+ * id alone, so this correlates by attribute rather than pretending to a W3C
+ * parent-child edge it cannot prove.
+ *
+ * Compose it as `start`'s `unit`; the root must export `Tracer`.
+ */
+declare const UnitSpanModule: Module<UnitSpan, never, Scope | Tracer>;
+//#endregion
+export { UnitSpan, UnitSpanModule, otel };

package/dist/otel.mjs

@@ -0,0 +1,87 @@
+import { Meter, Tracer, currentUnit } from "@btravstack/core";
+import { Ok } from "unthrown";
+import { Module, Port, Provider } from "@btravstack/di";
+import { metrics, trace } from "@opentelemetry/api";
+import { NodeSDK } from "@opentelemetry/sdk-node";
+//#region src/otel.ts
+/**
+* The tracing half of observability — the ADAPTER, not the contract. `Tracer`
+* and `Meter` are the kernel's ports, and OTel's presence stops at this subpath,
+* behind an optional peer exactly like `pino`.
+*
+* The ports are narrowings of OTel's own shapes, so what the SDK hands back
+* satisfies them with no translation in between.
+*/
+/**
+* The SDK itself, module-private: providing it is what starts it, and `release`
+* is what flushes it. It rides the graph as a RESOURCE so the kernel closes it
+* on every exit path — a span lost in `shutdown()` becomes a `teardownError` and
+* exit `2`, never silence.
+*/
+var OtelSdk = class extends Port("OtelSdk") {};
+/**
+* The OTel starter: a module providing `Tracer` and `Meter` over a `NodeSDK`
+* opened with the scope and flushed on close. Compose it beside
+* `observability()` in a root's `imports`.
+*
+* **No config slice, deliberately**: the SDK reads the `OTEL_*` environment
+* conventions itself, and re-binding them through `Config` would be a second
+* spelling of names operators already know. Programmatic overrides go through
+* `options`, the SDK's own configuration type.
+*
+* **Auto-instrumentation cannot live here**: the register hook must be
+* preloaded before the instrumented libraries are imported, which no DI
+* provider can promise. Preloading is the deployment's line.
+*/
+const otel = (options) => Module("Otel")({
+	provides: [
+		Provider(OtelSdk)({
+			acquire: () => {
+				const sdk = new NodeSDK(options);
+				sdk.start();
+				return Ok(sdk);
+			},
+			release: (sdk) => sdk.shutdown()
+		}),
+		Provider(Tracer)({ sdk: OtelSdk }, { sync: () => {
+			const tracer = trace.getTracer("@btravstack/observability");
+			return { startSpan: (name) => tracer.startSpan(name) };
+		} }),
+		Provider(Meter)({ sdk: OtelSdk }, { sync: () => metrics.getMeter("@btravstack/observability") })
+	],
+	exports: [Tracer, Meter]
+});
+/** The span a unit rides, ended when the unit's fork closes. */
+var UnitSpan = class extends Port("UnitSpan") {};
+/**
+* A span per kernel unit, as a `StartOptions.unit` module: the kernel forks it
+* per unit and tears it down inside the unit's ambient record, so the span opens
+* when the unit does and `onStop` ends it on every path out.
+*
+* The correlation is the ambient record's own, carried as attributes so a span
+* joins the same query the logger's lines answer. The remote PARENT is
+* deliberately not reconstructed: `UnitMeta.traceId` carries the inbound trace
+* id alone, so this correlates by attribute rather than pretending to a W3C
+* parent-child edge it cannot prove.
+*
+* Compose it as `start`'s `unit`; the root must export `Tracer`.
+*/
+const UnitSpanModule = Module("UnitSpan")({
+	needs: [Tracer],
+	provides: [Provider(UnitSpan)({ tracer: Tracer }, {
+		sync: ({ tracer }) => {
+			const unit = currentUnit();
+			const span = tracer.startSpan("unit");
+			if (unit !== void 0) span.setAttributes({
+				"btravstack.unit_id": unit.unitId,
+				"btravstack.trace_id": unit.traceId,
+				...unit.tenantId === void 0 ? {} : { "btravstack.tenant_id": unit.tenantId }
+			});
+			return span;
+		},
+		onStop: (span) => span.end()
+	})],
+	exports: [UnitSpan]
+});
+//#endregion
+export { UnitSpan, UnitSpanModule, otel };

package/dist/pino.cjs

@@ -0,0 +1,34 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/pino.ts
+/**
+* A {@link Sink} over a pino logger — the subpath a deployment reaches for
+* when the default JSON sink's `JSON.stringify` per line is the thing showing
+* up in a profile. `pino` is an **optional** peer: install it, import
+* `@btravstack/observability/pino`, and pass the sink; a consumer that never
+* imports this file never needs it.
+*
+* ```ts
+* import pino from "pino";
+* import { observability } from "@btravstack/observability";
+* import { pinoSink } from "@btravstack/observability/pino";
+*
+* observability({ sink: pinoSink(pino()) });
+* ```
+*
+* The level filter stays **ours**: `createLogger` has already decided the
+* line is worth writing by the time a sink sees it, so pino is configured at
+* `trace` here — one filter in the process, and it is the one `LOG_LEVEL`
+* validated at startup. `fatal` and `trace` map to pino's own; the ambient
+* unit's ids ride as fields, not as a message prefix, so they stay indexable.
+*/
+const pinoSink = (logger) => (line) => {
+	const { level, message, attributes, cause, unit } = line;
+	const fields = {
+		...attributes,
+		...unit === void 0 ? {} : unit,
+		...cause === void 0 ? {} : { err: cause }
+	};
+	logger[level](fields, message);
+};
+//#endregion
+exports.pinoSink = pinoSink;

package/dist/pino.d.cts

@@ -0,0 +1,27 @@
+import { n as Sink } from "./logger-B1-_76ej.cjs";
+import { Logger } from "pino";
+//#region src/pino.d.ts
+/**
+ * A {@link Sink} over a pino logger — the subpath a deployment reaches for
+ * when the default JSON sink's `JSON.stringify` per line is the thing showing
+ * up in a profile. `pino` is an **optional** peer: install it, import
+ * `@btravstack/observability/pino`, and pass the sink; a consumer that never
+ * imports this file never needs it.
+ *
+ * ```ts
+ * import pino from "pino";
+ * import { observability } from "@btravstack/observability";
+ * import { pinoSink } from "@btravstack/observability/pino";
+ *
+ * observability({ sink: pinoSink(pino()) });
+ * ```
+ *
+ * The level filter stays **ours**: `createLogger` has already decided the
+ * line is worth writing by the time a sink sees it, so pino is configured at
+ * `trace` here — one filter in the process, and it is the one `LOG_LEVEL`
+ * validated at startup. `fatal` and `trace` map to pino's own; the ambient
+ * unit's ids ride as fields, not as a message prefix, so they stay indexable.
+ */
+declare const pinoSink: (logger: Logger) => Sink;
+//#endregion
+export { pinoSink };

package/dist/pino.d.mts

@@ -0,0 +1,27 @@
+import { n as Sink } from "./logger-B1-_76ej.mjs";
+import { Logger } from "pino";
+//#region src/pino.d.ts
+/**
+ * A {@link Sink} over a pino logger — the subpath a deployment reaches for
+ * when the default JSON sink's `JSON.stringify` per line is the thing showing
+ * up in a profile. `pino` is an **optional** peer: install it, import
+ * `@btravstack/observability/pino`, and pass the sink; a consumer that never
+ * imports this file never needs it.
+ *
+ * ```ts
+ * import pino from "pino";
+ * import { observability } from "@btravstack/observability";
+ * import { pinoSink } from "@btravstack/observability/pino";
+ *
+ * observability({ sink: pinoSink(pino()) });
+ * ```
+ *
+ * The level filter stays **ours**: `createLogger` has already decided the
+ * line is worth writing by the time a sink sees it, so pino is configured at
+ * `trace` here — one filter in the process, and it is the one `LOG_LEVEL`
+ * validated at startup. `fatal` and `trace` map to pino's own; the ambient
+ * unit's ids ride as fields, not as a message prefix, so they stay indexable.
+ */
+declare const pinoSink: (logger: Logger) => Sink;
+//#endregion
+export { pinoSink };

package/dist/pino.mjs

@@ -0,0 +1,33 @@
+//#region src/pino.ts
+/**
+* A {@link Sink} over a pino logger — the subpath a deployment reaches for
+* when the default JSON sink's `JSON.stringify` per line is the thing showing
+* up in a profile. `pino` is an **optional** peer: install it, import
+* `@btravstack/observability/pino`, and pass the sink; a consumer that never
+* imports this file never needs it.
+*
+* ```ts
+* import pino from "pino";
+* import { observability } from "@btravstack/observability";
+* import { pinoSink } from "@btravstack/observability/pino";
+*
+* observability({ sink: pinoSink(pino()) });
+* ```
+*
+* The level filter stays **ours**: `createLogger` has already decided the
+* line is worth writing by the time a sink sees it, so pino is configured at
+* `trace` here — one filter in the process, and it is the one `LOG_LEVEL`
+* validated at startup. `fatal` and `trace` map to pino's own; the ambient
+* unit's ids ride as fields, not as a message prefix, so they stay indexable.
+*/
+const pinoSink = (logger) => (line) => {
+	const { level, message, attributes, cause, unit } = line;
+	const fields = {
+		...attributes,
+		...unit === void 0 ? {} : unit,
+		...cause === void 0 ? {} : { err: cause }
+	};
+	logger[level](fields, message);
+};
+//#endregion
+export { pinoSink };

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "@btravstack/observability",
+  "version": "0.3.0",
+  "description": "Observability for @btravstack/core: a strict Logger port correlated with the kernel's units, a dependency-free JSON sink, and the lifecycle events as log lines",
+  "keywords": [
+    "dependency-injection",
+    "logger",
+    "logging",
+    "observability",
+    "opentelemetry",
+    "structured-logging",
+    "typescript",
+    "unthrown"
+  ],
+  "homepage": "https://github.com/btravstack/btravstack#readme",
+  "bugs": {
+    "url": "https://github.com/btravstack/btravstack/issues"
+  },
+  "license": "MIT",
+  "author": "Benoit TRAVERS <benoit.travers.fr@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/btravstack/btravstack.git",
+    "directory": "packages/observability"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./pino": {
+      "import": {
+        "types": "./dist/pino.d.mts",
+        "default": "./dist/pino.mjs"
+      },
+      "require": {
+        "types": "./dist/pino.d.cts",
+        "default": "./dist/pino.cjs"
+      }
+    },
+    "./otel": {
+      "import": {
+        "types": "./dist/otel.d.mts",
+        "default": "./dist/otel.mjs"
+      },
+      "require": {
+        "types": "./dist/otel.d.cts",
+        "default": "./dist/otel.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@btravstack/tsconfig": "0.2.0",
+    "@opentelemetry/api": "1.9.1",
+    "@opentelemetry/sdk-node": "0.221.0",
+    "@opentelemetry/sdk-trace": "2.10.0",
+    "@types/node": "26.2.0",
+    "@unthrown/vitest": "5.7.0",
+    "@vitest/coverage-v8": "4.1.11",
+    "pino": "10.3.1",
+    "tsdown": "0.22.14",
+    "typescript": "7.0.2",
+    "unthrown": "5.7.0",
+    "vitest": "4.1.11",
+    "@btravstack/config": "0.3.0",
+    "@btravstack/di": "0.3.0",
+    "@btravstack/testing": "0.3.0",
+    "@btravstack/core": "0.3.0"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-node": "^0.221.0",
+    "pino": "^10",
+    "unthrown": "^5.0.0",
+    "@btravstack/config": "^0.3.0",
+    "@btravstack/core": "^0.3.0",
+    "@btravstack/di": "^0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-node": {
+      "optional": true
+    },
+    "pino": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts src/pino.ts src/otel.ts --format cjs,esm --dts --clean",
+    "dev": "tsdown src/index.ts src/pino.ts --format cjs,esm --dts --watch",
+    "test": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}