@storyshelf/observability 0.0.0-stage → 0.5.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Siddhant Gupta
+
+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

@@ -1,3 +1,30 @@
-# Temporary Holding Version
+# @storyshelf/observability
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+OpenTelemetry tracing, metrics, and log correlation for StoryShelf adapters. This is the single OTEL owner in the monorepo.
+
+## Install
+
+```sh
+nub add @storyshelf/observability
+```
+
+or
+
+```sh
+npm install @storyshelf/observability
+```
+
+## Usage
+
+```ts
+import { createInstrumentedDatabase, createInstrumentedStorage } from "@storyshelf/observability";
+
+const database = createInstrumentedDatabase(baseDatabase);
+const storage = createInstrumentedStorage(baseStorage);
+```
+
+See the [StoryShelf documentation](https://github.com/GuptaSiddhant/StoryShelf#readme) for configuration details.
+
+## License
+
+MIT

package/dist/config.d.mts

@@ -0,0 +1,38 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/config.d.ts
+/**
+ * Environment-driven observability configuration.
+ *
+ * Standard `OTEL_*` variables win; `STORYSHELF_OTEL_*` covers StoryShelf
+ * specifics. When `OTEL_EXPORTER_OTLP_ENDPOINT` is unset the SDK stays a
+ * noop (zero overhead, hermetic tests). Deno runtimes are always noop here —
+ * Deno's built-in OTEL (`OTEL_DENO=true`) bridges `npm:@opentelemetry/api`
+ * natively, so a NodeSDK must never start under Deno.
+ */
+/** Resolved observability configuration for the Node SDK entrypoint. */
+interface ObservabilityConfig {
+  /** Whether to start the SDK (false = noop handle). */
+  enabled: boolean;
+  /** OTLP/HTTP endpoint, e.g. `http://collector:4318`. */
+  endpoint?: string;
+  /** Extra OTLP headers (`OTEL_EXPORTER_OTLP_HEADERS`, `k=v,k2=v2`). */
+  headers?: Record<string, string>;
+  /** Resource `service.name`. */
+  serviceName: string;
+  /** Resource `service.version`. */
+  serviceVersion?: string;
+  /** Metric export interval in milliseconds. */
+  metricsIntervalMs: number;
+}
+/**
+ * Resolve the observability configuration from the environment.
+ *
+ * @param env - Environment record (defaults to `process.env`).
+ * @param serviceVersion - Version for the resource (defaults to `__PKG_VERSION__`).
+ * @returns The resolved config; `enabled` is false without an endpoint.
+ */
+declare function resolveObservabilityConfig(env?: NodeJS.ProcessEnv, serviceVersion?: string): ObservabilityConfig;
+//#endregion
+export { ObservabilityConfig, resolveObservabilityConfig };
+//# sourceMappingURL=config.d.mts.map

package/dist/config.mjs

@@ -0,0 +1,60 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/config.ts
+const DEFAULT_SERVICE_NAME = "storyshelf";
+const DEFAULT_METRICS_INTERVAL_MS = 6e4;
+/** Whether the current runtime is Deno (native OTEL owns the SDK there). */
+function isDenoRuntime(env) {
+	if (env["OTEL_DENO"] === "true") return true;
+	return globalThis.Deno !== void 0;
+}
+/** Parse one `k=v` pair into the headers record. */
+function parseHeaderPair(pair, headers) {
+	const separator = pair.indexOf("=");
+	if (separator === -1) return;
+	const key = pair.slice(0, separator).trim();
+	const value = pair.slice(separator + 1).trim();
+	if (key) headers[key] = value;
+}
+/** Parse `k=v,k2=v2` header syntax into a record. */
+function parseHeaders(raw) {
+	if (!raw) return;
+	const headers = {};
+	for (const pair of raw.split(",")) parseHeaderPair(pair, headers);
+	return Object.keys(headers).length === 0 ? void 0 : headers;
+}
+/** Parse a positive integer env value with a fallback. */
+function parseInterval(raw, fallback) {
+	const parsed = Number(raw);
+	if (!raw || !Number.isFinite(parsed) || parsed <= 0) return fallback;
+	return Math.trunc(parsed);
+}
+/**
+* Resolve the observability configuration from the environment.
+*
+* @param env - Environment record (defaults to `process.env`).
+* @param serviceVersion - Version for the resource (defaults to `__PKG_VERSION__`).
+* @returns The resolved config; `enabled` is false without an endpoint.
+*/
+function resolveObservabilityConfig(env = process.env, serviceVersion) {
+	const endpoint = env["OTEL_EXPORTER_OTLP_ENDPOINT"];
+	const sdkDisabled = env["OTEL_SDK_DISABLED"] === "true";
+	const explicit = env["STORYSHELF_OTEL_ENABLED"];
+	return {
+		enabled: !sdkDisabled && !isDenoRuntime(env) && (explicit ? explicit === "true" : Boolean(endpoint)),
+		endpoint,
+		headers: parseHeaders(env["OTEL_EXPORTER_OTLP_HEADERS"]),
+		serviceName: env["OTEL_SERVICE_NAME"] ?? DEFAULT_SERVICE_NAME,
+		serviceVersion: serviceVersion ?? packageVersion(),
+		metricsIntervalMs: parseInterval(env["STORYSHELF_OTEL_METRICS_INTERVAL_MS"], DEFAULT_METRICS_INTERVAL_MS)
+	};
+}
+/** Package version injected at build via __PKG_VERSION__. */
+function packageVersion() {
+	return globalThis.__PKG_VERSION__;
+}
+//#endregion
+export { resolveObservabilityConfig };
+
+//# sourceMappingURL=config.mjs.map

package/dist/config.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.mjs","names":[],"sources":["../src/config.ts"],"sourcesContent":["/**\n * Environment-driven observability configuration.\n *\n * Standard `OTEL_*` variables win; `STORYSHELF_OTEL_*` covers StoryShelf\n * specifics. When `OTEL_EXPORTER_OTLP_ENDPOINT` is unset the SDK stays a\n * noop (zero overhead, hermetic tests). Deno runtimes are always noop here —\n * Deno's built-in OTEL (`OTEL_DENO=true`) bridges `npm:@opentelemetry/api`\n * natively, so a NodeSDK must never start under Deno.\n */\n\n/** Resolved observability configuration for the Node SDK entrypoint. */\nexport interface ObservabilityConfig {\n  /** Whether to start the SDK (false = noop handle). */\n  enabled: boolean;\n  /** OTLP/HTTP endpoint, e.g. `http://collector:4318`. */\n  endpoint?: string;\n  /** Extra OTLP headers (`OTEL_EXPORTER_OTLP_HEADERS`, `k=v,k2=v2`). */\n  headers?: Record<string, string>;\n  /** Resource `service.name`. */\n  serviceName: string;\n  /** Resource `service.version`. */\n  serviceVersion?: string;\n  /** Metric export interval in milliseconds. */\n  metricsIntervalMs: number;\n}\n\nconst DEFAULT_SERVICE_NAME = \"storyshelf\";\nconst DEFAULT_METRICS_INTERVAL_MS = 60_000;\n\n/** Whether the current runtime is Deno (native OTEL owns the SDK there). */\nfunction isDenoRuntime(env: NodeJS.ProcessEnv): boolean {\n  if (env[\"OTEL_DENO\"] === \"true\") {\n    return true;\n  }\n  return (globalThis as { Deno?: unknown }).Deno !== undefined;\n}\n\n/** Parse one `k=v` pair into the headers record. */\nfunction parseHeaderPair(pair: string, headers: Record<string, string>): void {\n  const separator = pair.indexOf(\"=\");\n  if (separator === -1) {\n    return;\n  }\n  const key = pair.slice(0, separator).trim();\n  const value = pair.slice(separator + 1).trim();\n  if (key) {\n    headers[key] = value;\n  }\n}\n\n/** Parse `k=v,k2=v2` header syntax into a record. */\nfunction parseHeaders(raw: string | undefined): Record<string, string> | undefined {\n  if (!raw) {\n    return undefined;\n  }\n  const headers: Record<string, string> = {};\n  for (const pair of raw.split(\",\")) {\n    parseHeaderPair(pair, headers);\n  }\n  return Object.keys(headers).length === 0 ? undefined : headers;\n}\n\n/** Parse a positive integer env value with a fallback. */\nfunction parseInterval(raw: string | undefined, fallback: number): number {\n  const parsed = Number(raw);\n  if (!raw || !Number.isFinite(parsed) || parsed <= 0) {\n    return fallback;\n  }\n  return Math.trunc(parsed);\n}\n\n/**\n * Resolve the observability configuration from the environment.\n *\n * @param env - Environment record (defaults to `process.env`).\n * @param serviceVersion - Version for the resource (defaults to `__PKG_VERSION__`).\n * @returns The resolved config; `enabled` is false without an endpoint.\n */\nexport function resolveObservabilityConfig(\n  env: NodeJS.ProcessEnv = process.env,\n  serviceVersion?: string,\n): ObservabilityConfig {\n  const endpoint = env[\"OTEL_EXPORTER_OTLP_ENDPOINT\"];\n  const sdkDisabled = env[\"OTEL_SDK_DISABLED\"] === \"true\";\n  const explicit = env[\"STORYSHELF_OTEL_ENABLED\"];\n  const enabled =\n    !sdkDisabled && !isDenoRuntime(env) && (explicit ? explicit === \"true\" : Boolean(endpoint));\n  return {\n    enabled,\n    endpoint,\n    headers: parseHeaders(env[\"OTEL_EXPORTER_OTLP_HEADERS\"]),\n    serviceName: env[\"OTEL_SERVICE_NAME\"] ?? DEFAULT_SERVICE_NAME,\n    serviceVersion: serviceVersion ?? packageVersion(),\n    metricsIntervalMs: parseInterval(\n      env[\"STORYSHELF_OTEL_METRICS_INTERVAL_MS\"],\n      DEFAULT_METRICS_INTERVAL_MS,\n    ),\n  };\n}\n\n/** Package version injected at build via __PKG_VERSION__. */\nfunction packageVersion(): string | undefined {\n  return (globalThis as unknown as { __PKG_VERSION__?: string }).__PKG_VERSION__;\n}\n"],"mappings":";;;;AA0BA,MAAM,uBAAuB;AAC7B,MAAM,8BAA8B;;AAGpC,SAAS,cAAc,KAAiC;CACtD,IAAI,IAAI,iBAAiB,QACvB,OAAO;CAET,OAAQ,WAAkC,SAAS,KAAA;AACrD;;AAGA,SAAS,gBAAgB,MAAc,SAAuC;CAC5E,MAAM,YAAY,KAAK,QAAQ,GAAG;CAClC,IAAI,cAAc,IAChB;CAEF,MAAM,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC,KAAK;CAC1C,MAAM,QAAQ,KAAK,MAAM,YAAY,CAAC,CAAC,CAAC,KAAK;CAC7C,IAAI,KACF,QAAQ,OAAO;AAEnB;;AAGA,SAAS,aAAa,KAA6D;CACjF,IAAI,CAAC,KACH;CAEF,MAAM,UAAkC,CAAC;CACzC,KAAK,MAAM,QAAQ,IAAI,MAAM,GAAG,GAC9B,gBAAgB,MAAM,OAAO;CAE/B,OAAO,OAAO,KAAK,OAAO,CAAC,CAAC,WAAW,IAAI,KAAA,IAAY;AACzD;;AAGA,SAAS,cAAc,KAAyB,UAA0B;CACxE,MAAM,SAAS,OAAO,GAAG;CACzB,IAAI,CAAC,OAAO,CAAC,OAAO,SAAS,MAAM,KAAK,UAAU,GAChD,OAAO;CAET,OAAO,KAAK,MAAM,MAAM;AAC1B;;;;;;;;AASA,SAAgB,2BACd,MAAyB,QAAQ,KACjC,gBACqB;CACrB,MAAM,WAAW,IAAI;CACrB,MAAM,cAAc,IAAI,yBAAyB;CACjD,MAAM,WAAW,IAAI;CAGrB,OAAO;EACL,SAFA,CAAC,eAAe,CAAC,cAAc,GAAG,MAAM,WAAW,aAAa,SAAS,QAAQ,QAAQ;EAGzF;EACA,SAAS,aAAa,IAAI,6BAA6B;EACvD,aAAa,IAAI,wBAAwB;EACzC,gBAAgB,kBAAkB,eAAe;EACjD,mBAAmB,cACjB,IAAI,wCACJ,2BACF;CACF;AACF;;AAGA,SAAS,iBAAqC;CAC5C,OAAQ,WAAuD;AACjE"}

package/dist/index.d.mts

@@ -0,0 +1,12 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { createInstrumentedDatabase } from "./instrument-db.mjs";
+import { createInstrumentedStorage } from "./instrument-storage.mjs";
+import { HttpMiddlewareOptions, ObservabilityHandle, SpanAttributes } from "./types.mjs";
+import { createHttpMiddleware } from "./middleware.mjs";
+import { CaptureInstruments, DbInstruments, StorageInstruments, captureMetrics, dbMetrics, storageMetrics } from "./metrics.mjs";
+import { otelLogMixin } from "./logs.mjs";
+import { TRACEPARENT_HEADER, currentTraceparent, injectTraceContext, parentContext } from "./propagate.mjs";
+import { ObservabilityConfig, resolveObservabilityConfig } from "./config.mjs";
+import { withSpan } from "./tracing.mjs";
+export { type CaptureInstruments, type DbInstruments, type HttpMiddlewareOptions, type ObservabilityConfig, type ObservabilityHandle, type SpanAttributes, type StorageInstruments, TRACEPARENT_HEADER, captureMetrics, createHttpMiddleware, createInstrumentedDatabase, createInstrumentedStorage, currentTraceparent, dbMetrics, injectTraceContext, otelLogMixin, parentContext, resolveObservabilityConfig, storageMetrics, withSpan };

package/dist/index.mjs

@@ -0,0 +1,24 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { captureMetrics, dbMetrics, storageMetrics } from "./metrics.mjs";
+import { withSpan } from "./tracing.mjs";
+import { createInstrumentedDatabase } from "./instrument-db.mjs";
+import { createInstrumentedStorage } from "./instrument-storage.mjs";
+import { createHttpMiddleware } from "./middleware.mjs";
+import { otelLogMixin } from "./logs.mjs";
+import { TRACEPARENT_HEADER, currentTraceparent, injectTraceContext, parentContext } from "./propagate.mjs";
+import { resolveObservabilityConfig } from "./config.mjs";
+//#region src/index.ts
+/**
+* StoryShelf observability: runtime-agnostic OTEL instrumentation.
+*
+* This entrypoint is cross-runtime (`@opentelemetry/api` only — Node SDK or
+* Deno's native bridge supplies the provider). The Node SDK lifecycle
+* (`initObservabilityFromEnv`) lives under `@storyshelf/observability/node`
+* and must never be imported here.
+*/
+//#endregion
+export { TRACEPARENT_HEADER, captureMetrics, createHttpMiddleware, createInstrumentedDatabase, createInstrumentedStorage, currentTraceparent, dbMetrics, injectTraceContext, otelLogMixin, parentContext, resolveObservabilityConfig, storageMetrics, withSpan };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * StoryShelf observability: runtime-agnostic OTEL instrumentation.\n *\n * This entrypoint is cross-runtime (`@opentelemetry/api` only — Node SDK or\n * Deno's native bridge supplies the provider). The Node SDK lifecycle\n * (`initObservabilityFromEnv`) lives under `@storyshelf/observability/node`\n * and must never be imported here.\n */\nimport { createInstrumentedDatabase } from \"./instrument-db.ts\";\nimport { createInstrumentedStorage } from \"./instrument-storage.ts\";\nimport { createHttpMiddleware } from \"./middleware.ts\";\n\n/** Wrap a database adapter with `db.*` spans and metrics. */\nexport { createInstrumentedDatabase };\n/** Wrap a storage adapter with `storage.*` spans and metrics. */\nexport { createInstrumentedStorage };\n/** Hono middleware emitting one `http.server` span per request. */\nexport { createHttpMiddleware };\nexport { captureMetrics, dbMetrics, storageMetrics } from \"./metrics.ts\";\nexport type { CaptureInstruments, DbInstruments, StorageInstruments } from \"./metrics.ts\";\nexport { otelLogMixin } from \"./logs.ts\";\nexport {\n  TRACEPARENT_HEADER,\n  currentTraceparent,\n  injectTraceContext,\n  parentContext,\n} from \"./propagate.ts\";\nexport { resolveObservabilityConfig } from \"./config.ts\";\nexport type { ObservabilityConfig } from \"./config.ts\";\nexport { withSpan } from \"./tracing.ts\";\nexport type { HttpMiddlewareOptions, ObservabilityHandle, SpanAttributes } from \"./types.ts\";\n"],"mappings":""}

package/dist/instrument-db.d.mts

@@ -0,0 +1,14 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DatabaseAdapter } from "@storyshelf/core/adapter/database";
+//#region src/instrument-db.d.ts
+/**
+ * Wrap a database adapter with per-operation spans and metrics.
+ *
+ * @param db - The adapter to wrap (never mutated).
+ * @returns A transparent adapter emitting `db.*` telemetry.
+ */
+declare function createInstrumentedDatabase(db: DatabaseAdapter): DatabaseAdapter;
+//#endregion
+export { createInstrumentedDatabase };
+//# sourceMappingURL=instrument-db.d.mts.map

package/dist/instrument-db.mjs

@@ -0,0 +1,88 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { dbMetrics } from "./metrics.mjs";
+import { withSpan } from "./tracing.mjs";
+import { addTiming } from "@storyshelf/core/utils";
+import { getTableName } from "drizzle-orm";
+//#region src/instrument-db.ts
+/**
+* Wrap a database adapter with per-operation spans and metrics.
+*
+* @param db - The adapter to wrap (never mutated).
+* @returns A transparent adapter emitting `db.*` telemetry.
+*/
+function createInstrumentedDatabase(db) {
+	return new InstrumentedDatabase(db);
+}
+var InstrumentedDatabase = class {
+	inner;
+	constructor(inner) {
+		this.inner = inner;
+	}
+	get metadata() {
+		return this.inner.metadata;
+	}
+	get lifecycle() {
+		return this.inner.lifecycle;
+	}
+	get tables() {
+		return this.inner.tables;
+	}
+	setLogger(logger) {
+		this.inner.setLogger?.(logger);
+	}
+	async insert(table, values) {
+		return await track("db.insert", table, async () => await this.inner.insert(table, values));
+	}
+	async update(table, id, values) {
+		return await track("db.update", table, async () => await this.inner.update(table, id, values));
+	}
+	async get(table, id) {
+		return await track("db.get", table, async () => await this.inner.get(table, id));
+	}
+	async remove(table, id) {
+		await track("db.remove", table, async () => {
+			await this.inner.remove(table, id);
+		});
+	}
+	async list(table, opts) {
+		return await track("db.list", table, async () => await this.inner.list(table, opts));
+	}
+	async count(table, where) {
+		return await track("db.count", table, async () => await this.inner.count(table, where));
+	}
+	async all(query) {
+		return await trackQuery("db.all", async () => await this.inner.all(query));
+	}
+};
+/** Run a table operation inside a span with a duration measurement. */
+async function track(operation, table, fn) {
+	const tableName = getTableName(table);
+	const start = performance.now();
+	try {
+		return await withSpan(operation, fn, { "db.table": tableName });
+	} finally {
+		const durationMs = performance.now() - start;
+		addTiming("db", durationMs);
+		dbMetrics().operationDuration.record(durationMs, {
+			"db.operation": operation,
+			"db.table": tableName
+		});
+	}
+}
+/** Run a table-less query inside a span with a duration measurement. */
+async function trackQuery(operation, fn) {
+	const start = performance.now();
+	try {
+		return await withSpan(operation, fn);
+	} finally {
+		const durationMs = performance.now() - start;
+		addTiming("db", durationMs);
+		dbMetrics().operationDuration.record(durationMs, { "db.operation": operation });
+	}
+}
+//#endregion
+export { createInstrumentedDatabase };
+
+//# sourceMappingURL=instrument-db.mjs.map

package/dist/instrument-db.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrument-db.mjs","names":[],"sources":["../src/instrument-db.ts"],"sourcesContent":["/**\n * Database adapter wrapper: one span + duration metric per operation.\n *\n * Span names are `db.<operation>` with the table as an attribute (never in\n * the name). Adapter identity (`metadata`, `lifecycle`, `tables`) and the\n * host-bound logger delegate straight through, so health/setup behave\n * identically with or without observability.\n */\nimport type { DatabaseAdapter, ListOptions, Tables } from \"@storyshelf/core/adapter/database\";\nimport type { Logger } from \"@storyshelf/core/logger\";\nimport { addTiming } from \"@storyshelf/core/utils\";\nimport { getTableName, type SQL, type Table } from \"drizzle-orm\";\nimport { dbMetrics } from \"./metrics.ts\";\nimport { withSpan } from \"./tracing.ts\";\n\n/**\n * Wrap a database adapter with per-operation spans and metrics.\n *\n * @param db - The adapter to wrap (never mutated).\n * @returns A transparent adapter emitting `db.*` telemetry.\n */\nexport function createInstrumentedDatabase(db: DatabaseAdapter): DatabaseAdapter {\n  return new InstrumentedDatabase(db);\n}\n\nclass InstrumentedDatabase implements DatabaseAdapter {\n  constructor(private readonly inner: DatabaseAdapter) {}\n\n  get metadata(): DatabaseAdapter[\"metadata\"] {\n    return this.inner.metadata;\n  }\n\n  get lifecycle(): DatabaseAdapter[\"lifecycle\"] {\n    return this.inner.lifecycle;\n  }\n\n  get tables(): Tables {\n    return this.inner.tables;\n  }\n\n  setLogger(logger: Logger): void {\n    this.inner.setLogger?.(logger);\n  }\n\n  async insert<T extends Table>(table: T, values: T[\"$inferInsert\"]): Promise<T[\"$inferSelect\"]> {\n    return await track(\"db.insert\", table, async () => await this.inner.insert(table, values));\n  }\n\n  async update<T extends Table>(\n    table: T,\n    id: string,\n    values: Partial<T[\"$inferInsert\"]>,\n  ): Promise<T[\"$inferSelect\"]> {\n    return await track(\"db.update\", table, async () => await this.inner.update(table, id, values));\n  }\n\n  async get<T extends Table>(table: T, id: string): Promise<T[\"$inferSelect\"] | null> {\n    return await track(\"db.get\", table, async () => await this.inner.get(table, id));\n  }\n\n  async remove(table: Table, id: string): Promise<void> {\n    await track(\"db.remove\", table, async () => {\n      await this.inner.remove(table, id);\n    });\n  }\n\n  async list<T extends Table>(table: T, opts?: ListOptions): Promise<T[\"$inferSelect\"][]> {\n    return await track(\"db.list\", table, async () => await this.inner.list(table, opts));\n  }\n\n  async count(table: Table, where?: SQL): Promise<number> {\n    return await track(\"db.count\", table, async () => await this.inner.count(table, where));\n  }\n\n  async all<T>(query: SQL): Promise<T[]> {\n    return await trackQuery(\"db.all\", async () => await this.inner.all<T>(query));\n  }\n}\n\n/** Run a table operation inside a span with a duration measurement. */\nasync function track<T>(operation: string, table: Table, fn: () => Promise<T>): Promise<T> {\n  const tableName = getTableName(table);\n  const start = performance.now();\n  try {\n    return await withSpan(operation, fn, { \"db.table\": tableName });\n  } finally {\n    const durationMs = performance.now() - start;\n    addTiming(\"db\", durationMs);\n    dbMetrics().operationDuration.record(durationMs, {\n      \"db.operation\": operation,\n      \"db.table\": tableName,\n    });\n  }\n}\n\n/** Run a table-less query inside a span with a duration measurement. */\nasync function trackQuery<T>(operation: string, fn: () => Promise<T>): Promise<T> {\n  const start = performance.now();\n  try {\n    return await withSpan(operation, fn);\n  } finally {\n    const durationMs = performance.now() - start;\n    addTiming(\"db\", durationMs);\n    dbMetrics().operationDuration.record(durationMs, {\n      \"db.operation\": operation,\n    });\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;AAqBA,SAAgB,2BAA2B,IAAsC;CAC/E,OAAO,IAAI,qBAAqB,EAAE;AACpC;AAEA,IAAM,uBAAN,MAAsD;CACvB;CAA7B,YAAY,OAAyC;EAAxB,KAAA,QAAA;CAAyB;CAEtD,IAAI,WAAwC;EAC1C,OAAO,KAAK,MAAM;CACpB;CAEA,IAAI,YAA0C;EAC5C,OAAO,KAAK,MAAM;CACpB;CAEA,IAAI,SAAiB;EACnB,OAAO,KAAK,MAAM;CACpB;CAEA,UAAU,QAAsB;EAC9B,KAAK,MAAM,YAAY,MAAM;CAC/B;CAEA,MAAM,OAAwB,OAAU,QAAuD;EAC7F,OAAO,MAAM,MAAM,aAAa,OAAO,YAAY,MAAM,KAAK,MAAM,OAAO,OAAO,MAAM,CAAC;CAC3F;CAEA,MAAM,OACJ,OACA,IACA,QAC4B;EAC5B,OAAO,MAAM,MAAM,aAAa,OAAO,YAAY,MAAM,KAAK,MAAM,OAAO,OAAO,IAAI,MAAM,CAAC;CAC/F;CAEA,MAAM,IAAqB,OAAU,IAA+C;EAClF,OAAO,MAAM,MAAM,UAAU,OAAO,YAAY,MAAM,KAAK,MAAM,IAAI,OAAO,EAAE,CAAC;CACjF;CAEA,MAAM,OAAO,OAAc,IAA2B;EACpD,MAAM,MAAM,aAAa,OAAO,YAAY;GAC1C,MAAM,KAAK,MAAM,OAAO,OAAO,EAAE;EACnC,CAAC;CACH;CAEA,MAAM,KAAsB,OAAU,MAAkD;EACtF,OAAO,MAAM,MAAM,WAAW,OAAO,YAAY,MAAM,KAAK,MAAM,KAAK,OAAO,IAAI,CAAC;CACrF;CAEA,MAAM,MAAM,OAAc,OAA8B;EACtD,OAAO,MAAM,MAAM,YAAY,OAAO,YAAY,MAAM,KAAK,MAAM,MAAM,OAAO,KAAK,CAAC;CACxF;CAEA,MAAM,IAAO,OAA0B;EACrC,OAAO,MAAM,WAAW,UAAU,YAAY,MAAM,KAAK,MAAM,IAAO,KAAK,CAAC;CAC9E;AACF;;AAGA,eAAe,MAAS,WAAmB,OAAc,IAAkC;CACzF,MAAM,YAAY,aAAa,KAAK;CACpC,MAAM,QAAQ,YAAY,IAAI;CAC9B,IAAI;EACF,OAAO,MAAM,SAAS,WAAW,IAAI,EAAE,YAAY,UAAU,CAAC;CAChE,UAAU;EACR,MAAM,aAAa,YAAY,IAAI,IAAI;EACvC,UAAU,MAAM,UAAU;EAC1B,UAAU,CAAC,CAAC,kBAAkB,OAAO,YAAY;GAC/C,gBAAgB;GAChB,YAAY;EACd,CAAC;CACH;AACF;;AAGA,eAAe,WAAc,WAAmB,IAAkC;CAChF,MAAM,QAAQ,YAAY,IAAI;CAC9B,IAAI;EACF,OAAO,MAAM,SAAS,WAAW,EAAE;CACrC,UAAU;EACR,MAAM,aAAa,YAAY,IAAI,IAAI;EACvC,UAAU,MAAM,UAAU;EAC1B,UAAU,CAAC,CAAC,kBAAkB,OAAO,YAAY,EAC/C,gBAAgB,UAClB,CAAC;CACH;AACF"}

package/dist/instrument-storage.d.mts

@@ -0,0 +1,14 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { StorageAdapter } from "@storyshelf/core/adapter/storage";
+//#region src/instrument-storage.d.ts
+/**
+ * Wrap a storage adapter with per-operation spans and metrics.
+ *
+ * @param storage - The adapter to wrap (never mutated).
+ * @returns A transparent adapter emitting `storage.*` telemetry.
+ */
+declare function createInstrumentedStorage(storage: StorageAdapter): StorageAdapter;
+//#endregion
+export { createInstrumentedStorage };
+//# sourceMappingURL=instrument-storage.d.mts.map

package/dist/instrument-storage.mjs

@@ -0,0 +1,73 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { storageMetrics } from "./metrics.mjs";
+import { withSpan } from "./tracing.mjs";
+import { addTiming } from "@storyshelf/core/utils";
+//#region src/instrument-storage.ts
+/**
+* Wrap a storage adapter with per-operation spans and metrics.
+*
+* @param storage - The adapter to wrap (never mutated).
+* @returns A transparent adapter emitting `storage.*` telemetry.
+*/
+function createInstrumentedStorage(storage) {
+	return new InstrumentedStorage(storage);
+}
+var InstrumentedStorage = class {
+	inner;
+	constructor(inner) {
+		this.inner = inner;
+	}
+	get metadata() {
+		return this.inner.metadata;
+	}
+	get lifecycle() {
+		return this.inner.lifecycle;
+	}
+	setLogger(logger) {
+		this.inner.setLogger?.(logger);
+	}
+	async read(path) {
+		return await track("storage.read", path, async () => await this.inner.read(path));
+	}
+	async write(path, data) {
+		await track("storage.write", path, async () => {
+			await this.inner.write(path, data);
+		});
+	}
+	async delete(path) {
+		await track("storage.delete", path, async () => {
+			await this.inner.delete(path);
+		});
+	}
+	async exists(path) {
+		return await track("storage.exists", path, async () => await this.inner.exists(path));
+	}
+	async list(prefix) {
+		return await track("storage.list", prefix, async () => await this.inner.list(prefix));
+	}
+	async writeStream(path, stream) {
+		await track("storage.writeStream", path, async () => {
+			await this.inner.writeStream(path, stream);
+		});
+	}
+	async readStream(path) {
+		return await track("storage.readStream", path, async () => await this.inner.readStream(path));
+	}
+};
+/** Run a storage operation inside a span with a duration measurement. */
+async function track(operation, path, fn) {
+	const start = performance.now();
+	try {
+		return await withSpan(operation, fn, { "storage.path": path });
+	} finally {
+		const durationMs = performance.now() - start;
+		addTiming("storage", durationMs);
+		storageMetrics().operationDuration.record(durationMs, { "storage.operation": operation });
+	}
+}
+//#endregion
+export { createInstrumentedStorage };
+
+//# sourceMappingURL=instrument-storage.mjs.map

package/dist/instrument-storage.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrument-storage.mjs","names":[],"sources":["../src/instrument-storage.ts"],"sourcesContent":["/**\n * Storage adapter wrapper: one span + duration metric per operation.\n *\n * Span names are `storage.<operation>` with the path as an attribute.\n * Metrics carry the operation only (paths are high-cardinality and stay\n * out of metric attributes). Identity, lifecycle, and logger delegate\n * straight through.\n */\nimport type { StorageAdapter } from \"@storyshelf/core/adapter/storage\";\nimport type { Logger } from \"@storyshelf/core/logger\";\nimport { addTiming } from \"@storyshelf/core/utils\";\nimport type { Buffer } from \"node:buffer\";\nimport type { Readable } from \"node:stream\";\nimport { storageMetrics } from \"./metrics.ts\";\nimport { withSpan } from \"./tracing.ts\";\n\n/**\n * Wrap a storage adapter with per-operation spans and metrics.\n *\n * @param storage - The adapter to wrap (never mutated).\n * @returns A transparent adapter emitting `storage.*` telemetry.\n */\nexport function createInstrumentedStorage(storage: StorageAdapter): StorageAdapter {\n  return new InstrumentedStorage(storage);\n}\n\nclass InstrumentedStorage implements StorageAdapter {\n  constructor(private readonly inner: StorageAdapter) {}\n\n  get metadata(): StorageAdapter[\"metadata\"] {\n    return this.inner.metadata;\n  }\n\n  get lifecycle(): StorageAdapter[\"lifecycle\"] {\n    return this.inner.lifecycle;\n  }\n\n  setLogger(logger: Logger): void {\n    this.inner.setLogger?.(logger);\n  }\n\n  async read(path: string): Promise<Buffer> {\n    return await track(\"storage.read\", path, async () => await this.inner.read(path));\n  }\n\n  async write(path: string, data: Buffer): Promise<void> {\n    await track(\"storage.write\", path, async () => {\n      await this.inner.write(path, data);\n    });\n  }\n\n  async delete(path: string): Promise<void> {\n    await track(\"storage.delete\", path, async () => {\n      await this.inner.delete(path);\n    });\n  }\n\n  async exists(path: string): Promise<boolean> {\n    return await track(\"storage.exists\", path, async () => await this.inner.exists(path));\n  }\n\n  async list(prefix: string): Promise<string[]> {\n    return await track(\"storage.list\", prefix, async () => await this.inner.list(prefix));\n  }\n\n  async writeStream(path: string, stream: Readable): Promise<void> {\n    await track(\"storage.writeStream\", path, async () => {\n      await this.inner.writeStream(path, stream);\n    });\n  }\n\n  async readStream(path: string): Promise<Readable> {\n    return await track(\"storage.readStream\", path, async () => await this.inner.readStream(path));\n  }\n}\n\n/** Run a storage operation inside a span with a duration measurement. */\nasync function track<T>(operation: string, path: string, fn: () => Promise<T>): Promise<T> {\n  const start = performance.now();\n  try {\n    return await withSpan(operation, fn, { \"storage.path\": path });\n  } finally {\n    const durationMs = performance.now() - start;\n    addTiming(\"storage\", durationMs);\n    storageMetrics().operationDuration.record(durationMs, {\n      \"storage.operation\": operation,\n    });\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AAsBA,SAAgB,0BAA0B,SAAyC;CACjF,OAAO,IAAI,oBAAoB,OAAO;AACxC;AAEA,IAAM,sBAAN,MAAoD;CACrB;CAA7B,YAAY,OAAwC;EAAvB,KAAA,QAAA;CAAwB;CAErD,IAAI,WAAuC;EACzC,OAAO,KAAK,MAAM;CACpB;CAEA,IAAI,YAAyC;EAC3C,OAAO,KAAK,MAAM;CACpB;CAEA,UAAU,QAAsB;EAC9B,KAAK,MAAM,YAAY,MAAM;CAC/B;CAEA,MAAM,KAAK,MAA+B;EACxC,OAAO,MAAM,MAAM,gBAAgB,MAAM,YAAY,MAAM,KAAK,MAAM,KAAK,IAAI,CAAC;CAClF;CAEA,MAAM,MAAM,MAAc,MAA6B;EACrD,MAAM,MAAM,iBAAiB,MAAM,YAAY;GAC7C,MAAM,KAAK,MAAM,MAAM,MAAM,IAAI;EACnC,CAAC;CACH;CAEA,MAAM,OAAO,MAA6B;EACxC,MAAM,MAAM,kBAAkB,MAAM,YAAY;GAC9C,MAAM,KAAK,MAAM,OAAO,IAAI;EAC9B,CAAC;CACH;CAEA,MAAM,OAAO,MAAgC;EAC3C,OAAO,MAAM,MAAM,kBAAkB,MAAM,YAAY,MAAM,KAAK,MAAM,OAAO,IAAI,CAAC;CACtF;CAEA,MAAM,KAAK,QAAmC;EAC5C,OAAO,MAAM,MAAM,gBAAgB,QAAQ,YAAY,MAAM,KAAK,MAAM,KAAK,MAAM,CAAC;CACtF;CAEA,MAAM,YAAY,MAAc,QAAiC;EAC/D,MAAM,MAAM,uBAAuB,MAAM,YAAY;GACnD,MAAM,KAAK,MAAM,YAAY,MAAM,MAAM;EAC3C,CAAC;CACH;CAEA,MAAM,WAAW,MAAiC;EAChD,OAAO,MAAM,MAAM,sBAAsB,MAAM,YAAY,MAAM,KAAK,MAAM,WAAW,IAAI,CAAC;CAC9F;AACF;;AAGA,eAAe,MAAS,WAAmB,MAAc,IAAkC;CACzF,MAAM,QAAQ,YAAY,IAAI;CAC9B,IAAI;EACF,OAAO,MAAM,SAAS,WAAW,IAAI,EAAE,gBAAgB,KAAK,CAAC;CAC/D,UAAU;EACR,MAAM,aAAa,YAAY,IAAI,IAAI;EACvC,UAAU,WAAW,UAAU;EAC/B,eAAe,CAAC,CAAC,kBAAkB,OAAO,YAAY,EACpD,qBAAqB,UACvB,CAAC;CACH;AACF"}

package/dist/logs.d.mts

@@ -0,0 +1,12 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/logs.d.ts
+/**
+ * Build the trace-correlation fields for one log line.
+ *
+ * @returns `{ trace_id, span_id }` when a valid span is active, else `{}`.
+ */
+declare function otelLogMixin(): Record<string, string>;
+//#endregion
+export { otelLogMixin };
+//# sourceMappingURL=logs.d.mts.map

package/dist/logs.mjs

@@ -0,0 +1,30 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { context, trace } from "@opentelemetry/api";
+//#region src/logs.ts
+/**
+* Pino log correlation: inject the active trace context into every log line.
+*
+* Pass `otelLogMixin` as the pino `mixin` (see `LoggerOptions.mixin`) so
+* stdout JSON carries `trace_id`/`span_id` whenever a span is active. The
+* collector joins these with exported traces — this is the log signal
+* (no separate OTLP log exporter; pino stays the single log pipeline).
+*/
+/**
+* Build the trace-correlation fields for one log line.
+*
+* @returns `{ trace_id, span_id }` when a valid span is active, else `{}`.
+*/
+function otelLogMixin() {
+	const spanContext = trace.getSpan(context.active())?.spanContext();
+	if (!spanContext || spanContext.traceId === "00000000000000000000000000000000") return {};
+	return {
+		trace_id: spanContext.traceId,
+		span_id: spanContext.spanId
+	};
+}
+//#endregion
+export { otelLogMixin };
+
+//# sourceMappingURL=logs.mjs.map

package/dist/logs.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"logs.mjs","names":[],"sources":["../src/logs.ts"],"sourcesContent":["/**\n * Pino log correlation: inject the active trace context into every log line.\n *\n * Pass `otelLogMixin` as the pino `mixin` (see `LoggerOptions.mixin`) so\n * stdout JSON carries `trace_id`/`span_id` whenever a span is active. The\n * collector joins these with exported traces — this is the log signal\n * (no separate OTLP log exporter; pino stays the single log pipeline).\n */\nimport { context, trace } from \"@opentelemetry/api\";\n\n/**\n * Build the trace-correlation fields for one log line.\n *\n * @returns `{ trace_id, span_id }` when a valid span is active, else `{}`.\n */\nexport function otelLogMixin(): Record<string, string> {\n  const spanContext = trace.getSpan(context.active())?.spanContext();\n  if (!spanContext || spanContext.traceId === \"00000000000000000000000000000000\") {\n    return {};\n  }\n  return { trace_id: spanContext.traceId, span_id: spanContext.spanId };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAeA,SAAgB,eAAuC;CACrD,MAAM,cAAc,MAAM,QAAQ,QAAQ,OAAO,CAAC,CAAC,EAAE,YAAY;CACjE,IAAI,CAAC,eAAe,YAAY,YAAY,oCAC1C,OAAO,CAAC;CAEV,OAAO;EAAE,UAAU,YAAY;EAAS,SAAS,YAAY;CAAO;AACtE"}

package/dist/metrics.d.mts

@@ -0,0 +1,32 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Counter, Histogram } from "@opentelemetry/api";
+//#region src/metrics.d.ts
+/** Capture-pipeline instruments. */
+interface CaptureInstruments {
+  /** Capture job wall duration in milliseconds (`capture.job.status`). */
+  jobDuration: Histogram;
+  /** Completed jobs (`capture.job.status = completed`). */
+  jobsCompleted: Counter;
+  /** Failed jobs (`capture.job.status = failed`). */
+  jobsFailed: Counter;
+}
+/** Database-operation instruments. */
+interface DbInstruments {
+  /** Per-operation wall duration in milliseconds (`db.operation`, `db.table`). */
+  operationDuration: Histogram;
+}
+/** Storage-operation instruments. */
+interface StorageInstruments {
+  /** Per-operation wall duration in milliseconds (`storage.operation`). */
+  operationDuration: Histogram;
+}
+/** Capture-pipeline instruments (created once). */
+declare function captureMetrics(): CaptureInstruments;
+/** Database-operation instruments (created once). */
+declare function dbMetrics(): DbInstruments;
+/** Storage-operation instruments (created once). */
+declare function storageMetrics(): StorageInstruments;
+//#endregion
+export { CaptureInstruments, DbInstruments, StorageInstruments, captureMetrics, dbMetrics, storageMetrics };
+//# sourceMappingURL=metrics.d.mts.map

package/dist/metrics.mjs

@@ -0,0 +1,44 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { metrics } from "@opentelemetry/api";
+//#region src/metrics.ts
+/**
+* Memoized OTEL instruments (global meter, `storyshelf` scope).
+*
+* Instruments are created once — duplicate `createHistogram` calls on one
+* meter log warnings, hence the module cache. Without an SDK these are
+* noops. Attribute values stay low-cardinality (operations, statuses);
+* IDs and paths never appear here.
+*/
+/** Meter scope for StoryShelf instruments. */
+const METER_NAME = "storyshelf";
+let capture;
+let database;
+let storage;
+/** Capture-pipeline instruments (created once). */
+function captureMetrics() {
+	if (!capture) {
+		const meter = metrics.getMeter(METER_NAME);
+		capture = {
+			jobDuration: meter.createHistogram("capture.job.duration", { unit: "ms" }),
+			jobsCompleted: meter.createCounter("capture.jobs.completed"),
+			jobsFailed: meter.createCounter("capture.jobs.failed")
+		};
+	}
+	return capture;
+}
+/** Database-operation instruments (created once). */
+function dbMetrics() {
+	if (!database) database = { operationDuration: metrics.getMeter(METER_NAME).createHistogram("db.operation.duration", { unit: "ms" }) };
+	return database;
+}
+/** Storage-operation instruments (created once). */
+function storageMetrics() {
+	if (!storage) storage = { operationDuration: metrics.getMeter(METER_NAME).createHistogram("storage.operation.duration", { unit: "ms" }) };
+	return storage;
+}
+//#endregion
+export { captureMetrics, dbMetrics, storageMetrics };
+
+//# sourceMappingURL=metrics.mjs.map

package/dist/metrics.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.mjs","names":[],"sources":["../src/metrics.ts"],"sourcesContent":["/**\n * Memoized OTEL instruments (global meter, `storyshelf` scope).\n *\n * Instruments are created once — duplicate `createHistogram` calls on one\n * meter log warnings, hence the module cache. Without an SDK these are\n * noops. Attribute values stay low-cardinality (operations, statuses);\n * IDs and paths never appear here.\n */\nimport { metrics, type Counter, type Histogram } from \"@opentelemetry/api\";\n\n/** Meter scope for StoryShelf instruments. */\nconst METER_NAME = \"storyshelf\";\n\n/** Capture-pipeline instruments. */\nexport interface CaptureInstruments {\n  /** Capture job wall duration in milliseconds (`capture.job.status`). */\n  jobDuration: Histogram;\n  /** Completed jobs (`capture.job.status = completed`). */\n  jobsCompleted: Counter;\n  /** Failed jobs (`capture.job.status = failed`). */\n  jobsFailed: Counter;\n}\n\n/** Database-operation instruments. */\nexport interface DbInstruments {\n  /** Per-operation wall duration in milliseconds (`db.operation`, `db.table`). */\n  operationDuration: Histogram;\n}\n\n/** Storage-operation instruments. */\nexport interface StorageInstruments {\n  /** Per-operation wall duration in milliseconds (`storage.operation`). */\n  operationDuration: Histogram;\n}\n\nlet capture: CaptureInstruments | undefined;\nlet database: DbInstruments | undefined;\nlet storage: StorageInstruments | undefined;\n\n/** Capture-pipeline instruments (created once). */\nexport function captureMetrics(): CaptureInstruments {\n  if (!capture) {\n    const meter = metrics.getMeter(METER_NAME);\n    capture = {\n      jobDuration: meter.createHistogram(\"capture.job.duration\", { unit: \"ms\" }),\n      jobsCompleted: meter.createCounter(\"capture.jobs.completed\"),\n      jobsFailed: meter.createCounter(\"capture.jobs.failed\"),\n    };\n  }\n  return capture;\n}\n\n/** Database-operation instruments (created once). */\nexport function dbMetrics(): DbInstruments {\n  if (!database) {\n    const meter = metrics.getMeter(METER_NAME);\n    database = {\n      operationDuration: meter.createHistogram(\"db.operation.duration\", { unit: \"ms\" }),\n    };\n  }\n  return database;\n}\n\n/** Storage-operation instruments (created once). */\nexport function storageMetrics(): StorageInstruments {\n  if (!storage) {\n    const meter = metrics.getMeter(METER_NAME);\n    storage = {\n      operationDuration: meter.createHistogram(\"storage.operation.duration\", { unit: \"ms\" }),\n    };\n  }\n  return storage;\n}\n"],"mappings":";;;;;;;;;;;;;;AAWA,MAAM,aAAa;AAwBnB,IAAI;AACJ,IAAI;AACJ,IAAI;;AAGJ,SAAgB,iBAAqC;CACnD,IAAI,CAAC,SAAS;EACZ,MAAM,QAAQ,QAAQ,SAAS,UAAU;EACzC,UAAU;GACR,aAAa,MAAM,gBAAgB,wBAAwB,EAAE,MAAM,KAAK,CAAC;GACzE,eAAe,MAAM,cAAc,wBAAwB;GAC3D,YAAY,MAAM,cAAc,qBAAqB;EACvD;CACF;CACA,OAAO;AACT;;AAGA,SAAgB,YAA2B;CACzC,IAAI,CAAC,UAEH,WAAW,EACT,mBAFY,QAAQ,SAAS,UAEN,CAAC,CAAC,gBAAgB,yBAAyB,EAAE,MAAM,KAAK,CAAC,EAClF;CAEF,OAAO;AACT;;AAGA,SAAgB,iBAAqC;CACnD,IAAI,CAAC,SAEH,UAAU,EACR,mBAFY,QAAQ,SAAS,UAEN,CAAC,CAAC,gBAAgB,8BAA8B,EAAE,MAAM,KAAK,CAAC,EACvF;CAEF,OAAO;AACT"}

package/dist/middleware.d.mts

@@ -0,0 +1,18 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { HttpMiddlewareOptions } from "./types.mjs";
+import { MiddlewareHandler } from "hono";
+//#region src/middleware.d.ts
+/**
+ * Create the instrumenting middleware.
+ *
+ * Mount directly after Hono's `requestId()` so `storyshelf.req_id` resolves;
+ * `enduser.id` resolves when `storeScope` runs downstream.
+ *
+ * @param options - Service name/version for span resources.
+ * @returns Hono middleware producing one `http.server` span per request.
+ */
+declare function createHttpMiddleware(options?: HttpMiddlewareOptions): MiddlewareHandler;
+//#endregion
+export { createHttpMiddleware };
+//# sourceMappingURL=middleware.d.mts.map

package/dist/middleware.mjs

@@ -0,0 +1,48 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { context, trace } from "@opentelemetry/api";
+import { httpInstrumentationMiddleware } from "@hono/otel";
+//#region src/middleware.ts
+/**
+* Hono HTTP middleware: `@hono/otel` server spans plus StoryShelf context.
+*
+* `@hono/otel` owns the `http.server` span (W3C extraction, route-template
+* naming, status attributes, request-duration metrics). This wrapper adds
+* `storyshelf.req_id` and `enduser.id` after downstream handlers run — still
+* inside the span, since `@hono/otel` finalizes after `next()` returns.
+*/
+/** Copy request/user ids from the Hono context onto the active server span. */
+function enrichSpan(c) {
+	const span = trace.getSpan(context.active());
+	if (!span) return;
+	const reqId = c.get("requestId");
+	if (reqId) span.setAttribute("storyshelf.req_id", reqId);
+	const userId = c.get("userId");
+	if (userId) span.setAttribute("enduser.id", userId);
+}
+/**
+* Create the instrumenting middleware.
+*
+* Mount directly after Hono's `requestId()` so `storyshelf.req_id` resolves;
+* `enduser.id` resolves when `storeScope` runs downstream.
+*
+* @param options - Service name/version for span resources.
+* @returns Hono middleware producing one `http.server` span per request.
+*/
+function createHttpMiddleware(options = {}) {
+	const otel = httpInstrumentationMiddleware({
+		serviceName: options.serviceName ?? "storyshelf",
+		serviceVersion: options.serviceVersion
+	});
+	return async (c, next) => {
+		return await otel(c, async () => {
+			await next();
+			enrichSpan(c);
+		});
+	};
+}
+//#endregion
+export { createHttpMiddleware };
+
+//# sourceMappingURL=middleware.mjs.map

package/dist/middleware.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.mjs","names":[],"sources":["../src/middleware.ts"],"sourcesContent":["/**\n * Hono HTTP middleware: `@hono/otel` server spans plus StoryShelf context.\n *\n * `@hono/otel` owns the `http.server` span (W3C extraction, route-template\n * naming, status attributes, request-duration metrics). This wrapper adds\n * `storyshelf.req_id` and `enduser.id` after downstream handlers run — still\n * inside the span, since `@hono/otel` finalizes after `next()` returns.\n */\nimport { httpInstrumentationMiddleware } from \"@hono/otel\";\nimport { context, trace } from \"@opentelemetry/api\";\nimport type { Context, MiddlewareHandler } from \"hono\";\nimport type { HttpMiddlewareOptions } from \"./types.ts\";\n\n/** Copy request/user ids from the Hono context onto the active server span. */\nfunction enrichSpan(c: Context): void {\n  const span = trace.getSpan(context.active());\n  if (!span) {\n    return;\n  }\n  const reqId = c.get(\"requestId\") as string | undefined;\n  if (reqId) {\n    span.setAttribute(\"storyshelf.req_id\", reqId);\n  }\n  const userId = c.get(\"userId\") as string | null | undefined;\n  if (userId) {\n    span.setAttribute(\"enduser.id\", userId);\n  }\n}\n\n/**\n * Create the instrumenting middleware.\n *\n * Mount directly after Hono's `requestId()` so `storyshelf.req_id` resolves;\n * `enduser.id` resolves when `storeScope` runs downstream.\n *\n * @param options - Service name/version for span resources.\n * @returns Hono middleware producing one `http.server` span per request.\n */\nexport function createHttpMiddleware(options: HttpMiddlewareOptions = {}): MiddlewareHandler {\n  const otel = httpInstrumentationMiddleware({\n    serviceName: options.serviceName ?? \"storyshelf\",\n    serviceVersion: options.serviceVersion,\n  });\n  return async (c, next) => {\n    return await otel(c, async () => {\n      await next();\n      enrichSpan(c);\n    });\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;AAcA,SAAS,WAAW,GAAkB;CACpC,MAAM,OAAO,MAAM,QAAQ,QAAQ,OAAO,CAAC;CAC3C,IAAI,CAAC,MACH;CAEF,MAAM,QAAQ,EAAE,IAAI,WAAW;CAC/B,IAAI,OACF,KAAK,aAAa,qBAAqB,KAAK;CAE9C,MAAM,SAAS,EAAE,IAAI,QAAQ;CAC7B,IAAI,QACF,KAAK,aAAa,cAAc,MAAM;AAE1C;;;;;;;;;;AAWA,SAAgB,qBAAqB,UAAiC,CAAC,GAAsB;CAC3F,MAAM,OAAO,8BAA8B;EACzC,aAAa,QAAQ,eAAe;EACpC,gBAAgB,QAAQ;CAC1B,CAAC;CACD,OAAO,OAAO,GAAG,SAAS;EACxB,OAAO,MAAM,KAAK,GAAG,YAAY;GAC/B,MAAM,KAAK;GACX,WAAW,CAAC;EACd,CAAC;CACH;AACF"}

package/dist/node.d.mts

@@ -0,0 +1,20 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { ObservabilityHandle } from "./types.mjs";
+import { ObservabilityConfig, resolveObservabilityConfig } from "./config.mjs";
+//#region src/node.d.ts
+/**
+ * Initialize observability from the environment.
+ *
+ * Starts the Node SDK when `OTEL_EXPORTER_OTLP_ENDPOINT` (or
+ * `STORYSHELF_OTEL_ENABLED=true`) is set; otherwise returns a noop handle
+ * (also under Deno or `OTEL_SDK_DISABLED=true`). Call before
+ * `createShelfApp` and flush via the handle next to `app.lifecycle.teardown`.
+ *
+ * @param env - Environment record (defaults to `process.env`).
+ * @returns The SDK handle (check `enabled`, always call `shutdown`).
+ */
+declare function initObservabilityFromEnv(env?: NodeJS.ProcessEnv): Promise<ObservabilityHandle>;
+//#endregion
+export { type ObservabilityConfig, type ObservabilityHandle, initObservabilityFromEnv, resolveObservabilityConfig };
+//# sourceMappingURL=node.d.mts.map

package/dist/node.mjs

@@ -0,0 +1,83 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { resolveObservabilityConfig } from "./config.mjs";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { ATTR_DEPLOYMENT_ENVIRONMENT_NAME, ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
+//#region src/node.ts
+/**
+* Node-only OTEL SDK lifecycle.
+*
+* Separate entrypoint (`@storyshelf/observability/node`) so the cross-runtime
+* root never pulls Node SDK modules. Never import this file under Deno —
+* `initObservabilityFromEnv` noops there and Deno's native OTEL owns export.
+*/
+/** Noop handle: SDK disabled, nothing to flush. */
+function noopHandle() {
+	return {
+		enabled: false,
+		shutdown: async () => {
+			await Promise.resolve();
+		}
+	};
+}
+/** OTLP/HTTP exporter options shared by trace and metric exporters. */
+function exporterOptions(config) {
+	return {
+		url: config.endpoint ? `${config.endpoint}/v1/traces` : void 0,
+		headers: config.headers
+	};
+}
+/** Start the Node SDK wired to the OTLP/HTTP endpoint. */
+function startSdk(config) {
+	const resource = resourceFromAttributes({
+		[ATTR_SERVICE_NAME]: config.serviceName,
+		...config.serviceVersion ? { [ATTR_SERVICE_VERSION]: config.serviceVersion } : {},
+		...process.env["NODE_ENV"] ? { [ATTR_DEPLOYMENT_ENVIRONMENT_NAME]: process.env["NODE_ENV"] } : {}
+	});
+	const sdk = new NodeSDK({
+		resource,
+		traceExporter: new OTLPTraceExporter(exporterOptions(config)),
+		metricReaders: [new PeriodicExportingMetricReader({
+			exporter: new OTLPMetricExporter({
+				url: config.endpoint ? `${config.endpoint}/v1/metrics` : void 0,
+				headers: config.headers
+			}),
+			exportIntervalMillis: config.metricsIntervalMs
+		})]
+	});
+	sdk.start();
+	let shut = false;
+	return {
+		enabled: true,
+		shutdown: async () => {
+			if (shut) return;
+			shut = true;
+			await sdk.shutdown();
+		}
+	};
+}
+/**
+* Initialize observability from the environment.
+*
+* Starts the Node SDK when `OTEL_EXPORTER_OTLP_ENDPOINT` (or
+* `STORYSHELF_OTEL_ENABLED=true`) is set; otherwise returns a noop handle
+* (also under Deno or `OTEL_SDK_DISABLED=true`). Call before
+* `createShelfApp` and flush via the handle next to `app.lifecycle.teardown`.
+*
+* @param env - Environment record (defaults to `process.env`).
+* @returns The SDK handle (check `enabled`, always call `shutdown`).
+*/
+async function initObservabilityFromEnv(env = process.env) {
+	const config = resolveObservabilityConfig(env);
+	if (!config.enabled) return noopHandle();
+	return startSdk(config);
+}
+//#endregion
+export { initObservabilityFromEnv, resolveObservabilityConfig };
+
+//# sourceMappingURL=node.mjs.map

package/dist/node.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.mjs","names":[],"sources":["../src/node.ts"],"sourcesContent":["/**\n * Node-only OTEL SDK lifecycle.\n *\n * Separate entrypoint (`@storyshelf/observability/node`) so the cross-runtime\n * root never pulls Node SDK modules. Never import this file under Deno —\n * `initObservabilityFromEnv` noops there and Deno's native OTEL owns export.\n */\nimport { OTLPMetricExporter } from \"@opentelemetry/exporter-metrics-otlp-http\";\nimport { OTLPTraceExporter } from \"@opentelemetry/exporter-trace-otlp-http\";\nimport { resourceFromAttributes } from \"@opentelemetry/resources\";\nimport { PeriodicExportingMetricReader } from \"@opentelemetry/sdk-metrics\";\nimport { NodeSDK } from \"@opentelemetry/sdk-node\";\nimport {\n  ATTR_DEPLOYMENT_ENVIRONMENT_NAME,\n  ATTR_SERVICE_NAME,\n  ATTR_SERVICE_VERSION,\n} from \"@opentelemetry/semantic-conventions\";\nimport { resolveObservabilityConfig, type ObservabilityConfig } from \"./config.ts\";\nimport type { ObservabilityHandle } from \"./types.ts\";\n\n/** Noop handle: SDK disabled, nothing to flush. */\nfunction noopHandle(): ObservabilityHandle {\n  return {\n    enabled: false,\n    shutdown: async (): Promise<void> => {\n      await Promise.resolve();\n    },\n  };\n}\n\n/** OTLP/HTTP exporter options shared by trace and metric exporters. */\nfunction exporterOptions(config: ObservabilityConfig): {\n  url?: string;\n  headers?: Record<string, string>;\n} {\n  return {\n    url: config.endpoint ? `${config.endpoint}/v1/traces` : undefined,\n    headers: config.headers,\n  };\n}\n\n/** Start the Node SDK wired to the OTLP/HTTP endpoint. */\nfunction startSdk(config: ObservabilityConfig): ObservabilityHandle {\n  const resource = resourceFromAttributes({\n    [ATTR_SERVICE_NAME]: config.serviceName,\n    ...(config.serviceVersion ? { [ATTR_SERVICE_VERSION]: config.serviceVersion } : {}),\n    ...(process.env[\"NODE_ENV\"]\n      ? { [ATTR_DEPLOYMENT_ENVIRONMENT_NAME]: process.env[\"NODE_ENV\"] }\n      : {}),\n  });\n  const sdk = new NodeSDK({\n    resource,\n    traceExporter: new OTLPTraceExporter(exporterOptions(config)),\n    metricReaders: [\n      new PeriodicExportingMetricReader({\n        exporter: new OTLPMetricExporter({\n          url: config.endpoint ? `${config.endpoint}/v1/metrics` : undefined,\n          headers: config.headers,\n        }),\n        exportIntervalMillis: config.metricsIntervalMs,\n      }),\n    ],\n  });\n  sdk.start();\n  let shut = false;\n  return {\n    enabled: true,\n    shutdown: async (): Promise<void> => {\n      if (shut) {\n        return;\n      }\n      shut = true;\n      await sdk.shutdown();\n    },\n  };\n}\n\n/**\n * Initialize observability from the environment.\n *\n * Starts the Node SDK when `OTEL_EXPORTER_OTLP_ENDPOINT` (or\n * `STORYSHELF_OTEL_ENABLED=true`) is set; otherwise returns a noop handle\n * (also under Deno or `OTEL_SDK_DISABLED=true`). Call before\n * `createShelfApp` and flush via the handle next to `app.lifecycle.teardown`.\n *\n * @param env - Environment record (defaults to `process.env`).\n * @returns The SDK handle (check `enabled`, always call `shutdown`).\n */\n// oxlint-disable-next-line typescript/require-await -- async signature; the disabled fast-path is synchronous\nexport async function initObservabilityFromEnv(\n  env: NodeJS.ProcessEnv = process.env,\n): Promise<ObservabilityHandle> {\n  const config = resolveObservabilityConfig(env);\n  if (!config.enabled) {\n    return noopHandle();\n  }\n  return startSdk(config);\n}\n\nexport { resolveObservabilityConfig } from \"./config.ts\";\nexport type { ObservabilityConfig } from \"./config.ts\";\nexport type { ObservabilityHandle } from \"./types.ts\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAqBA,SAAS,aAAkC;CACzC,OAAO;EACL,SAAS;EACT,UAAU,YAA2B;GACnC,MAAM,QAAQ,QAAQ;EACxB;CACF;AACF;;AAGA,SAAS,gBAAgB,QAGvB;CACA,OAAO;EACL,KAAK,OAAO,WAAW,GAAG,OAAO,SAAS,cAAc,KAAA;EACxD,SAAS,OAAO;CAClB;AACF;;AAGA,SAAS,SAAS,QAAkD;CAClE,MAAM,WAAW,uBAAuB;GACrC,oBAAoB,OAAO;EAC5B,GAAI,OAAO,iBAAiB,GAAG,uBAAuB,OAAO,eAAe,IAAI,CAAC;EACjF,GAAI,QAAQ,IAAI,cACZ,GAAG,mCAAmC,QAAQ,IAAI,YAAY,IAC9D,CAAC;CACP,CAAC;CACD,MAAM,MAAM,IAAI,QAAQ;EACtB;EACA,eAAe,IAAI,kBAAkB,gBAAgB,MAAM,CAAC;EAC5D,eAAe,CACb,IAAI,8BAA8B;GAChC,UAAU,IAAI,mBAAmB;IAC/B,KAAK,OAAO,WAAW,GAAG,OAAO,SAAS,eAAe,KAAA;IACzD,SAAS,OAAO;GAClB,CAAC;GACD,sBAAsB,OAAO;EAC/B,CAAC,CACH;CACF,CAAC;CACD,IAAI,MAAM;CACV,IAAI,OAAO;CACX,OAAO;EACL,SAAS;EACT,UAAU,YAA2B;GACnC,IAAI,MACF;GAEF,OAAO;GACP,MAAM,IAAI,SAAS;EACrB;CACF;AACF;;;;;;;;;;;;AAcA,eAAsB,yBACpB,MAAyB,QAAQ,KACH;CAC9B,MAAM,SAAS,2BAA2B,GAAG;CAC7C,IAAI,CAAC,OAAO,SACV,OAAO,WAAW;CAEpB,OAAO,SAAS,MAAM;AACxB"}

package/dist/propagate.d.mts

@@ -0,0 +1,24 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Context } from "@opentelemetry/api";
+//#region src/propagate.d.ts
+/** W3C traceparent header name. */
+declare const TRACEPARENT_HEADER = "traceparent";
+/**
+ * Resolve the parent context from an inbound `traceparent` value.
+ *
+ * @param traceparent - W3C value from a queue payload; undefined keeps context.
+ * @returns The extracted remote context, or the active context when absent.
+ */
+declare function parentContext(traceparent?: string): Context;
+/** Inject the active span context into a mutable header record. */
+declare function injectTraceContext(headers: Record<string, string>): void;
+/**
+ * Read the current W3C `traceparent` value for queue payloads.
+ *
+ * @returns The header value, or undefined when no span is active.
+ */
+declare function currentTraceparent(): string | undefined;
+//#endregion
+export { TRACEPARENT_HEADER, currentTraceparent, injectTraceContext, parentContext };
+//# sourceMappingURL=propagate.d.mts.map

package/dist/propagate.mjs

@@ -0,0 +1,42 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { context, propagation } from "@opentelemetry/api";
+//#region src/propagate.ts
+/**
+* W3C trace-context propagation helpers.
+*
+* Queue payloads carry the `traceparent` string (see `CaptureJob`) so a
+* remote worker can continue the enqueueing request's trace; outbound HTTP
+* injects the same header via {@link injectTraceContext}.
+*/
+/** W3C traceparent header name. */
+const TRACEPARENT_HEADER = "traceparent";
+/**
+* Resolve the parent context from an inbound `traceparent` value.
+*
+* @param traceparent - W3C value from a queue payload; undefined keeps context.
+* @returns The extracted remote context, or the active context when absent.
+*/
+function parentContext(traceparent) {
+	if (!traceparent) return context.active();
+	return propagation.extract(context.active(), { [TRACEPARENT_HEADER]: traceparent });
+}
+/** Inject the active span context into a mutable header record. */
+function injectTraceContext(headers) {
+	propagation.inject(context.active(), headers);
+}
+/**
+* Read the current W3C `traceparent` value for queue payloads.
+*
+* @returns The header value, or undefined when no span is active.
+*/
+function currentTraceparent() {
+	const carrier = {};
+	propagation.inject(context.active(), carrier);
+	return carrier[TRACEPARENT_HEADER];
+}
+//#endregion
+export { TRACEPARENT_HEADER, currentTraceparent, injectTraceContext, parentContext };
+
+//# sourceMappingURL=propagate.mjs.map

package/dist/propagate.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"propagate.mjs","names":[],"sources":["../src/propagate.ts"],"sourcesContent":["/**\n * W3C trace-context propagation helpers.\n *\n * Queue payloads carry the `traceparent` string (see `CaptureJob`) so a\n * remote worker can continue the enqueueing request's trace; outbound HTTP\n * injects the same header via {@link injectTraceContext}.\n */\nimport { context, propagation, type Context } from \"@opentelemetry/api\";\n\n/** W3C traceparent header name. */\nexport const TRACEPARENT_HEADER = \"traceparent\";\n\n/**\n * Resolve the parent context from an inbound `traceparent` value.\n *\n * @param traceparent - W3C value from a queue payload; undefined keeps context.\n * @returns The extracted remote context, or the active context when absent.\n */\nexport function parentContext(traceparent?: string): Context {\n  if (!traceparent) {\n    return context.active();\n  }\n  return propagation.extract(context.active(), { [TRACEPARENT_HEADER]: traceparent });\n}\n\n/** Inject the active span context into a mutable header record. */\nexport function injectTraceContext(headers: Record<string, string>): void {\n  propagation.inject(context.active(), headers);\n}\n\n/**\n * Read the current W3C `traceparent` value for queue payloads.\n *\n * @returns The header value, or undefined when no span is active.\n */\nexport function currentTraceparent(): string | undefined {\n  const carrier: Record<string, string> = {};\n  propagation.inject(context.active(), carrier);\n  return carrier[TRACEPARENT_HEADER];\n}\n"],"mappings":";;;;;;;;;;;;;AAUA,MAAa,qBAAqB;;;;;;;AAQlC,SAAgB,cAAc,aAA+B;CAC3D,IAAI,CAAC,aACH,OAAO,QAAQ,OAAO;CAExB,OAAO,YAAY,QAAQ,QAAQ,OAAO,GAAG,GAAG,qBAAqB,YAAY,CAAC;AACpF;;AAGA,SAAgB,mBAAmB,SAAuC;CACxE,YAAY,OAAO,QAAQ,OAAO,GAAG,OAAO;AAC9C;;;;;;AAOA,SAAgB,qBAAyC;CACvD,MAAM,UAAkC,CAAC;CACzC,YAAY,OAAO,QAAQ,OAAO,GAAG,OAAO;CAC5C,OAAO,QAAQ;AACjB"}

package/dist/tracing.d.mts

@@ -0,0 +1,20 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Attributes, Context, Span } from "@opentelemetry/api";
+//#region src/tracing.d.ts
+/**
+ * Run `fn` inside an internal span.
+ *
+ * On throw the span records the exception, is marked ERROR, and the error
+ * is rethrown — mirroring the pino `{ err }` convention.
+ *
+ * @param name - Span name (`domain.operation`, never a high-cardinality value).
+ * @param fn - Work to run with the span active.
+ * @param attributes - Fixed span attributes (no high-cardinality values in names).
+ * @param parent - Parent context (defaults to the active context).
+ * @returns Whatever `fn` returns.
+ */
+declare function withSpan<T>(name: string, fn: (span: Span) => Promise<T>, attributes?: Attributes, parent?: Context): Promise<T>;
+//#endregion
+export { withSpan };
+//# sourceMappingURL=tracing.d.mts.map

package/dist/tracing.mjs

@@ -0,0 +1,44 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { SpanKind, SpanStatusCode, context, trace } from "@opentelemetry/api";
+//#region src/tracing.ts
+/**
+* Span helpers over `@opentelemetry/api` (runtime-agnostic: Node SDK or
+* Deno's native bridge). Without a configured provider these are cheap
+* noops, so call sites need no enabled-checks.
+*/
+/** Instrumentation scope for observability-package spans. */
+const SCOPE = "storyshelf.observability";
+/**
+* Run `fn` inside an internal span.
+*
+* On throw the span records the exception, is marked ERROR, and the error
+* is rethrown — mirroring the pino `{ err }` convention.
+*
+* @param name - Span name (`domain.operation`, never a high-cardinality value).
+* @param fn - Work to run with the span active.
+* @param attributes - Fixed span attributes (no high-cardinality values in names).
+* @param parent - Parent context (defaults to the active context).
+* @returns Whatever `fn` returns.
+*/
+async function withSpan(name, fn, attributes, parent) {
+	return await trace.getTracer(SCOPE).startActiveSpan(name, {
+		kind: SpanKind.INTERNAL,
+		attributes
+	}, parent ?? context.active(), async (span) => {
+		try {
+			return await fn(span);
+		} catch (error) {
+			span.recordException(error instanceof Error ? error : String(error));
+			span.setStatus({ code: SpanStatusCode.ERROR });
+			throw error;
+		} finally {
+			span.end();
+		}
+	});
+}
+//#endregion
+export { withSpan };
+
+//# sourceMappingURL=tracing.mjs.map

package/dist/tracing.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.mjs","names":[],"sources":["../src/tracing.ts"],"sourcesContent":["/**\n * Span helpers over `@opentelemetry/api` (runtime-agnostic: Node SDK or\n * Deno's native bridge). Without a configured provider these are cheap\n * noops, so call sites need no enabled-checks.\n */\nimport {\n  SpanKind,\n  SpanStatusCode,\n  context,\n  trace,\n  type Attributes,\n  type Context,\n  type Span,\n} from \"@opentelemetry/api\";\n\n/** Instrumentation scope for observability-package spans. */\nconst SCOPE = \"storyshelf.observability\";\n\n/**\n * Run `fn` inside an internal span.\n *\n * On throw the span records the exception, is marked ERROR, and the error\n * is rethrown — mirroring the pino `{ err }` convention.\n *\n * @param name - Span name (`domain.operation`, never a high-cardinality value).\n * @param fn - Work to run with the span active.\n * @param attributes - Fixed span attributes (no high-cardinality values in names).\n * @param parent - Parent context (defaults to the active context).\n * @returns Whatever `fn` returns.\n */\nexport async function withSpan<T>(\n  name: string,\n  fn: (span: Span) => Promise<T>,\n  attributes?: Attributes,\n  parent?: Context,\n): Promise<T> {\n  const tracer = trace.getTracer(SCOPE);\n  return await tracer.startActiveSpan(\n    name,\n    { kind: SpanKind.INTERNAL, attributes },\n    parent ?? context.active(),\n    async (span) => {\n      try {\n        return await fn(span);\n      } catch (error) {\n        span.recordException(error instanceof Error ? error : String(error));\n        span.setStatus({ code: SpanStatusCode.ERROR });\n        throw error;\n      } finally {\n        span.end();\n      }\n    },\n  );\n}\n"],"mappings":";;;;;;;;;;;AAgBA,MAAM,QAAQ;;;;;;;;;;;;;AAcd,eAAsB,SACpB,MACA,IACA,YACA,QACY;CAEZ,OAAO,MADQ,MAAM,UAAU,KACb,CAAC,CAAC,gBAClB,MACA;EAAE,MAAM,SAAS;EAAU;CAAW,GACtC,UAAU,QAAQ,OAAO,GACzB,OAAO,SAAS;EACd,IAAI;GACF,OAAO,MAAM,GAAG,IAAI;EACtB,SAAS,OAAO;GACd,KAAK,gBAAgB,iBAAiB,QAAQ,QAAQ,OAAO,KAAK,CAAC;GACnE,KAAK,UAAU,EAAE,MAAM,eAAe,MAAM,CAAC;GAC7C,MAAM;EACR,UAAU;GACR,KAAK,IAAI;EACX;CACF,CACF;AACF"}

package/dist/types.d.mts

@@ -0,0 +1,23 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Attributes } from "@opentelemetry/api";
+//#region src/types.d.ts
+/** Attributes attached to a span or metric measurement. */
+type SpanAttributes = Attributes;
+/** Shutdown handle for the observability SDK (see `node.ts`). */
+interface ObservabilityHandle {
+  /** Whether the SDK is active (false = noop: no endpoint configured or Deno runtime). */
+  readonly enabled: boolean;
+  /** Flush exporters and release SDK resources. Idempotent. */
+  shutdown(): Promise<void>;
+}
+/** Options for the Hono HTTP middleware (`middleware.ts`). */
+interface HttpMiddlewareOptions {
+  /** Service name in spans/metrics. Defaults to `OTEL_SERVICE_NAME` resolution. */
+  serviceName?: string;
+  /** Service version in spans/metrics. Defaults to the package version. */
+  serviceVersion?: string;
+}
+//#endregion
+export { HttpMiddlewareOptions, ObservabilityHandle, SpanAttributes };
+//# sourceMappingURL=types.d.mts.map

package/package.json

@@ -1,6 +1,96 @@
 {
   "name": "@storyshelf/observability",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.4",
+  "description": "StoryShelf observability: OpenTelemetry tracing, metrics, and log correlation over @storyshelf/core adapters.",
+  "keywords": [
+    "metrics",
+    "observability",
+    "opentelemetry",
+    "self-hosted",
+    "storybook",
+    "tracing",
+    "visual-testing"
+  ],
+  "homepage": "https://github.com/GuptaSiddhant/StoryShelf#readme",
+  "bugs": {
+    "url": "https://github.com/GuptaSiddhant/StoryShelf/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Siddhant Gupta",
+    "url": "https://guptasiddhant.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GuptaSiddhant/StoryShelf.git",
+    "directory": "packages/observability"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./node": {
+      "source": "./src/node.ts",
+      "default": "./dist/node.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.mjs",
+      "./node": "./dist/node.mjs",
+      "./package.json": "./package.json"
+    },
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown -w",
+    "fmt": "oxfmt ./src",
+    "lint": "oxlint --type-aware --type-check ./src",
+    "prepublishOnly": "nub run build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@hono/otel": "^1.1.2",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/resources": "^2.11.0",
+    "@opentelemetry/sdk-metrics": "^2.11.0",
+    "@opentelemetry/sdk-node": "^0.222.0",
+    "@opentelemetry/semantic-conventions": "^1.43.0",
+    "@storyshelf/core": "0.5.4",
+    "drizzle-orm": "^0.44.0",
+    "hono": "^4.11.0"
+  },
+  "devDependencies": {
+    "@opentelemetry/context-async-hooks": "^2.11.0",
+    "@opentelemetry/core": "^2.11.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.222.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.222.0",
+    "@opentelemetry/sdk-trace-base": "^2.11.0",
+    "@types/node": "^26.0.0",
+    "@vitest/coverage-v8": "^4.0.0",
+    "oxfmt": "^0.65.0",
+    "oxlint": "^1.80.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  },
+  "jsr": {
+    "runtimeCompat": {
+      "node": true,
+      "deno": true,
+      "bun": true,
+      "workerd": false,
+      "browser": false
+    }
+  }
+}