@ap3x/observe-otel 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AP3X
+
+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,25 @@
+# @ap3x/observe-otel
+
+Exports `@ap3x/observe` events to any OpenTelemetry-compatible backend.
+
+Part of [AP3X](https://github.com/AP3X-Dev/AP3X) — a TypeScript multi-agent framework.
+
+## Install
+
+```bash
+npm install @ap3x/observe-otel
+```
+
+## What's inside
+
+- **`OtelExporter`** — implements the `@ap3x/observe` `Exporter` interface over `@opentelemetry/api`.
+
+Bring your own OpenTelemetry SDK and configure it as usual; this package only emits.
+
+## Documentation
+
+See the [AP3X repository](https://github.com/AP3X-Dev/AP3X) for architecture notes, the full package map, and examples.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import type { Exporter, TraceEvent } from "@ap3x/observe";
+import type { Tracer } from "@opentelemetry/api";
+export interface OtelExporterOptions {
+    tracer?: Tracer;
+}
+/**
+ * Reconstructs OTel spans from AP3X's point-event trace stream. AP3X emits a flat
+ * sequence of start/end/point events per span id; OTel wants intervals. Paired
+ * `*_start`/`*_end` events become real spans, keyed by spanId+stem+disambiguator:
+ * `tool_execution` uses its `toolCallId`; `member_run`/`struct_run` (which carry no
+ * per-invocation id) use the agent/struct name instead. Each key holds a FIFO queue
+ * of open spans rather than a single slot, so same-key concurrent starts (e.g.
+ * `SubagentRegistry.gather()` fan-out) each get their own span instead of the second
+ * start clobbering the first. Everything else is attached as a span event on the
+ * innermost open span.
+ *
+ * ponytail: parent linkage is recorded as the `ap3x.parent_span_id` attribute rather
+ * than wired through OTel's Context/trace.setSpan machinery. The injectable `tracer`
+ * here is typed against @opentelemetry/api's `Tracer`/`Span` interfaces only (no SDK
+ * dependency), and tests inject a hand-rolled fake tracer whose `startSpan` doesn't
+ * participate in real Context propagation — attribute-based linkage is what a
+ * downstream OTel backend can reconstruct real parent/child spans from, without this
+ * package needing a live Context API. Upgrade path: thread `context.active()` +
+ * `trace.setSpan` once this exporter runs against a real SDK-backed tracer.
+ */
+export declare class OtelExporter implements Exporter {
+    #private;
+    constructor(options?: OtelExporterOptions);
+    get dropped(): number;
+    onEvent(e: TraceEvent): void;
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAoB,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAGnE,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAyFD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,YAAa,YAAW,QAAQ;;gBAM/B,OAAO,CAAC,EAAE,mBAAmB;IAIzC,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,OAAO,CAAC,CAAC,EAAE,UAAU,GAAG,IAAI;IAiBtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAmE7B"}

package/dist/index.js

@@ -0,0 +1,154 @@
+// src/index.ts
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+function stemOf(name) {
+  return name.replace(/_(start|end)$/, "");
+}
+function isStart(name) {
+  return name.endsWith("_start");
+}
+function isEnd(name) {
+  return name.endsWith("_end");
+}
+var PAIRED_STEMS = /* @__PURE__ */ new Set(["agent", "turn", "tool_execution", "member_run", "struct_run"]);
+function toolCallIdOf(data) {
+  if (data && typeof data === "object" && "toolCallId" in data) {
+    const id = data.toolCallId;
+    if (typeof id === "string") return id;
+  }
+  return "";
+}
+function disambiguatorOf(e, stem) {
+  if (stem === "member_run") return e.agent?.name ?? "";
+  if (stem === "struct_run") {
+    const data = e.data;
+    if (data && typeof data === "object" && "struct" in data) {
+      const struct = data.struct;
+      if (typeof struct === "string") return struct;
+    }
+    return "";
+  }
+  return toolCallIdOf(e.data);
+}
+function isErrorEvent(data) {
+  return Boolean(
+    data && typeof data === "object" && data.isError === true
+  );
+}
+function flatAttributes(data) {
+  if (!data || typeof data !== "object") return {};
+  const out = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (value === null || value === void 0) continue;
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      out[key] = value;
+    } else {
+      try {
+        out[key] = JSON.stringify(value);
+      } catch {
+        out[key] = String(value);
+      }
+    }
+  }
+  return out;
+}
+function startAttributes(e) {
+  return {
+    "ap3x.trace_id": e.traceId,
+    "ap3x.span_id": e.spanId,
+    ...e.parentSpanId ? { "ap3x.parent_span_id": e.parentSpanId } : {},
+    "ap3x.seq": e.seq,
+    "ap3x.source": e.source,
+    ...e.agent?.name ? { "agent.name": e.agent.name } : {},
+    ...e.agent?.model ? { "agent.model": e.agent.model } : {}
+  };
+}
+var OtelExporter = class {
+  #tracer;
+  // ponytail: no invocation id in the stream — identical concurrent twins may swap durations; exact match needs an id on the events.
+  #open = /* @__PURE__ */ new Map();
+  #dropped = 0;
+  constructor(options) {
+    this.#tracer = options?.tracer ?? trace.getTracer("@ap3x/observe-otel");
+  }
+  get dropped() {
+    return this.#dropped;
+  }
+  onEvent(e) {
+    try {
+      const stem = stemOf(e.name);
+      if (isStart(e.name) && PAIRED_STEMS.has(stem)) {
+        this.#handleStart(e, stem);
+        return;
+      }
+      if (isEnd(e.name) && PAIRED_STEMS.has(stem)) {
+        this.#handleEnd(e, stem);
+        return;
+      }
+      this.#handlePoint(e);
+    } catch {
+      this.#dropped += 1;
+    }
+  }
+  async flush() {
+    const now = Date.now();
+    for (const queue of this.#open.values()) {
+      for (const { span } of queue) span.end(now);
+    }
+    this.#open.clear();
+  }
+  #keyOf(spanId, stem, disambiguator) {
+    return `${spanId}:${stem}:${disambiguator}`;
+  }
+  #handleStart(e, stem) {
+    const key = this.#keyOf(e.spanId, stem, disambiguatorOf(e, stem));
+    const span = this.#tracer.startSpan(stem, { startTime: e.ts, attributes: startAttributes(e) });
+    const queue = this.#open.get(key);
+    if (queue) queue.push({ span, spanId: e.spanId, stem });
+    else this.#open.set(key, [{ span, spanId: e.spanId, stem }]);
+  }
+  #handleEnd(e, stem) {
+    const key = this.#keyOf(e.spanId, stem, disambiguatorOf(e, stem));
+    const queue = this.#open.get(key);
+    const open = queue?.shift();
+    if (!open) return;
+    open.span.setAttributes({
+      "ap3x.end_seq": e.seq,
+      ...e.usage ? {
+        "gen_ai.usage.input_tokens": e.usage.input,
+        "gen_ai.usage.output_tokens": e.usage.output
+      } : {}
+    });
+    if (isErrorEvent(e.data)) open.span.setStatus({ code: SpanStatusCode.ERROR });
+    open.span.end(e.ts);
+    if (queue && queue.length === 0) this.#open.delete(key);
+  }
+  #handlePoint(e) {
+    const target = this.#innermostOpenSpan(e.spanId);
+    if (target) {
+      target.addEvent(e.name, flatAttributes(e.data), e.ts);
+      return;
+    }
+    const span = this.#tracer.startSpan(e.name, {
+      startTime: e.ts,
+      attributes: startAttributes(e)
+    });
+    span.end(e.ts);
+  }
+  /** Most-recently-opened span whose key belongs to this spanId. */
+  #innermostOpenSpan(spanId) {
+    const prefix = `${spanId}:`;
+    const entries = [...this.#open.entries()];
+    for (let i = entries.length - 1; i >= 0; i -= 1) {
+      const entry = entries[i];
+      if (entry?.[0].startsWith(prefix)) {
+        const queue = entry[1];
+        const last = queue[queue.length - 1];
+        if (last) return last.span;
+      }
+    }
+    return void 0;
+  }
+};
+export {
+  OtelExporter
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@ap3x/observe-otel",
+  "version": "0.1.0",
+  "description": "OpenTelemetry exporter for @ap3x/observe",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AP3X-Dev/AP3X.git",
+    "directory": "packages/observe-otel"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean --tsconfig tsconfig.build.json && tsc -p tsconfig.build.json",
+    "prepublishOnly": "node ../../scripts/publish-gate.mjs",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@ap3x/observe": "0.1.0",
+    "@opentelemetry/api": "^1.9.0"
+  }
+}