@fiducian/otel 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+import { type StoryContext, type TraceEvent } from "@fiducian/conductor";
+import type { FiduciaTrace } from "@fiducian/runtime";
+export declare const OTEL_BAGGAGE_CONTEXT_KEY = "fiducia.context";
+export declare const OTEL_ATTR_FROM = "fiducia.from";
+export declare const OTEL_ATTR_TO = "fiducia.to";
+export declare const OTEL_ATTR_OP = "fiducia.op";
+export interface TraceParentParts {
+    version: string;
+    traceId: string;
+    spanId: string;
+    flags: string;
+}
+export interface OtelSpanLike {
+    traceId?: string;
+    spanId?: string;
+    name?: string;
+    timestamp?: number;
+    attributes?: Record<string, string | number | boolean>;
+}
+export interface HttpLikeRequest {
+    headers: Record<string, string | string[] | undefined>;
+}
+export declare function parseTraceParent(traceparent: string): TraceParentParts | undefined;
+export declare function parseBaggage(baggage: string | undefined): Record<string, string>;
+export declare function contextFromOtelHeaders(headers: Record<string, string | string[] | undefined>, ct: FiduciaTrace): StoryContext;
+export declare function otelHeadersFromContext(ctx: StoryContext): Record<string, string>;
+export declare function spanLikeToEvent(span: OtelSpanLike, contextId: string): TraceEvent | undefined;
+export declare function importOtelJsonl(source: string): TraceEvent[];
+export declare function importOtelJsonlFile(path: string): TraceEvent[];
+export interface ExpressRouteMapping {
+    method: string;
+    path: string;
+    from: string;
+    to: string;
+    payloadKeys?: string[];
+}
+export interface ExpressOtelMiddlewareOptions {
+    serviceName: string;
+    routes?: ExpressRouteMapping[];
+}
+export declare function createExpressOtelMiddleware(ct: FiduciaTrace, options: ExpressOtelMiddlewareOptions): (req: HttpLikeRequest & {
+    method?: string;
+    path?: string;
+    body?: Record<string, unknown>;
+}, res: {
+    on: (event: string, cb: () => void) => void;
+    statusCode?: number;
+}, next: () => void) => void;
+export declare function attachOtelContext(ctx: StoryContext, headers?: Record<string, string>): Record<string, string>;

package/dist/index.js

@@ -0,0 +1,150 @@
+import { readFileSync } from "node:fs";
+import { CONTEXT_HEADER, contextFromHeader, headerFromContext, } from "@fiducian/conductor";
+export const OTEL_BAGGAGE_CONTEXT_KEY = "fiducia.context";
+export const OTEL_ATTR_FROM = "fiducia.from";
+export const OTEL_ATTR_TO = "fiducia.to";
+export const OTEL_ATTR_OP = "fiducia.op";
+function headerValue(headers, name) {
+    const raw = headers[name] ?? headers[name.toLowerCase()];
+    return Array.isArray(raw) ? raw[0] : raw;
+}
+export function parseTraceParent(traceparent) {
+    const parts = traceparent.trim().split("-");
+    if (parts.length !== 4)
+        return undefined;
+    const [version, traceId, spanId, flags] = parts;
+    if (version !== "00" || traceId.length !== 32 || spanId.length !== 16) {
+        return undefined;
+    }
+    return { version, traceId, spanId, flags };
+}
+export function parseBaggage(baggage) {
+    if (!baggage)
+        return {};
+    const out = {};
+    for (const part of baggage.split(",")) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        const eq = trimmed.indexOf("=");
+        if (eq === -1)
+            continue;
+        const key = decodeURIComponent(trimmed.slice(0, eq).trim());
+        const value = decodeURIComponent(trimmed.slice(eq + 1).trim());
+        out[key] = value;
+    }
+    return out;
+}
+export function contextFromOtelHeaders(headers, ct) {
+    const explicit = headerValue(headers, CONTEXT_HEADER) ??
+        parseBaggage(headerValue(headers, "baggage"))[OTEL_BAGGAGE_CONTEXT_KEY];
+    if (explicit) {
+        return contextFromHeader(explicit) ?? ct.startStory();
+    }
+    const traceparent = headerValue(headers, "traceparent");
+    if (traceparent) {
+        const parsed = parseTraceParent(traceparent);
+        if (parsed) {
+            return ct.conductor.startStoryWithId(parsed.traceId);
+        }
+    }
+    return ct.startStory();
+}
+export function otelHeadersFromContext(ctx) {
+    const id = headerFromContext(ctx);
+    return {
+        [CONTEXT_HEADER]: id,
+        baggage: `${OTEL_BAGGAGE_CONTEXT_KEY}=${encodeURIComponent(id)}`,
+    };
+}
+export function spanLikeToEvent(span, contextId) {
+    const attrs = span.attributes ?? {};
+    const from = attrs[OTEL_ATTR_FROM] ??
+        inferFromSpanName(span.name, 0);
+    const to = attrs[OTEL_ATTR_TO] ??
+        inferFromSpanName(span.name, 1);
+    if (!from || !to)
+        return undefined;
+    const payload = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        if (key.startsWith("fiducia.payload.")) {
+            payload[key.slice("fiducia.payload.".length)] = value;
+        }
+        else if (key.startsWith("fiducia.payload.")) {
+            payload[key.slice("fiducia.payload.".length)] = value;
+        }
+    }
+    return {
+        contextId,
+        timestamp: span.timestamp ?? Date.now(),
+        from,
+        to,
+        op: attrs[OTEL_ATTR_OP] ?? "send",
+        payload,
+    };
+}
+function inferFromSpanName(name, index) {
+    if (!name)
+        return undefined;
+    const arrow = name.match(/^([^->]+)->([^->]+)$/);
+    if (!arrow)
+        return undefined;
+    return index === 0 ? arrow[1].trim() : arrow[2].trim();
+}
+export function importOtelJsonl(source) {
+    const events = [];
+    for (const line of source.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const row = JSON.parse(trimmed);
+        if ("from" in row && "to" in row && "contextId" in row) {
+            events.push(row);
+            continue;
+        }
+        const span = row;
+        const contextId = span.traceId ?? "unknown-trace";
+        const event = spanLikeToEvent(span, contextId);
+        if (event)
+            events.push(event);
+    }
+    return events;
+}
+export function importOtelJsonlFile(path) {
+    return importOtelJsonl(readFileSync(path, "utf8"));
+}
+export function createExpressOtelMiddleware(ct, options) {
+    const routes = options.routes ?? [];
+    return (req, res, next) => {
+        const ctx = contextFromOtelHeaders(req.headers, ct);
+        req.fiduciaContext =
+            ctx;
+        const match = routes.find((route) => route.method.toUpperCase() === (req.method ?? "GET").toUpperCase() &&
+            route.path === req.path);
+        if (match) {
+            const payload = {};
+            for (const key of match.payloadKeys ?? []) {
+                if (req.body && key in req.body)
+                    payload[key] = req.body[key];
+            }
+            ct.emit(ctx, {
+                from: match.from,
+                to: match.to,
+                payload,
+            });
+        }
+        res.on("finish", () => {
+            if (res.statusCode && res.statusCode >= 400) {
+                ct.emit(ctx, {
+                    from: options.serviceName,
+                    to: "error",
+                    payload: { status: res.statusCode, path: req.path ?? "/" },
+                });
+            }
+        });
+        next();
+    };
+}
+export function attachOtelContext(ctx, headers = {}) {
+    return { ...headers, ...otelHeadersFromContext(ctx) };
+}

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,57 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { FiduciaTrace, parseWaltzFile } from "@fiducian/runtime";
+import { contextFromOtelHeaders, importOtelJsonl, parseTraceParent, spanLikeToEvent, } from "./index.js";
+const spec = parseWaltzFile(`
+  Omega(
+    send client->order{orderId} : true
+    ;
+    send order->kitchen{orderId, accepted} : accepted == true
+    ;
+    send order->billing{orderId, charged} : charged == true
+  )
+`);
+test("parseTraceParent extracts trace id", () => {
+    const parsed = parseTraceParent("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01");
+    assert.ok(parsed);
+    assert.equal(parsed.traceId, "4bf92f3577b34da6a3ce929d0e0e4736");
+});
+test("contextFromOtelHeaders uses traceparent as story id", () => {
+    const ct = new FiduciaTrace({ spec });
+    const ctx = contextFromOtelHeaders({
+        traceparent: "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
+    }, ct);
+    assert.equal(ctx.contextId, "4bf92f3577b34da6a3ce929d0e0e4736");
+});
+test("importOtelJsonl converts span attributes to events", () => {
+    const jsonl = [
+        JSON.stringify({
+            traceId: "trace-1",
+            name: "order->kitchen",
+            timestamp: 1,
+            attributes: {
+                "fiducia.payload.orderId": "42",
+                "fiducia.payload.accepted": true,
+            },
+        }),
+        JSON.stringify({
+            traceId: "trace-1",
+            name: "order->billing",
+            timestamp: 2,
+            attributes: {
+                "fiducia.payload.orderId": "42",
+                "fiducia.payload.charged": true,
+            },
+        }),
+    ].join("\n");
+    const events = importOtelJsonl(jsonl);
+    assert.equal(events.length, 2);
+    assert.equal(events[0].from, "order");
+    assert.equal(events[0].to, "kitchen");
+});
+test("spanLikeToEvent maps arrow span names", () => {
+    const event = spanLikeToEvent({ name: "client->order", traceId: "t1", attributes: {} }, "t1");
+    assert.ok(event);
+    assert.equal(event.from, "client");
+    assert.equal(event.to, "order");
+});

package/dist/packs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/packs.test.js

@@ -0,0 +1,44 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { importOtelJsonl } from "./index.js";
+import { evaluateTrace, parseWaltzFile } from "@fiducian/runtime";
+const root = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+test("payment-ordering bug fixture fails", () => {
+    const spec = parseWaltzFile(readFileSync(join(root, "specs", "payment-ordering.waltz"), "utf8"));
+    const events = importOtelJsonl(readFileSync(join(root, "specs", "fixtures", "payment-ordering-bug.otel.jsonl"), "utf8"));
+    const result = evaluateTrace(spec, events);
+    assert.equal(result.passed, false);
+});
+test("payment-ordering fix fixture passes", () => {
+    const spec = parseWaltzFile(readFileSync(join(root, "specs", "payment-ordering.waltz"), "utf8"));
+    const events = importOtelJsonl(readFileSync(join(root, "specs", "fixtures", "payment-ordering-fix.otel.jsonl"), "utf8"));
+    const result = evaluateTrace(spec, events);
+    assert.equal(result.passed, true);
+});
+test("refund-chain bug fixture fails", () => {
+    const spec = parseWaltzFile(readFileSync(join(root, "specs", "refund-chain.waltz"), "utf8"));
+    const events = importOtelJsonl(readFileSync(join(root, "specs", "fixtures", "refund-chain-bug.otel.jsonl"), "utf8"));
+    const result = evaluateTrace(spec, events);
+    assert.equal(result.passed, false);
+});
+test("refund-chain fix fixture passes", () => {
+    const spec = parseWaltzFile(readFileSync(join(root, "specs", "refund-chain.waltz"), "utf8"));
+    const events = importOtelJsonl(readFileSync(join(root, "specs", "fixtures", "refund-chain-fix.otel.jsonl"), "utf8"));
+    const result = evaluateTrace(spec, events);
+    assert.equal(result.passed, true);
+});
+test("agent-tool-chain bug fixture fails", () => {
+    const spec = parseWaltzFile(readFileSync(join(root, "specs", "agent-tool-chain.waltz"), "utf8"));
+    const events = importOtelJsonl(readFileSync(join(root, "specs", "fixtures", "agent-tool-chain-bug.otel.jsonl"), "utf8"));
+    const result = evaluateTrace(spec, events);
+    assert.equal(result.passed, false);
+});
+test("agent-tool-chain fix fixture passes", () => {
+    const spec = parseWaltzFile(readFileSync(join(root, "specs", "agent-tool-chain.waltz"), "utf8"));
+    const events = importOtelJsonl(readFileSync(join(root, "specs", "fixtures", "agent-tool-chain-fix.otel.jsonl"), "utf8"));
+    const result = evaluateTrace(spec, events);
+    assert.equal(result.passed, true);
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@fiducian/otel",
+  "version": "0.4.0",
+  "description": "OpenTelemetry bridge for FiduciaTrace traceparent and JSONL import",
+  "license": "AGPL-3.0-or-later",
+  "keywords": ["fiducia", "fiducia", "opentelemetry", "otel", "tracing"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thesnmc/Fiducian.git",
+    "directory": "trace/packages/otel"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["dist"],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@fiducian/conductor": "0.4.0",
+    "@fiducian/runtime": "0.4.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test dist/**/*.test.js",
+    "prepublishOnly": "npm run build"
+  }
+}