@btravstack/observability 0.17.0 → 0.19.0

package/dist/index.cjs

@@ -60,15 +60,22 @@ const jsonSink = (stream = process.stdout) => (line) => {
 	};
 	stream.write(`${safeStringify(rendered)}\n`);
 };
+const serialises = (key, value) => {
+	try {
+		JSON.stringify({ [key]: value });
+		return true;
+	} catch {
+		return false;
+	}
+};
 const safeStringify = (rendered) => {
 	try {
 		return JSON.stringify(rendered);
 	} catch {
+		const kept = Object.entries(rendered).filter(([key, value]) => serialises(key, value));
 		return JSON.stringify({
-			time: rendered["time"],
-			level: rendered["level"],
-			message: rendered["message"],
-			cause: "[unserialisable]"
+			...Object.fromEntries(kept),
+			unserialisable: Object.keys(rendered).filter((key) => !serialises(key, rendered[key]))
 		});
 	}
 };

package/dist/index.mjs

@@ -59,15 +59,22 @@ const jsonSink = (stream = process.stdout) => (line) => {
 	};
 	stream.write(`${safeStringify(rendered)}\n`);
 };
+const serialises = (key, value) => {
+	try {
+		JSON.stringify({ [key]: value });
+		return true;
+	} catch {
+		return false;
+	}
+};
 const safeStringify = (rendered) => {
 	try {
 		return JSON.stringify(rendered);
 	} catch {
+		const kept = Object.entries(rendered).filter(([key, value]) => serialises(key, value));
 		return JSON.stringify({
-			time: rendered["time"],
-			level: rendered["level"],
-			message: rendered["message"],
-			cause: "[unserialisable]"
+			...Object.fromEntries(kept),
+			unserialisable: Object.keys(rendered).filter((key) => !serialises(key, rendered[key]))
 		});
 	}
 };

package/dist/otel.cjs

@@ -7,6 +7,38 @@ let unthrown = require("unthrown");
 //#region src/otel.ts
 var OtelSdk = class extends (0, _btravstack_di.Port)("OtelSdk") {};
 /**
+* OTel semantic conventions' duration buckets, in seconds. The SDK's default
+* boundaries were drawn for milliseconds and would put every operation under a
+* second into the first bucket.
+*/
+const SECONDS_BUCKETS = [
+	.005,
+	.01,
+	.025,
+	.05,
+	.075,
+	.1,
+	.25,
+	.5,
+	.75,
+	1,
+	2.5,
+	5,
+	7.5,
+	10
+];
+/**
+* Each open unit's span, by the record it was opened for — so an operation
+* inside the unit parents on it while the observer still injects nothing.
+* Weak, so an ended unit costs nothing once its record is gone.
+*/
+const unitSpans = /* @__PURE__ */ new WeakMap();
+const unitAttributes = (unit) => unit === void 0 ? {} : {
+	"btravstack.unit_id": unit.unitId,
+	"btravstack.trace_id": unit.traceId,
+	...unit.tenantId === void 0 ? {} : { "btravstack.tenant_id": unit.tenantId }
+};
+/**
 * 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`.
@@ -54,16 +86,25 @@ const otel = (options) => (0, _btravstack_di.Module)("Otel")({
 				};
 				return ({ component, name, attributes, details, traced }) => {
 					const meter = _opentelemetry_api.metrics.getMeter("@btravstack/observability");
-					const span = traced === false ? void 0 : tracer.startSpan(`${component}.${name}`);
-					span?.setAttributes({
-						...attributes,
-						...details
-					});
+					const unit = (0, _btravstack_core.currentUnit)();
 					const startedAt = performance.now();
+					const open = (startTime) => {
+						const parent = unit === void 0 ? void 0 : unitSpans.get(unit);
+						const opened = tracer.startSpan(`${component}.${name}`, startTime === void 0 ? {} : { startTime }, parent === void 0 ? void 0 : _opentelemetry_api.trace.setSpan(_opentelemetry_api.context.active(), parent));
+						opened.setAttributes({
+							...attributes,
+							...details,
+							...unitAttributes(unit)
+						});
+						return opened;
+					};
+					const deferred = traced !== false && unit !== void 0 && !unitSpans.has(unit);
+					const started = traced === false || deferred ? void 0 : open();
 					const operations = instrument(counters, component, () => meter.createCounter(`btravstack.${component}.operations`, { description: `${component} operations, by operation and outcome` }));
 					const duration = instrument(durations, component, () => meter.createHistogram(`btravstack.${component}.duration`, {
 						description: `${component} operation duration`,
-						unit: "ms"
+						unit: "s",
+						advice: { explicitBucketBoundaries: SECONDS_BUCKETS }
 					}));
 					return ({ outcome, attributes: settled }) => {
 						const all = {
@@ -72,9 +113,15 @@ const otel = (options) => (0, _btravstack_di.Module)("Otel")({
 							outcome
 						};
 						operations.add(1, all);
-						duration.record(performance.now() - startedAt, all);
-						if (outcome === "error") span?.setStatus({ code: _btravstack_core.SPAN_STATUS.error });
-						span?.end();
+						const endedAt = performance.now();
+						duration.record((endedAt - startedAt) / 1e3, all);
+						const finish = (span) => {
+							if (outcome === "error") span?.setStatus({ code: _btravstack_core.SPAN_STATUS.error });
+							span?.end(endedAt);
+						};
+						if (!deferred) finish(started);
+						else if (unitSpans.has(unit)) finish(open(startedAt));
+						else queueMicrotask(() => finish(open(startedAt)));
 					};
 				};
 			}
@@ -114,7 +161,9 @@ var UnitSpan = class extends (0, _btravstack_di.Port)("UnitSpan") {};
 * 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
+* joins the same query the logger's lines answer. Every operation observed
+* inside the unit — a cache read, a stored object, a sent mail — is this
+* span's CHILD and carries the same attributes. 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.
@@ -129,14 +178,19 @@ const UnitSpanModule = (0, _btravstack_di.Module)("UnitSpan")({
 		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 }
-			});
+			span.setAttributes(unitAttributes(unit));
+			if (unit !== void 0 && "spanContext" in span) unitSpans.set(unit, span);
 			return span;
 		},
-		onStop: (span) => span.end()
+		onStop: (span) => {
+			const unit = (0, _btravstack_core.currentUnit)();
+			if (unit?.signal.aborted === true) span.setStatus({
+				code: _btravstack_core.SPAN_STATUS.error,
+				message: "aborted"
+			});
+			else if (unit !== void 0 && (0, _btravstack_core.unitOutcome)() !== "ok") span.setStatus({ code: _btravstack_core.SPAN_STATUS.error });
+			span.end();
+		}
 	})],
 	exports: [UnitSpan]
 });

package/dist/otel.d.cts

@@ -39,7 +39,9 @@ export declare class UnitSpan extends UnitSpan_base<Span> {}
  * 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
+ * joins the same query the logger's lines answer. Every operation observed
+ * inside the unit — a cache read, a stored object, a sent mail — is this
+ * span's CHILD and carries the same attributes. 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.

package/dist/otel.d.mts

@@ -39,7 +39,9 @@ export declare class UnitSpan extends UnitSpan_base<Span> {}
  * 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
+ * joins the same query the logger's lines answer. Every operation observed
+ * inside the unit — a cache read, a stored object, a sent mail — is this
+ * span's CHILD and carries the same attributes. 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.

package/dist/otel.mjs

@@ -1,11 +1,43 @@
-import { Instrumentations, Meter, Observers, SPAN_STATUS, Tracer, currentUnit } from "@btravstack/core";
+import { Instrumentations, Meter, Observers, SPAN_STATUS, Tracer, currentUnit, unitOutcome } from "@btravstack/core";
 import { Module, Port, Provider } from "@btravstack/di";
-import { metrics, trace } from "@opentelemetry/api";
+import { context, metrics, trace } from "@opentelemetry/api";
 import { NodeSDK } from "@opentelemetry/sdk-node";
 import { fromSafePromise } from "unthrown";
 //#region src/otel.ts
 var OtelSdk = class extends Port("OtelSdk") {};
 /**
+* OTel semantic conventions' duration buckets, in seconds. The SDK's default
+* boundaries were drawn for milliseconds and would put every operation under a
+* second into the first bucket.
+*/
+const SECONDS_BUCKETS = [
+	.005,
+	.01,
+	.025,
+	.05,
+	.075,
+	.1,
+	.25,
+	.5,
+	.75,
+	1,
+	2.5,
+	5,
+	7.5,
+	10
+];
+/**
+* Each open unit's span, by the record it was opened for — so an operation
+* inside the unit parents on it while the observer still injects nothing.
+* Weak, so an ended unit costs nothing once its record is gone.
+*/
+const unitSpans = /* @__PURE__ */ new WeakMap();
+const unitAttributes = (unit) => unit === void 0 ? {} : {
+	"btravstack.unit_id": unit.unitId,
+	"btravstack.trace_id": unit.traceId,
+	...unit.tenantId === void 0 ? {} : { "btravstack.tenant_id": unit.tenantId }
+};
+/**
 * 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`.
@@ -53,16 +85,25 @@ const otel = (options) => Module("Otel")({
 				};
 				return ({ component, name, attributes, details, traced }) => {
 					const meter = metrics.getMeter("@btravstack/observability");
-					const span = traced === false ? void 0 : tracer.startSpan(`${component}.${name}`);
-					span?.setAttributes({
-						...attributes,
-						...details
-					});
+					const unit = currentUnit();
 					const startedAt = performance.now();
+					const open = (startTime) => {
+						const parent = unit === void 0 ? void 0 : unitSpans.get(unit);
+						const opened = tracer.startSpan(`${component}.${name}`, startTime === void 0 ? {} : { startTime }, parent === void 0 ? void 0 : trace.setSpan(context.active(), parent));
+						opened.setAttributes({
+							...attributes,
+							...details,
+							...unitAttributes(unit)
+						});
+						return opened;
+					};
+					const deferred = traced !== false && unit !== void 0 && !unitSpans.has(unit);
+					const started = traced === false || deferred ? void 0 : open();
 					const operations = instrument(counters, component, () => meter.createCounter(`btravstack.${component}.operations`, { description: `${component} operations, by operation and outcome` }));
 					const duration = instrument(durations, component, () => meter.createHistogram(`btravstack.${component}.duration`, {
 						description: `${component} operation duration`,
-						unit: "ms"
+						unit: "s",
+						advice: { explicitBucketBoundaries: SECONDS_BUCKETS }
 					}));
 					return ({ outcome, attributes: settled }) => {
 						const all = {
@@ -71,9 +112,15 @@ const otel = (options) => Module("Otel")({
 							outcome
 						};
 						operations.add(1, all);
-						duration.record(performance.now() - startedAt, all);
-						if (outcome === "error") span?.setStatus({ code: SPAN_STATUS.error });
-						span?.end();
+						const endedAt = performance.now();
+						duration.record((endedAt - startedAt) / 1e3, all);
+						const finish = (span) => {
+							if (outcome === "error") span?.setStatus({ code: SPAN_STATUS.error });
+							span?.end(endedAt);
+						};
+						if (!deferred) finish(started);
+						else if (unitSpans.has(unit)) finish(open(startedAt));
+						else queueMicrotask(() => finish(open(startedAt)));
 					};
 				};
 			}
@@ -113,7 +160,9 @@ var UnitSpan = class extends Port("UnitSpan") {};
 * 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
+* joins the same query the logger's lines answer. Every operation observed
+* inside the unit — a cache read, a stored object, a sent mail — is this
+* span's CHILD and carries the same attributes. 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.
@@ -128,14 +177,19 @@ const UnitSpanModule = Module("UnitSpan")({
 		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 }
-			});
+			span.setAttributes(unitAttributes(unit));
+			if (unit !== void 0 && "spanContext" in span) unitSpans.set(unit, span);
 			return span;
 		},
-		onStop: (span) => span.end()
+		onStop: (span) => {
+			const unit = currentUnit();
+			if (unit?.signal.aborted === true) span.setStatus({
+				code: SPAN_STATUS.error,
+				message: "aborted"
+			});
+			else if (unit !== void 0 && unitOutcome() !== "ok") span.setStatus({ code: SPAN_STATUS.error });
+			span.end();
+		}
 	})],
 	exports: [UnitSpan]
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/observability",
-  "version": "0.17.0",
+  "version": "0.19.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,10 +65,10 @@
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@btravstack/config": "0.17.0",
-    "@btravstack/core": "0.17.0",
-    "@btravstack/di": "0.17.0",
-    "@btravstack/testing": "0.17.0",
+    "@btravstack/config": "0.19.0",
+    "@btravstack/core": "0.19.0",
+    "@btravstack/di": "0.19.0",
+    "@btravstack/testing": "0.19.0",
     "@btravstack/tsconfig": "0.4.0",
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/sdk-node": "0.222.0",
@@ -83,9 +83,9 @@
     "vitest": "5.0.3"
   },
   "peerDependencies": {
-    "@btravstack/config": "^0.17.0",
-    "@btravstack/core": "^0.17.0",
-    "@btravstack/di": "^0.17.0",
+    "@btravstack/config": "^0.19.0",
+    "@btravstack/core": "^0.19.0",
+    "@btravstack/di": "^0.19.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/sdk-node": "^0.222.0",
     "pino": "^10",