@cybernetyx1/atlasflow-opentelemetry 0.1.0

package/LICENSE

@@ -0,0 +1,18 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2026 Cybernetyx. All rights reserved.
+
+This software and its source code are the proprietary and confidential property
+of the copyright holder. The software is original work authored independently.
+
+No part of this software may be copied, reproduced, modified, published,
+distributed, sublicensed, or sold in any form or by any means without the prior
+written permission of the copyright holder, except as expressly permitted by a
+separate written agreement.
+
+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 COPYRIGHT
+HOLDER 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,39 @@
+# @cybernetyx1/atlasflow-opentelemetry
+
+Maps the AtlasFlow runtime event stream onto OpenTelemetry spans — one span per run and per operation, with tool calls and token usage recorded.
+
+## Install
+
+```sh
+pnpm add @cybernetyx1/atlasflow-opentelemetry
+```
+
+Part of the AtlasFlow monorepo. Proprietary.
+
+## Usage
+
+`createOpenTelemetryObserver(options)` returns an event subscriber. Subscribe it with `observe()`; spans export through whatever OpenTelemetry tracer provider you have configured (OTLP, Braintrust, Sentry, etc.).
+
+```ts
+import { observe } from "@cybernetyx1/atlasflow-runtime";
+import { createOpenTelemetryObserver } from "@cybernetyx1/atlasflow-opentelemetry";
+
+observe(createOpenTelemetryObserver());
+```
+
+Pass a custom `tracer` or a `sanitize` hook to inspect or drop events before they become spans:
+
+```ts
+observe(
+  createOpenTelemetryObserver({
+    tracer: myTracer,
+    sanitize: (event) => (event.type === "tool_call" ? undefined : event),
+  }),
+);
+```
+
+Exports: `createOpenTelemetryObserver` and the `OpenTelemetryObserverOptions` type. Requires `@opentelemetry/api`.
+
+## License
+
+Proprietary. © 2026 Cybernetyx. See LICENSE.

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { Tracer } from '@opentelemetry/api';
+import { AtlasEvent, EventSubscriber } from '@cybernetyx1/atlasflow-runtime';
+
+/**
+ * @cybernetyx1/atlasflow-opentelemetry — map the AtlasFlow event stream to OpenTelemetry
+ * spans. Subscribe the returned observer via `observe()`:
+ *
+ *   import { observe } from "@cybernetyx1/atlasflow-runtime";
+ *   import { createOpenTelemetryObserver } from "@cybernetyx1/atlasflow-opentelemetry";
+ *   observe(createOpenTelemetryObserver());
+ *
+ * Emits a span per run and per operation, records tool calls and token usage,
+ * and sets span status from run/operation outcomes. Exports through whatever
+ * OpenTelemetry tracer provider you've configured (OTLP, Braintrust, Sentry...).
+ */
+
+interface OpenTelemetryObserverOptions {
+    /** Tracer to use; defaults to the global tracer named "atlasflow". */
+    tracer?: Tracer;
+    /** Inspect/redact events before they become spans. Return undefined to drop. */
+    sanitize?: (event: AtlasEvent) => AtlasEvent | undefined;
+}
+declare function createOpenTelemetryObserver(options?: OpenTelemetryObserverOptions): EventSubscriber;
+
+export { type OpenTelemetryObserverOptions, createOpenTelemetryObserver };

package/dist/index.js

@@ -0,0 +1,70 @@
+// src/index.ts
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+function createOpenTelemetryObserver(options = {}) {
+  const tracer = options.tracer ?? trace.getTracer("atlasflow");
+  const runSpans = /* @__PURE__ */ new Map();
+  const opSpans = /* @__PURE__ */ new Map();
+  return (raw) => {
+    const event = options.sanitize ? options.sanitize(raw) : raw;
+    if (!event) return;
+    switch (event.type) {
+      case "run_start": {
+        if (!event.runId) break;
+        const span = tracer.startSpan(`atlasflow.run ${event.agent}`, {
+          attributes: { "atlasflow.run_id": event.runId, "atlasflow.agent": event.agent, "atlasflow.instance_id": event.instanceId }
+        });
+        runSpans.set(event.runId, span);
+        break;
+      }
+      case "operation_start": {
+        if (!event.runId) break;
+        const span = tracer.startSpan(`atlasflow.operation ${event.kind}`, {
+          attributes: { "atlasflow.operation.kind": event.kind, "atlasflow.run_id": event.runId }
+        });
+        opSpans.set(event.operationId, span);
+        break;
+      }
+      case "operation_end": {
+        const span = opSpans.get(event.operationId);
+        span?.setStatus({ code: event.ok ? SpanStatusCode.OK : SpanStatusCode.ERROR });
+        span?.end();
+        opSpans.delete(event.operationId);
+        break;
+      }
+      case "turn_end": {
+        const span = event.runId ? runSpans.get(event.runId) : void 0;
+        span?.addEvent("gen_ai.generate", {
+          "gen_ai.usage.input_tokens": event.usage.inputTokens,
+          "gen_ai.usage.output_tokens": event.usage.outputTokens,
+          "gen_ai.usage.cache_read_tokens": event.usage.cacheReadTokens,
+          "gen_ai.usage.cost_total": event.usage.costTotal,
+          "atlasflow.stop_reason": event.stopReason
+        });
+        break;
+      }
+      case "tool_call": {
+        const span = event.runId ? runSpans.get(event.runId) : void 0;
+        span?.addEvent("atlasflow.tool_call", { "atlasflow.tool": event.tool, "atlasflow.call_id": event.callId });
+        break;
+      }
+      case "run_error": {
+        const span = event.runId ? runSpans.get(event.runId) : void 0;
+        span?.recordException({ name: event.code, message: event.message });
+        break;
+      }
+      case "run_end": {
+        if (!event.runId) break;
+        const span = runSpans.get(event.runId);
+        span?.setStatus({ code: event.ok ? SpanStatusCode.OK : SpanStatusCode.ERROR });
+        span?.end();
+        runSpans.delete(event.runId);
+        break;
+      }
+      default:
+        break;
+    }
+  };
+}
+export {
+  createOpenTelemetryObserver
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@cybernetyx1/atlasflow-opentelemetry",
+  "version": "0.1.0",
+  "description": "OpenTelemetry span observer for AtlasFlow runtime events.",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Cybernetyx",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Cybernetyx/atlasflow.git",
+    "directory": "packages/opentelemetry"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@cybernetyx1/atlasflow-runtime": "0.1.0"
+  },
+  "devDependencies": {
+    "@opentelemetry/sdk-trace-base": "^1.30.0",
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts"
+  }
+}