@nightowlsdev/telemetry-otel 0.1.1

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,59 @@
+# @nightowlsdev/telemetry-otel
+
+An **OTLP/HTTP** telemetry exporter for `@nightowlsdev/core`. It maps a swarm run's
+`run`/`generation`/`tool` `SwarmSpan`s to OpenTelemetry spans (via
+`@nightowlsdev/telemetry-core`) and ships them over OTLP to any compatible backend — Datadog,
+New Relic, Honeycomb, Grafana Tempo, Jaeger, or a plain OpenTelemetry Collector — by
+changing the `url` + `headers`. Generation spans carry `gen_ai.*` semantic-convention
+attributes (model + input/output token usage + cost), so traces land with the LLM context
+your APM already understands.
+
+It never imports `@mastra/*` and re-exports no Mastra types (the engine wall, CONTRACTS §1).
+
+## Install
+
+```bash
+pnpm add @nightowlsdev/telemetry-otel @nightowlsdev/core
+```
+
+## Factory
+
+```ts
+import { otelTelemetry } from "@nightowlsdev/telemetry-otel";
+
+const telemetry = otelTelemetry({
+  url: "https://otlp.example.com/v1/traces", // OTLP/HTTP traces endpoint
+  headers: { "x-api-key": process.env.OTLP_KEY! },
+  serviceName: "nightowls",                     // optional (default "nightowls")
+  resourceAttributes: { "deployment.environment": "prod" }, // optional
+});
+```
+
+Spans are exported through a `BatchSpanProcessor`; the replayer **awaits `forceFlush()`**
+after each run's batch so spans aren't lost in a serverless / short-lived invocation.
+
+## Wiring into a swarm
+
+```ts
+import { defineSwarm } from "@nightowlsdev/core";
+import { otelTelemetry } from "@nightowlsdev/telemetry-otel";
+
+const swarm = defineSwarm({
+  storage,
+  agents,
+  models: { allow: ["openai/gpt-5.5"] },
+  modelFactory,
+  cost: { maxSteps: 8, maxCostUsd: 1 },
+  telemetry: otelTelemetry({ url, headers }),
+});
+```
+
+`telemetry` accepts one exporter or an array — see `@nightowlsdev/telemetry-core` /
+`compositeTelemetry` for multi-backend fan-out. Telemetry is **best-effort**: a throwing or
+hung exporter never breaks the run (the engine exports in a `finally` and swallows export
+errors).
+
+## Engine wall
+
+The built `dist/index.d.ts` contains zero `@mastra` references (enforced by
+`test/wall.test.ts`).

package/dist/index.cjs

@@ -0,0 +1,84 @@
+"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, {
+  nightOwlsPlugin: () => nightOwlsPlugin,
+  otelTelemetry: () => otelTelemetry
+});
+module.exports = __toCommonJS(index_exports);
+var import_sdk_trace_base = require("@opentelemetry/sdk-trace-base");
+var import_exporter_trace_otlp_http = require("@opentelemetry/exporter-trace-otlp-http");
+var import_telemetry_core = require("@nightowlsdev/telemetry-core");
+
+// src/plugin.ts
+var nightOwlsPlugin = {
+  name: "telemetry-otel",
+  version: "0.0.0",
+  kind: "telemetry",
+  pkg: "@nightowlsdev/telemetry-otel",
+  description: "OpenTelemetry/OTLP exporter (Datadog, Honeycomb, Grafana, New Relic, \u2026).",
+  env: [
+    {
+      key: "OTEL_EXPORTER_OTLP_ENDPOINT",
+      example: "http://localhost:4318/v1/traces",
+      comment: "OTLP/HTTP traces endpoint (your collector or vendor)"
+    },
+    {
+      key: "OTEL_EXPORTER_OTLP_HEADERS",
+      example: "",
+      comment: "optional vendor auth headers, e.g. 'x-honeycomb-team=KEY' (parse + pass via headers:)"
+    }
+  ],
+  config: {
+    import: "import { otelTelemetry } from '@nightowlsdev/telemetry-otel';",
+    snippet: "telemetry = [...(telemetry ?? []), otelTelemetry({ url: env.OTEL_EXPORTER_OTLP_ENDPOINT })];",
+    marker: "telemetry"
+  },
+  // Print-only (idempotent) — runs on init/install + `owl init telemetry-otel`. NEVER connects.
+  init: (ctx) => {
+    ctx.log(
+      "OTel telemetry wired (composes with any other telemetry adapter) \u2014 set OTEL_EXPORTER_OTLP_ENDPOINT (+ OTEL_EXPORTER_OTLP_HEADERS for vendor auth)."
+    );
+  },
+  commands: [
+    {
+      name: "info",
+      description: "Show the env + config this telemetry adapter contributes.",
+      // PURE — no network. Reads only the static manifest data.
+      run: (ctx) => {
+        ctx.log("env: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS");
+        ctx.log("config: telemetry = [...(telemetry ?? []), otelTelemetry({ url })]");
+      }
+    }
+  ]
+};
+
+// src/index.ts
+function otelTelemetry(opts = {}) {
+  const exporter = opts.exporter ?? new import_exporter_trace_otlp_http.OTLPTraceExporter({ url: opts.url, headers: opts.headers });
+  const processor = new import_sdk_trace_base.BatchSpanProcessor(exporter);
+  return (0, import_telemetry_core.replayerExporter)({ processor, serviceName: opts.serviceName, resourceAttributes: opts.resourceAttributes });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  nightOwlsPlugin,
+  otelTelemetry
+});

package/dist/index.d.cts

@@ -0,0 +1,68 @@
+import { SpanExporter } from '@opentelemetry/sdk-trace-base';
+import { TelemetryExporter } from '@nightowlsdev/core';
+
+/**
+ * The Night Owls adapter plugin manifest for the OpenTelemetry/OTLP exporter. `@nightowlsdev/cli` discovers this,
+ * dynamic-imports it, and acts on it declaratively:
+ *  - `env`     → merged into `.env.example` (idempotent, only if the KEY is absent),
+ *  - `config`  → the `import` + wiring `snippet` inserted at the `// nightowls:telemetry` marker. Telemetry
+ *                COMPOSES: the snippet pushes this exporter onto the `telemetry` array, so multiple
+ *                telemetry adapters coexist (`telemetry = [...(telemetry ?? []), otelTelemetry({...})];`),
+ *  - `init`    → a print-only hook run after the wiring (it NEVER connects to a collector),
+ *  - `commands`→ `owl telemetry-otel <cmd>` subcommands (e.g. `info` — pure, no network).
+ *
+ * This object STRUCTURALLY matches the CLI's `NightOwlsPlugin` type but does NOT import it (no dependency
+ * cycle): all codegen lives in `@nightowlsdev/cli`; this adapter stays data-only. The `init`/command handler
+ * contexts are typed STRUCTURALLY (local `Ctx`/inline shapes) — never importing `@nightowlsdev/cli`.
+ */
+/** Structural context for this adapter's pure command handlers — matches the CLI's PluginCommandContext. */
+type Ctx = {
+    cwd: string;
+    log: (m: string) => void;
+    args: string[];
+    options: Record<string, unknown>;
+};
+declare const nightOwlsPlugin: {
+    readonly name: "telemetry-otel";
+    readonly version: "0.0.0";
+    readonly kind: "telemetry";
+    readonly pkg: "@nightowlsdev/telemetry-otel";
+    readonly description: "OpenTelemetry/OTLP exporter (Datadog, Honeycomb, Grafana, New Relic, …).";
+    readonly env: readonly [{
+        readonly key: "OTEL_EXPORTER_OTLP_ENDPOINT";
+        readonly example: "http://localhost:4318/v1/traces";
+        readonly comment: "OTLP/HTTP traces endpoint (your collector or vendor)";
+    }, {
+        readonly key: "OTEL_EXPORTER_OTLP_HEADERS";
+        readonly example: "";
+        readonly comment: "optional vendor auth headers, e.g. 'x-honeycomb-team=KEY' (parse + pass via headers:)";
+    }];
+    readonly config: {
+        readonly import: "import { otelTelemetry } from '@nightowlsdev/telemetry-otel';";
+        readonly snippet: "telemetry = [...(telemetry ?? []), otelTelemetry({ url: env.OTEL_EXPORTER_OTLP_ENDPOINT })];";
+        readonly marker: "telemetry";
+    };
+    readonly init: (ctx: {
+        cwd: string;
+        log: (m: string) => void;
+    }) => void;
+    readonly commands: readonly [{
+        readonly name: "info";
+        readonly description: "Show the env + config this telemetry adapter contributes.";
+        readonly run: (ctx: Ctx) => void;
+    }];
+};
+
+interface OtelTelemetryOpts {
+    /** OTLP/HTTP traces endpoint (Datadog/New Relic/Honeycomb/Grafana/Jaeger). Default OTel Collector. */
+    url?: string;
+    headers?: Record<string, string>;
+    serviceName?: string;
+    resourceAttributes?: Record<string, string>;
+    /** Test/advanced override: provide a SpanExporter directly (skips OTLP construction). */
+    exporter?: SpanExporter;
+}
+/** Map Night Owls SwarmSpans to OTLP via OpenTelemetry. Best-effort; pairs with any OTLP-compatible backend. */
+declare function otelTelemetry(opts?: OtelTelemetryOpts): TelemetryExporter;
+
+export { type OtelTelemetryOpts, nightOwlsPlugin, otelTelemetry };

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+import { SpanExporter } from '@opentelemetry/sdk-trace-base';
+import { TelemetryExporter } from '@nightowlsdev/core';
+
+/**
+ * The Night Owls adapter plugin manifest for the OpenTelemetry/OTLP exporter. `@nightowlsdev/cli` discovers this,
+ * dynamic-imports it, and acts on it declaratively:
+ *  - `env`     → merged into `.env.example` (idempotent, only if the KEY is absent),
+ *  - `config`  → the `import` + wiring `snippet` inserted at the `// nightowls:telemetry` marker. Telemetry
+ *                COMPOSES: the snippet pushes this exporter onto the `telemetry` array, so multiple
+ *                telemetry adapters coexist (`telemetry = [...(telemetry ?? []), otelTelemetry({...})];`),
+ *  - `init`    → a print-only hook run after the wiring (it NEVER connects to a collector),
+ *  - `commands`→ `owl telemetry-otel <cmd>` subcommands (e.g. `info` — pure, no network).
+ *
+ * This object STRUCTURALLY matches the CLI's `NightOwlsPlugin` type but does NOT import it (no dependency
+ * cycle): all codegen lives in `@nightowlsdev/cli`; this adapter stays data-only. The `init`/command handler
+ * contexts are typed STRUCTURALLY (local `Ctx`/inline shapes) — never importing `@nightowlsdev/cli`.
+ */
+/** Structural context for this adapter's pure command handlers — matches the CLI's PluginCommandContext. */
+type Ctx = {
+    cwd: string;
+    log: (m: string) => void;
+    args: string[];
+    options: Record<string, unknown>;
+};
+declare const nightOwlsPlugin: {
+    readonly name: "telemetry-otel";
+    readonly version: "0.0.0";
+    readonly kind: "telemetry";
+    readonly pkg: "@nightowlsdev/telemetry-otel";
+    readonly description: "OpenTelemetry/OTLP exporter (Datadog, Honeycomb, Grafana, New Relic, …).";
+    readonly env: readonly [{
+        readonly key: "OTEL_EXPORTER_OTLP_ENDPOINT";
+        readonly example: "http://localhost:4318/v1/traces";
+        readonly comment: "OTLP/HTTP traces endpoint (your collector or vendor)";
+    }, {
+        readonly key: "OTEL_EXPORTER_OTLP_HEADERS";
+        readonly example: "";
+        readonly comment: "optional vendor auth headers, e.g. 'x-honeycomb-team=KEY' (parse + pass via headers:)";
+    }];
+    readonly config: {
+        readonly import: "import { otelTelemetry } from '@nightowlsdev/telemetry-otel';";
+        readonly snippet: "telemetry = [...(telemetry ?? []), otelTelemetry({ url: env.OTEL_EXPORTER_OTLP_ENDPOINT })];";
+        readonly marker: "telemetry";
+    };
+    readonly init: (ctx: {
+        cwd: string;
+        log: (m: string) => void;
+    }) => void;
+    readonly commands: readonly [{
+        readonly name: "info";
+        readonly description: "Show the env + config this telemetry adapter contributes.";
+        readonly run: (ctx: Ctx) => void;
+    }];
+};
+
+interface OtelTelemetryOpts {
+    /** OTLP/HTTP traces endpoint (Datadog/New Relic/Honeycomb/Grafana/Jaeger). Default OTel Collector. */
+    url?: string;
+    headers?: Record<string, string>;
+    serviceName?: string;
+    resourceAttributes?: Record<string, string>;
+    /** Test/advanced override: provide a SpanExporter directly (skips OTLP construction). */
+    exporter?: SpanExporter;
+}
+/** Map Night Owls SwarmSpans to OTLP via OpenTelemetry. Best-effort; pairs with any OTLP-compatible backend. */
+declare function otelTelemetry(opts?: OtelTelemetryOpts): TelemetryExporter;
+
+export { type OtelTelemetryOpts, nightOwlsPlugin, otelTelemetry };

package/dist/index.js

@@ -0,0 +1,58 @@
+// src/index.ts
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { replayerExporter } from "@nightowlsdev/telemetry-core";
+
+// src/plugin.ts
+var nightOwlsPlugin = {
+  name: "telemetry-otel",
+  version: "0.0.0",
+  kind: "telemetry",
+  pkg: "@nightowlsdev/telemetry-otel",
+  description: "OpenTelemetry/OTLP exporter (Datadog, Honeycomb, Grafana, New Relic, \u2026).",
+  env: [
+    {
+      key: "OTEL_EXPORTER_OTLP_ENDPOINT",
+      example: "http://localhost:4318/v1/traces",
+      comment: "OTLP/HTTP traces endpoint (your collector or vendor)"
+    },
+    {
+      key: "OTEL_EXPORTER_OTLP_HEADERS",
+      example: "",
+      comment: "optional vendor auth headers, e.g. 'x-honeycomb-team=KEY' (parse + pass via headers:)"
+    }
+  ],
+  config: {
+    import: "import { otelTelemetry } from '@nightowlsdev/telemetry-otel';",
+    snippet: "telemetry = [...(telemetry ?? []), otelTelemetry({ url: env.OTEL_EXPORTER_OTLP_ENDPOINT })];",
+    marker: "telemetry"
+  },
+  // Print-only (idempotent) — runs on init/install + `owl init telemetry-otel`. NEVER connects.
+  init: (ctx) => {
+    ctx.log(
+      "OTel telemetry wired (composes with any other telemetry adapter) \u2014 set OTEL_EXPORTER_OTLP_ENDPOINT (+ OTEL_EXPORTER_OTLP_HEADERS for vendor auth)."
+    );
+  },
+  commands: [
+    {
+      name: "info",
+      description: "Show the env + config this telemetry adapter contributes.",
+      // PURE — no network. Reads only the static manifest data.
+      run: (ctx) => {
+        ctx.log("env: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS");
+        ctx.log("config: telemetry = [...(telemetry ?? []), otelTelemetry({ url })]");
+      }
+    }
+  ]
+};
+
+// src/index.ts
+function otelTelemetry(opts = {}) {
+  const exporter = opts.exporter ?? new OTLPTraceExporter({ url: opts.url, headers: opts.headers });
+  const processor = new BatchSpanProcessor(exporter);
+  return replayerExporter({ processor, serviceName: opts.serviceName, resourceAttributes: opts.resourceAttributes });
+}
+export {
+  nightOwlsPlugin,
+  otelTelemetry
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@nightowlsdev/telemetry-otel",
+  "version": "0.1.1",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cueplusplus/corale.git",
+    "directory": "packages/telemetry-otel"
+  },
+  "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/exporter-trace-otlp-http": "^0.203.0",
+    "@opentelemetry/sdk-trace-base": "^2.0.1",
+    "@nightowlsdev/telemetry-core": "0.1.2"
+  },
+  "peerDependencies": {
+    "@nightowlsdev/core": "0.3.0"
+  },
+  "devDependencies": {
+    "@opentelemetry/core": "^2.0.1",
+    "@types/node": "^24.12.4",
+    "tsup": "8.5.1",
+    "typescript": "6.0.3",
+    "vitest": "^3.2.0",
+    "@nightowlsdev/tsconfig": "0.0.0",
+    "@nightowlsdev/eslint-config": "0.0.0",
+    "@nightowlsdev/core": "0.3.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src"
+  }
+}