@btravstack/observability 0.12.0 → 0.14.0

package/README.md

@@ -154,8 +154,10 @@ import { UnitSpanModule, otel } from "@btravstack/observability/otel";
 // 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 })
+// A span per unit, correlated with the same ids the logger stamps — bound on
+// the starter's own `unit` option and forked by the runtime around each
+// request, delivery or activity attempt, e.g.
+// http({ unit: { anonymous: UnitSpanModule } })
 ```
 
 Inbound W3C `traceparent` feeds the unit's trace id in `@btravstack/http-server` and

package/dist/index.d.cts

@@ -13,7 +13,7 @@ import { Module } from "@btravstack/di";
  * `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?: {
+export declare const logLevel: (options?: {
   readonly default?: Level;
 }) => ConfigField<Level>;
 /** What `observability()` binds from the environment. */
@@ -32,7 +32,7 @@ type LoggerSettings = {
  * 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?: {
+export declare const jsonSink: (stream?: {
   readonly write: (chunk: string) => unknown;
 }) => Sink;
 //#endregion
@@ -43,7 +43,7 @@ declare const LoggerConfig_base: import("@btravstack/di").PortClass<"LoggerConfi
  * 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> {}
+export declare class LoggerConfig extends LoggerConfig_base<LoggerSettings> {}
 type ObservabilityOptions = {
   /**
    * Where lines go. Default: one JSON object per line on `stdout`. The
@@ -63,7 +63,7 @@ type ObservabilityOptions = {
  * `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 | Observers, ConfigInvalid, Env>;
+export declare const observability: (options?: ObservabilityOptions) => Module<Logger | LoggerConfig | Observers, ConfigInvalid, Env>;
 /**
  * The kernel's nine lifecycle events, as log lines on `logger` — the adapter
  * between `StartOptions.onEvent` and an application's own stream.
@@ -76,6 +76,6 @@ declare const observability: (options?: ObservabilityOptions) => Module<Logger |
  * 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;
+export declare const kernelEvents: (logger: LoggerService) => EventSink;
 //#endregion
-export { type Line, LoggerConfig, type LoggerSettings, type ObservabilityOptions, type Sink, createLogger, jsonSink, kernelEvents, logLevel, observability };
+export { type Line, type LoggerSettings, type ObservabilityOptions, type Sink, createLogger };

package/dist/index.d.mts

@@ -13,7 +13,7 @@ import { Module } from "@btravstack/di";
  * `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?: {
+export declare const logLevel: (options?: {
   readonly default?: Level;
 }) => ConfigField<Level>;
 /** What `observability()` binds from the environment. */
@@ -32,7 +32,7 @@ type LoggerSettings = {
  * 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?: {
+export declare const jsonSink: (stream?: {
   readonly write: (chunk: string) => unknown;
 }) => Sink;
 //#endregion
@@ -43,7 +43,7 @@ declare const LoggerConfig_base: import("@btravstack/di").PortClass<"LoggerConfi
  * 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> {}
+export declare class LoggerConfig extends LoggerConfig_base<LoggerSettings> {}
 type ObservabilityOptions = {
   /**
    * Where lines go. Default: one JSON object per line on `stdout`. The
@@ -63,7 +63,7 @@ type ObservabilityOptions = {
  * `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 | Observers, ConfigInvalid, Env>;
+export declare const observability: (options?: ObservabilityOptions) => Module<Logger | LoggerConfig | Observers, ConfigInvalid, Env>;
 /**
  * The kernel's nine lifecycle events, as log lines on `logger` — the adapter
  * between `StartOptions.onEvent` and an application's own stream.
@@ -76,6 +76,6 @@ declare const observability: (options?: ObservabilityOptions) => Module<Logger |
  * 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;
+export declare const kernelEvents: (logger: LoggerService) => EventSink;
 //#endregion
-export { type Line, LoggerConfig, type LoggerSettings, type ObservabilityOptions, type Sink, createLogger, jsonSink, kernelEvents, logLevel, observability };
+export { type Line, type LoggerSettings, type ObservabilityOptions, type Sink, createLogger };

package/dist/otel.cjs

@@ -112,9 +112,9 @@ const otel = (options) => (0, _btravstack_di.Module)("Otel")({
 /** 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.
+* A span per unit, as a module a starter's own `unit` option binds: the runtime
+* forks it around every unit it opens, so the span opens when the fork is built
+* 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
@@ -122,7 +122,8 @@ var UnitSpan = class extends (0, _btravstack_di.Port)("UnitSpan") {};
 * 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`.
+* Bind it as a starter's `unit` module — `unit: { anonymous: UnitSpanModule }`,
+* `unit: { message: … }`, `unit: { activity: … }`; the root must export `Tracer`.
 */
 const UnitSpanModule = (0, _btravstack_di.Module)("UnitSpan")({
 	needs: [_btravstack_core.Tracer],

package/dist/otel.d.cts

@@ -29,14 +29,14 @@ import { NodeSDKConfiguration } from "@opentelemetry/sdk-node";
  * plan time and in `Needs`. Guice's `newSetBinder` declares the empty set for
  * the same reason.
  */
-declare const otel: (options?: Partial<NodeSDKConfiguration>) => Module<Tracer | Meter | Observers, never, Scope>;
+export declare const otel: (options?: Partial<NodeSDKConfiguration>) => Module<Tracer | Meter | Observers, 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> {}
+export 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.
+ * A span per unit, as a module a starter's own `unit` option binds: the runtime
+ * forks it around every unit it opens, so the span opens when the fork is built
+ * 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
@@ -44,8 +44,8 @@ declare class UnitSpan extends UnitSpan_base<Span> {}
  * 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`.
+ * Bind it as a starter's `unit` module — `unit: { anonymous: UnitSpanModule }`,
+ * `unit: { message: … }`, `unit: { activity: … }`; the root must export `Tracer`.
  */
-declare const UnitSpanModule: Module<UnitSpan, never, Scope | Tracer>;
-//#endregion
-export { UnitSpan, UnitSpanModule, otel };
+export declare const UnitSpanModule: Module<UnitSpan, never, Scope | Tracer>;
+//#endregion

package/dist/otel.d.mts

@@ -29,14 +29,14 @@ import { NodeSDKConfiguration } from "@opentelemetry/sdk-node";
  * plan time and in `Needs`. Guice's `newSetBinder` declares the empty set for
  * the same reason.
  */
-declare const otel: (options?: Partial<NodeSDKConfiguration>) => Module<Tracer | Meter | Observers, never, Scope>;
+export declare const otel: (options?: Partial<NodeSDKConfiguration>) => Module<Tracer | Meter | Observers, 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> {}
+export 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.
+ * A span per unit, as a module a starter's own `unit` option binds: the runtime
+ * forks it around every unit it opens, so the span opens when the fork is built
+ * 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
@@ -44,8 +44,8 @@ declare class UnitSpan extends UnitSpan_base<Span> {}
  * 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`.
+ * Bind it as a starter's `unit` module — `unit: { anonymous: UnitSpanModule }`,
+ * `unit: { message: … }`, `unit: { activity: … }`; the root must export `Tracer`.
  */
-declare const UnitSpanModule: Module<UnitSpan, never, Scope | Tracer>;
-//#endregion
-export { UnitSpan, UnitSpanModule, otel };
+export declare const UnitSpanModule: Module<UnitSpan, never, Scope | Tracer>;
+//#endregion

package/dist/otel.mjs

@@ -111,9 +111,9 @@ const otel = (options) => Module("Otel")({
 /** 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.
+* A span per unit, as a module a starter's own `unit` option binds: the runtime
+* forks it around every unit it opens, so the span opens when the fork is built
+* 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
@@ -121,7 +121,8 @@ var UnitSpan = class extends Port("UnitSpan") {};
 * 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`.
+* Bind it as a starter's `unit` module — `unit: { anonymous: UnitSpanModule }`,
+* `unit: { message: … }`, `unit: { activity: … }`; the root must export `Tracer`.
 */
 const UnitSpanModule = Module("UnitSpan")({
 	needs: [Tracer],

package/dist/pino.d.cts

@@ -22,6 +22,5 @@ import { Logger } from "pino";
  * 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 };
+export declare const pinoSink: (logger: Logger) => Sink;
+//#endregion

package/dist/pino.d.mts

@@ -22,6 +22,5 @@ import { Logger } from "pino";
  * 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 };
+export declare const pinoSink: (logger: Logger) => Sink;
+//#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/observability",
-  "version": "0.12.0",
+  "version": "0.14.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",
@@ -65,31 +65,31 @@
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@btravstack/tsconfig": "0.2.0",
+    "@btravstack/tsconfig": "0.4.0",
     "@opentelemetry/api": "1.9.1",
-    "@opentelemetry/sdk-node": "0.221.0",
-    "@opentelemetry/sdk-trace": "2.10.0",
-    "@types/node": "26.4.0",
-    "@unthrown/vitest": "5.7.0",
+    "@opentelemetry/sdk-node": "0.222.0",
+    "@opentelemetry/sdk-trace": "2.11.0",
+    "@types/node": "26.4.1",
+    "@unthrown/vitest": "5.8.0",
     "@vitest/coverage-v8": "4.1.11",
     "pino": "10.3.1",
-    "tsdown": "0.22.14",
+    "tsdown": "0.23.0",
     "typescript": "7.0.2",
-    "unthrown": "5.7.0",
+    "unthrown": "5.8.0",
     "vitest": "4.1.11",
-    "@btravstack/config": "0.12.0",
-    "@btravstack/core": "0.12.0",
-    "@btravstack/di": "0.12.0",
-    "@btravstack/testing": "0.12.0"
+    "@btravstack/config": "0.14.0",
+    "@btravstack/core": "0.14.0",
+    "@btravstack/di": "0.14.0",
+    "@btravstack/testing": "0.14.0"
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/sdk-node": "^0.221.0",
     "pino": "^10",
     "unthrown": "^5.0.0",
-    "@btravstack/config": "^0.12.0",
-    "@btravstack/core": "^0.12.0",
-    "@btravstack/di": "^0.12.0"
+    "@btravstack/config": "^0.14.0",
+    "@btravstack/core": "^0.14.0",
+    "@btravstack/di": "^0.14.0"
   },
   "peerDependenciesMeta": {
     "@opentelemetry/api": {