@nightowlsdev/telemetry-core 0.1.2

package/LICENSE

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

package/README.md

@@ -0,0 +1,84 @@
+# @nightowlsdev/telemetry-core
+
+The shared **SwarmSpan → OpenTelemetry replay** for the Night Owls telemetry family. When a
+swarm run finishes, `@nightowlsdev/core`'s engine hands a batch of pre-recorded `SwarmSpan`s
+(one `run`, one `generation` per model call, one `tool` per tool call) to a
+`TelemetryExporter`. This package replays those spans through a `BasicTracerProvider` as
+real OpenTelemetry spans: it derives a valid 32-hex trace id from the run id, nests the
+children under the run span, and maps generations to `gen_ai.*` semantic conventions. The
+two backend adapters (`@nightowlsdev/telemetry-otel`, `@nightowlsdev/telemetry-langfuse`) are thin
+shells over this — they differ only in the `SpanProcessor` they pass in.
+
+It never imports `@mastra/*` and re-exports no Mastra types (the engine wall, CONTRACTS §1).
+
+## Install
+
+```bash
+pnpm add @nightowlsdev/telemetry-core @nightowlsdev/core
+```
+
+OpenTelemetry (`@opentelemetry/api`, `@opentelemetry/sdk-trace-base`,
+`@opentelemetry/resources`, `@opentelemetry/semantic-conventions`) ships as a dependency.
+
+## What it does
+
+- **`deriveTraceId(runId)`** — a UUID run id becomes its dash-stripped 32-lowercase-hex form;
+  any other run id is sha256-hashed to 32 hex. Deterministic, so a run always maps to the
+  same trace.
+- **`createSpanReplayer({ exporter | processor, serviceName?, resourceAttributes? })`** —
+  builds a long-lived provider. `replay(spans)` groups spans by run id, forces the derived
+  trace id via a synthetic parent `SpanContext`, opens the `run` span first and parents the
+  `generation`/`tool` children under it (`trace.setSpan`), replays the original epoch-ms
+  timings, then **awaits `provider.forceFlush()`** so nothing is lost in a short-lived /
+  serverless invocation.
+- **`replayerExporter(opts)`** — wraps a replayer as a `TelemetryExporter` so an adapter can
+  return it directly from its factory.
+- **gen_ai mapping** — generation spans carry `gen_ai.request.model`,
+  `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens` (from
+  `@opentelemetry/semantic-conventions/incubating`) plus `gen_ai.usage.cost_usd`, so both
+  OTLP backends and Langfuse's default `gen_ai.*` filter pick them up.
+
+## Usage (building an adapter)
+
+```ts
+import { replayerExporter } from "@nightowlsdev/telemetry-core";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+
+export function myTelemetry(opts) {
+  const processor = new BatchSpanProcessor(new OTLPTraceExporter({ url: opts.url }));
+  return replayerExporter({ processor, serviceName: "nightowls" });
+}
+```
+
+You usually don't depend on this package directly — use `@nightowlsdev/telemetry-otel` or
+`@nightowlsdev/telemetry-langfuse`, then wire it into `defineSwarm({ telemetry })`.
+
+## Multi-backend: send to OTLP **and** Langfuse at once
+
+`@nightowlsdev/core`'s `compositeTelemetry` fans one span batch out to many exporters, isolating
+each one (`Promise.allSettled` — a throwing exporter never blocks the others or the run):
+
+```ts
+import { defineSwarm, compositeTelemetry } from "@nightowlsdev/core";
+import { otelTelemetry } from "@nightowlsdev/telemetry-otel";
+import { langfuseTelemetry } from "@nightowlsdev/telemetry-langfuse";
+
+const swarm = defineSwarm({
+  storage, agents, models: { allow: ["openai/gpt-5.5"] }, modelFactory,
+  cost: { maxSteps: 8, maxCostUsd: 1 },
+  telemetry: compositeTelemetry([
+    otelTelemetry({ url, headers }),
+    langfuseTelemetry({ publicKey, secretKey }),
+  ]),
+});
+```
+
+`defineSwarm({ telemetry })` also accepts a bare array (`telemetry: [otelTelemetry(...),
+langfuseTelemetry(...)]`) — it's composed the same way. `customTelemetry(fn)` wraps any
+`(spans) => void | Promise<void>` into an exporter.
+
+## Engine wall
+
+The built `dist/index.d.ts` contains zero `@mastra` references (enforced by
+`test/wall.test.ts`). It consumes only `@nightowlsdev/core`'s `SwarmSpan`/`TelemetryExporter`.

package/dist/index.cjs

@@ -0,0 +1,146 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  KIND_MAP: () => KIND_MAP,
+  createSpanReplayer: () => createSpanReplayer,
+  deriveRootSpanId: () => deriveRootSpanId,
+  deriveTraceId: () => deriveTraceId,
+  replayerExporter: () => replayerExporter,
+  toOtelAttributes: () => toOtelAttributes
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/replay.ts
+var import_api2 = require("@opentelemetry/api");
+var import_sdk_trace_base = require("@opentelemetry/sdk-trace-base");
+var import_resources = require("@opentelemetry/resources");
+
+// src/trace-id.ts
+var import_node_crypto = require("crypto");
+var HEX32 = /^[0-9a-f]{32}$/;
+function deriveTraceId(runId) {
+  const stripped = runId.replace(/-/g, "").toLowerCase();
+  if (HEX32.test(stripped)) return stripped;
+  return (0, import_node_crypto.createHash)("sha256").update(runId).digest("hex").slice(0, 32);
+}
+function deriveRootSpanId(runId) {
+  return (0, import_node_crypto.createHash)("sha256").update(`root:${runId}`).digest("hex").slice(0, 16);
+}
+
+// src/attributes.ts
+var import_api = require("@opentelemetry/api");
+var import_incubating = require("@opentelemetry/semantic-conventions/incubating");
+var KIND_MAP = {
+  run: import_api.SpanKind.INTERNAL,
+  delegation: import_api.SpanKind.INTERNAL,
+  generation: import_api.SpanKind.INTERNAL,
+  tool: import_api.SpanKind.CLIENT,
+  event: import_api.SpanKind.INTERNAL,
+  recall: import_api.SpanKind.INTERNAL
+  // R4: a memory recall is an internal read (like run/event)
+};
+function coerce(v) {
+  if (v == null) return void 0;
+  if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") return v;
+  return JSON.stringify(v);
+}
+function toOtelAttributes(span) {
+  const out = { "nightowls.span.kind": span.kind };
+  for (const [k, v] of Object.entries(span.attributes)) {
+    const c = coerce(v);
+    if (c !== void 0) out[k] = c;
+  }
+  if (span.kind === "generation") {
+    const a = span.attributes;
+    if (typeof a.modelId === "string") out[import_incubating.ATTR_GEN_AI_REQUEST_MODEL] = a.modelId;
+    if (typeof a.inputTokens === "number") out[import_incubating.ATTR_GEN_AI_USAGE_INPUT_TOKENS] = a.inputTokens;
+    if (typeof a.outputTokens === "number") out[import_incubating.ATTR_GEN_AI_USAGE_OUTPUT_TOKENS] = a.outputTokens;
+    if (typeof a.costUsd === "number") out["gen_ai.usage.cost_usd"] = a.costUsd;
+  }
+  return out;
+}
+
+// src/replay.ts
+function createSpanReplayer(opts) {
+  const processor = opts.processor ?? new import_sdk_trace_base.SimpleSpanProcessor(
+    opts.exporter ?? (() => {
+      throw new Error("createSpanReplayer needs `exporter` or `processor`");
+    })()
+  );
+  const provider = new import_sdk_trace_base.BasicTracerProvider({
+    resource: (0, import_resources.resourceFromAttributes)({
+      "service.name": opts.serviceName ?? "nightowls",
+      ...opts.resourceAttributes
+    }),
+    spanProcessors: [processor]
+  });
+  const tracer = provider.getTracer("@nightowlsdev/telemetry");
+  return {
+    async replay(spans) {
+      if (spans.length === 0) return;
+      const groups = /* @__PURE__ */ new Map();
+      for (const s of spans) {
+        const g = groups.get(s.traceId);
+        if (g) g.push(s);
+        else groups.set(s.traceId, [s]);
+      }
+      for (const [runId, group] of groups) {
+        const traceId = deriveTraceId(runId);
+        const rootSc = {
+          traceId,
+          spanId: deriveRootSpanId(runId),
+          traceFlags: import_api2.TraceFlags.SAMPLED,
+          isRemote: false
+        };
+        const rootCtx = import_api2.trace.setSpanContext(import_api2.context.active(), rootSc);
+        const ordered = [...group].sort(
+          (a, b) => a.kind === "run" ? -1 : b.kind === "run" ? 1 : a.startedAt - b.startedAt
+        );
+        let runSpan;
+        for (const sw of ordered) {
+          const parentCtx = sw.kind === "run" || !runSpan ? rootCtx : import_api2.trace.setSpan(import_api2.context.active(), runSpan);
+          const span = tracer.startSpan(sw.name, { kind: KIND_MAP[sw.kind], startTime: sw.startedAt }, parentCtx);
+          span.setAttributes(toOtelAttributes(sw));
+          span.end(sw.endedAt ?? sw.startedAt);
+          if (sw.kind === "run") runSpan = span;
+        }
+      }
+      await provider.forceFlush();
+    },
+    async shutdown() {
+      await provider.shutdown();
+    }
+  };
+}
+function replayerExporter(opts) {
+  const replayer = createSpanReplayer(opts);
+  return { export: (spans) => replayer.replay(spans) };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  KIND_MAP,
+  createSpanReplayer,
+  deriveRootSpanId,
+  deriveTraceId,
+  replayerExporter,
+  toOtelAttributes
+});

package/dist/index.d.cts

@@ -0,0 +1,30 @@
+import { SpanExporter, SpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { SwarmSpan, TelemetryExporter } from '@nightowlsdev/core';
+import { SpanKind, Attributes } from '@opentelemetry/api';
+
+interface SpanReplayerOpts {
+    /** Provide a SpanExporter (telemetry-otel: OTLP) OR a full SpanProcessor (telemetry-langfuse). */
+    exporter?: SpanExporter;
+    processor?: SpanProcessor;
+    serviceName?: string;
+    resourceAttributes?: Record<string, string>;
+}
+interface SpanReplayer {
+    replay(spans: SwarmSpan[]): Promise<void>;
+    shutdown(): Promise<void>;
+}
+/** Build a long-lived provider; `replay` re-plays a batch of pre-recorded SwarmSpans as real OTel spans. */
+declare function createSpanReplayer(opts: SpanReplayerOpts): SpanReplayer;
+/** Convenience: wrap a replayer as a TelemetryExporter (so adapters export directly). */
+declare function replayerExporter(opts: SpanReplayerOpts): TelemetryExporter;
+
+/** Derive a valid 32-lowercase-hex OTel trace id from any runId (UUID → strip dashes; else sha256). */
+declare function deriveTraceId(runId: string): string;
+/** Derive a stable 16-hex span id for the synthetic trace root (so the run span has a parent to anchor the traceId). */
+declare function deriveRootSpanId(runId: string): string;
+
+declare const KIND_MAP: Record<SwarmSpan["kind"], SpanKind>;
+/** Map a SwarmSpan's attributes to OTel attributes, lifting generation usage/model/cost to gen_ai.* semconv. */
+declare function toOtelAttributes(span: SwarmSpan): Attributes;
+
+export { KIND_MAP, type SpanReplayer, type SpanReplayerOpts, createSpanReplayer, deriveRootSpanId, deriveTraceId, replayerExporter, toOtelAttributes };

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { SpanExporter, SpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { SwarmSpan, TelemetryExporter } from '@nightowlsdev/core';
+import { SpanKind, Attributes } from '@opentelemetry/api';
+
+interface SpanReplayerOpts {
+    /** Provide a SpanExporter (telemetry-otel: OTLP) OR a full SpanProcessor (telemetry-langfuse). */
+    exporter?: SpanExporter;
+    processor?: SpanProcessor;
+    serviceName?: string;
+    resourceAttributes?: Record<string, string>;
+}
+interface SpanReplayer {
+    replay(spans: SwarmSpan[]): Promise<void>;
+    shutdown(): Promise<void>;
+}
+/** Build a long-lived provider; `replay` re-plays a batch of pre-recorded SwarmSpans as real OTel spans. */
+declare function createSpanReplayer(opts: SpanReplayerOpts): SpanReplayer;
+/** Convenience: wrap a replayer as a TelemetryExporter (so adapters export directly). */
+declare function replayerExporter(opts: SpanReplayerOpts): TelemetryExporter;
+
+/** Derive a valid 32-lowercase-hex OTel trace id from any runId (UUID → strip dashes; else sha256). */
+declare function deriveTraceId(runId: string): string;
+/** Derive a stable 16-hex span id for the synthetic trace root (so the run span has a parent to anchor the traceId). */
+declare function deriveRootSpanId(runId: string): string;
+
+declare const KIND_MAP: Record<SwarmSpan["kind"], SpanKind>;
+/** Map a SwarmSpan's attributes to OTel attributes, lifting generation usage/model/cost to gen_ai.* semconv. */
+declare function toOtelAttributes(span: SwarmSpan): Attributes;
+
+export { KIND_MAP, type SpanReplayer, type SpanReplayerOpts, createSpanReplayer, deriveRootSpanId, deriveTraceId, replayerExporter, toOtelAttributes };

package/dist/index.js

@@ -0,0 +1,121 @@
+// src/replay.ts
+import { context, trace, TraceFlags } from "@opentelemetry/api";
+import {
+  BasicTracerProvider,
+  SimpleSpanProcessor
+} from "@opentelemetry/sdk-trace-base";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+
+// src/trace-id.ts
+import { createHash } from "crypto";
+var HEX32 = /^[0-9a-f]{32}$/;
+function deriveTraceId(runId) {
+  const stripped = runId.replace(/-/g, "").toLowerCase();
+  if (HEX32.test(stripped)) return stripped;
+  return createHash("sha256").update(runId).digest("hex").slice(0, 32);
+}
+function deriveRootSpanId(runId) {
+  return createHash("sha256").update(`root:${runId}`).digest("hex").slice(0, 16);
+}
+
+// src/attributes.ts
+import { SpanKind } from "@opentelemetry/api";
+import {
+  ATTR_GEN_AI_REQUEST_MODEL,
+  ATTR_GEN_AI_USAGE_INPUT_TOKENS,
+  ATTR_GEN_AI_USAGE_OUTPUT_TOKENS
+} from "@opentelemetry/semantic-conventions/incubating";
+var KIND_MAP = {
+  run: SpanKind.INTERNAL,
+  delegation: SpanKind.INTERNAL,
+  generation: SpanKind.INTERNAL,
+  tool: SpanKind.CLIENT,
+  event: SpanKind.INTERNAL,
+  recall: SpanKind.INTERNAL
+  // R4: a memory recall is an internal read (like run/event)
+};
+function coerce(v) {
+  if (v == null) return void 0;
+  if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") return v;
+  return JSON.stringify(v);
+}
+function toOtelAttributes(span) {
+  const out = { "nightowls.span.kind": span.kind };
+  for (const [k, v] of Object.entries(span.attributes)) {
+    const c = coerce(v);
+    if (c !== void 0) out[k] = c;
+  }
+  if (span.kind === "generation") {
+    const a = span.attributes;
+    if (typeof a.modelId === "string") out[ATTR_GEN_AI_REQUEST_MODEL] = a.modelId;
+    if (typeof a.inputTokens === "number") out[ATTR_GEN_AI_USAGE_INPUT_TOKENS] = a.inputTokens;
+    if (typeof a.outputTokens === "number") out[ATTR_GEN_AI_USAGE_OUTPUT_TOKENS] = a.outputTokens;
+    if (typeof a.costUsd === "number") out["gen_ai.usage.cost_usd"] = a.costUsd;
+  }
+  return out;
+}
+
+// src/replay.ts
+function createSpanReplayer(opts) {
+  const processor = opts.processor ?? new SimpleSpanProcessor(
+    opts.exporter ?? (() => {
+      throw new Error("createSpanReplayer needs `exporter` or `processor`");
+    })()
+  );
+  const provider = new BasicTracerProvider({
+    resource: resourceFromAttributes({
+      "service.name": opts.serviceName ?? "nightowls",
+      ...opts.resourceAttributes
+    }),
+    spanProcessors: [processor]
+  });
+  const tracer = provider.getTracer("@nightowlsdev/telemetry");
+  return {
+    async replay(spans) {
+      if (spans.length === 0) return;
+      const groups = /* @__PURE__ */ new Map();
+      for (const s of spans) {
+        const g = groups.get(s.traceId);
+        if (g) g.push(s);
+        else groups.set(s.traceId, [s]);
+      }
+      for (const [runId, group] of groups) {
+        const traceId = deriveTraceId(runId);
+        const rootSc = {
+          traceId,
+          spanId: deriveRootSpanId(runId),
+          traceFlags: TraceFlags.SAMPLED,
+          isRemote: false
+        };
+        const rootCtx = trace.setSpanContext(context.active(), rootSc);
+        const ordered = [...group].sort(
+          (a, b) => a.kind === "run" ? -1 : b.kind === "run" ? 1 : a.startedAt - b.startedAt
+        );
+        let runSpan;
+        for (const sw of ordered) {
+          const parentCtx = sw.kind === "run" || !runSpan ? rootCtx : trace.setSpan(context.active(), runSpan);
+          const span = tracer.startSpan(sw.name, { kind: KIND_MAP[sw.kind], startTime: sw.startedAt }, parentCtx);
+          span.setAttributes(toOtelAttributes(sw));
+          span.end(sw.endedAt ?? sw.startedAt);
+          if (sw.kind === "run") runSpan = span;
+        }
+      }
+      await provider.forceFlush();
+    },
+    async shutdown() {
+      await provider.shutdown();
+    }
+  };
+}
+function replayerExporter(opts) {
+  const replayer = createSpanReplayer(opts);
+  return { export: (spans) => replayer.replay(spans) };
+}
+export {
+  KIND_MAP,
+  createSpanReplayer,
+  deriveRootSpanId,
+  deriveTraceId,
+  replayerExporter,
+  toOtelAttributes
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@nightowlsdev/telemetry-core",
+  "version": "0.1.2",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cueplusplus/corale.git",
+    "directory": "packages/telemetry-core"
+  },
+  "homepage": "https://github.com/cueplusplus/corale#readme",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^2.0.1",
+    "@opentelemetry/sdk-trace-base": "^2.0.1",
+    "@opentelemetry/resources": "^2.0.1",
+    "@opentelemetry/semantic-conventions": "^1.36.0"
+  },
+  "peerDependencies": {
+    "@nightowlsdev/core": "0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.4",
+    "tsup": "8.5.1",
+    "typescript": "6.0.3",
+    "vitest": "^3.2.0",
+    "@nightowlsdev/core": "0.3.0",
+    "@nightowlsdev/tsconfig": "0.0.0",
+    "@nightowlsdev/eslint-config": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src"
+  }
+}