@error-bar/tracing 0.2.0

package/README.md

@@ -0,0 +1,93 @@
+# @error-bar/tracing
+
+**Standard OpenTelemetry, curated.** One install, one line, and your LLM traffic streams to [errorbar](https://platform.omnia-voice.com) — where you grade it, calibrate a judge against your own standards, and find out **with confidence intervals** whether a cheaper model holds up on your production traffic.
+
+This SDK contains **no instrumentation code of its own**. It pins and configures the ecosystem's standard OpenTelemetry instrumentations — which gives it a property no other tracing SDK offers: **you can uninstall it without losing your instrumentation.** The identical setup in vanilla OTel is documented below; your spans are byte-for-byte the same either way, and nothing proprietary ever goes on the wire.
+
+## Install
+
+```bash
+npm install @error-bar/tracing
+```
+
+## Use
+
+Call once at startup, **before constructing any LLM client**:
+
+```ts
+import { setup } from "@error-bar/tracing";
+
+const tracing = setup(); // reads ERRORBAR_API_KEY and ERRORBAR_TAG
+```
+
+Pure-ESM app? Skip the code entirely — start Node with the loader hook so imports are intercepted before your app runs:
+
+```bash
+node --import @error-bar/tracing/register app.mjs
+```
+
+Short-lived scripts should `await tracing.shutdown()` before exit to flush pending spans; long-running servers can skip it. The `register` entrypoint flushes automatically when the process exits normally — no code needed.
+
+## What gets captured
+
+OpenAI (v4–v7), Anthropic, LangChain, and Gemini (via the Vertex AI SDK) calls — automatically, and only for libraries actually installed. Successful calls, **streamed** calls (content aggregated across chunks), and **failed** calls (stored as ERROR trace structure — the most valuable signal there is, and the one status-code dashboards can't see).
+
+Your inference does **not** move: requests keep going to your current provider; only trace telemetry flows to errorbar.
+
+## Configuration
+
+| Env var | Meaning | Default |
+| --- | --- | --- |
+| `ERRORBAR_API_KEY` | errorbar API key — **required**; `setup()` throws rather than exporting nowhere silently | — |
+| `ERRORBAR_TAG` | Population tag: one tag = one evaluation population in errorbar | unset |
+| `ERRORBAR_OTLP_ENDPOINT` | OTLP/HTTP traces endpoint | `https://gateway.errorbar.ai/v1/traces` |
+| `OTEL_SERVICE_NAME` | Standard OTel service name | unset |
+
+All options can also be passed to `setup()` directly; explicit options beat env vars.
+
+## The eject guarantee
+
+Remove this package and wire the same standard pieces yourself — identical spans, same endpoint, nothing lost:
+
+```ts
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
+import { OpenAIInstrumentation } from "@traceloop/instrumentation-openai";
+import { AnthropicInstrumentation } from "@traceloop/instrumentation-anthropic";
+import { LangChainInstrumentation } from "@traceloop/instrumentation-langchain";
+
+process.env.OTEL_RESOURCE_ATTRIBUTES = "omnia.tag=my-agent";
+
+new NodeSDK({
+  serviceName: "my-service",
+  traceExporter: new OTLPTraceExporter({
+    url: "https://gateway.errorbar.ai/v1/traces",
+    headers: { Authorization: `Bearer ${process.env.ERRORBAR_API_KEY}` },
+  }),
+  instrumentations: [
+    new OpenAIInstrumentation(),
+    new AnthropicInstrumentation(),
+    new LangChainInstrumentation(),
+  ],
+}).start();
+```
+
+Already emitting OpenTelemetry (Vercel AI SDK telemetry, an existing OTel setup)? You don't need this package at all — three env vars point your existing exporter at errorbar. See the [OTLP ingest reference](https://docs.omnia-voice.com/reference/otlp-ingest).
+
+## Privacy
+
+Span **structure** is always stored. Model-call **content** (prompts/completions) is stored only if your errorbar workspace has request logging enabled, under your retention window, with the same scrubbing and size caps as gateway traffic.
+
+## Verify your setup — get a receipt, not a hope
+
+```bash
+ERRORBAR_API_KEY=sk_... sh -c "$(curl -fsSL https://platform.omnia-voice.com/setup.sh)"
+```
+
+Proves the key works, confirms traces are actually landing, and names your one next step. Instrumentation that fails silently is the industry default; this is the alternative.
+
+## Links
+
+- [Docs](https://docs.omnia-voice.com/reference/tracing-sdk) · [Platform](https://platform.omnia-voice.com) · [Python package](https://pypi.org/project/omnia-tracing/)
+
+Apache-2.0

package/dist/config.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure configuration assembly — separated from setup() so every decision the
+ * SDK makes is unit-testable without starting an OpenTelemetry pipeline.
+ *
+ * This package deliberately contains NO instrumentation code. It pins and
+ * configures standard, ecosystem-maintained OpenTelemetry pieces. The same
+ * setup expressed without this package is documented in docs/eject.md — eject
+ * anytime; your spans do not change.
+ */
+export declare const DEFAULT_ENDPOINT = "https://gateway.errorbar.ai/v1/traces";
+/** Resource attribute that names the traffic population in errorbar. */
+export declare const TAG_ATTRIBUTE = "omnia.tag";
+export interface SetupOptions {
+    /** errorbar API key. Default: ERRORBAR_API_KEY env var (OMNIA_API_KEY still honoured). Required — setup throws
+     *  rather than exporting nowhere silently. */
+    apiKey?: string;
+    /** Population tag (becomes the `omnia.tag` resource attribute — one tag =
+     *  one gradeable population). Default: ERRORBAR_TAG env var (OMNIA_TAG still honoured). */
+    tag?: string;
+    /** Service name on the resource. Default: OTEL_SERVICE_NAME env var. */
+    serviceName?: string;
+    /** OTLP/HTTP traces endpoint. Default: ERRORBAR_OTLP_ENDPOINT env var (OMNIA_OTLP_ENDPOINT still honoured), else
+     *  the errorbar gateway. Point it elsewhere and this package exports to any
+     *  OTLP receiver — there is nothing Omnia-specific on the wire. */
+    endpoint?: string;
+}
+export interface ResolvedConfig {
+    endpoint: string;
+    headers: {
+        Authorization: string;
+    };
+    serviceName: string | undefined;
+    /** Attributes merged into OTEL_RESOURCE_ATTRIBUTES semantics. */
+    resourceAttributes: Record<string, string>;
+}
+export declare function resolveConfig(opts?: SetupOptions, env?: NodeJS.ProcessEnv): ResolvedConfig;

package/dist/config.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Pure configuration assembly — separated from setup() so every decision the
+ * SDK makes is unit-testable without starting an OpenTelemetry pipeline.
+ *
+ * This package deliberately contains NO instrumentation code. It pins and
+ * configures standard, ecosystem-maintained OpenTelemetry pieces. The same
+ * setup expressed without this package is documented in docs/eject.md — eject
+ * anytime; your spans do not change.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAG_ATTRIBUTE = exports.DEFAULT_ENDPOINT = void 0;
+exports.resolveConfig = resolveConfig;
+exports.DEFAULT_ENDPOINT = "https://gateway.errorbar.ai/v1/traces";
+/** Resource attribute that names the traffic population in errorbar. */
+exports.TAG_ATTRIBUTE = "omnia.tag";
+function resolveConfig(opts = {}, env = process.env) {
+    const apiKey = opts.apiKey ?? env.ERRORBAR_API_KEY ?? env.OMNIA_API_KEY;
+    if (!apiKey) {
+        throw new Error("@error-bar/tracing: no API key. Pass setup({ apiKey }) or set ERRORBAR_API_KEY (OMNIA_API_KEY still works). " +
+            "Refusing to start a tracer that exports nowhere.");
+    }
+    const tag = opts.tag ?? env.ERRORBAR_TAG ?? env.OMNIA_TAG;
+    const resourceAttributes = {};
+    if (tag)
+        resourceAttributes[exports.TAG_ATTRIBUTE] = tag;
+    return {
+        endpoint: opts.endpoint ??
+            env.ERRORBAR_OTLP_ENDPOINT ??
+            env.OMNIA_OTLP_ENDPOINT ??
+            exports.DEFAULT_ENDPOINT,
+        headers: { Authorization: `Bearer ${apiKey}` },
+        serviceName: opts.serviceName ?? env.OTEL_SERVICE_NAME,
+        resourceAttributes,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import type { Instrumentation, InstrumentationNodeModuleDefinition } from "@opentelemetry/instrumentation";
+import { OpenAIInstrumentation } from "@traceloop/instrumentation-openai";
+import { AnthropicInstrumentation } from "@traceloop/instrumentation-anthropic";
+import { LangChainInstrumentation } from "@traceloop/instrumentation-langchain";
+import { VertexAIInstrumentation } from "@traceloop/instrumentation-vertexai";
+import { type SetupOptions } from "./config";
+/**
+ * Upstream pins openai support at ">=4 <7", but v7 kept the exact public
+ * class surface the patch wraps (Chat.Completions / Completions / Responses /
+ * Images — verified by live drill 2026-08-21, spans + content landed).
+ * Widen to <8 until upstream catches up; the weekly unpinned-upstream CI
+ * canary re-checks this assumption so the widening can't silently rot.
+ */
+export declare class OpenAIInstrumentationWide extends OpenAIInstrumentation {
+    protected init(): InstrumentationNodeModuleDefinition;
+}
+export { resolveConfig, DEFAULT_ENDPOINT, TAG_ATTRIBUTE } from "./config";
+export type { SetupOptions, ResolvedConfig } from "./config";
+export interface Tracing {
+    /** Flush pending spans and stop. Call before process exit in short-lived
+     *  scripts; long-running servers can skip it. */
+    shutdown(): Promise<void>;
+    /** The live instrumentation instances — escape hatch for ESM setups where
+     *  auto-patching can't intercept an already-imported client:
+     *  `tracing.instrumentations.openai.manuallyInstrument(client)`. */
+    instrumentations: {
+        openai: OpenAIInstrumentation;
+        anthropic: AnthropicInstrumentation;
+        langchain: LangChainInstrumentation;
+        /** Gemini via the Vertex AI SDK (@google-cloud/vertexai). */
+        vertexai: VertexAIInstrumentation;
+    };
+}
+/**
+ * Start standard OpenTelemetry tracing, exporting to errorbar.
+ *
+ * Call ONCE, before constructing any LLM client (the instrumentations patch
+ * module loading, so clients created earlier are not captured — use
+ * `tracing.instrumentations.<lib>.manuallyInstrument(client)` for those).
+ *
+ * Everything this function does is standard OTel configuration; see
+ * docs/eject.md for the identical setup without this package.
+ */
+export declare function setup(opts?: SetupOptions & {
+    instrumentations?: Instrumentation[];
+}): Tracing;

package/dist/index.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAG_ATTRIBUTE = exports.DEFAULT_ENDPOINT = exports.resolveConfig = exports.OpenAIInstrumentationWide = void 0;
+exports.setup = setup;
+const sdk_node_1 = require("@opentelemetry/sdk-node");
+const exporter_trace_otlp_proto_1 = require("@opentelemetry/exporter-trace-otlp-proto");
+const instrumentation_openai_1 = require("@traceloop/instrumentation-openai");
+const instrumentation_anthropic_1 = require("@traceloop/instrumentation-anthropic");
+const instrumentation_langchain_1 = require("@traceloop/instrumentation-langchain");
+const instrumentation_vertexai_1 = require("@traceloop/instrumentation-vertexai");
+const config_1 = require("./config");
+/**
+ * Upstream pins openai support at ">=4 <7", but v7 kept the exact public
+ * class surface the patch wraps (Chat.Completions / Completions / Responses /
+ * Images — verified by live drill 2026-08-21, spans + content landed).
+ * Widen to <8 until upstream catches up; the weekly unpinned-upstream CI
+ * canary re-checks this assumption so the widening can't silently rot.
+ */
+class OpenAIInstrumentationWide extends instrumentation_openai_1.OpenAIInstrumentation {
+    init() {
+        const def = super.init();
+        if (def.name === "openai")
+            def.supportedVersions = [">=4 <8"];
+        return def;
+    }
+}
+exports.OpenAIInstrumentationWide = OpenAIInstrumentationWide;
+var config_2 = require("./config");
+Object.defineProperty(exports, "resolveConfig", { enumerable: true, get: function () { return config_2.resolveConfig; } });
+Object.defineProperty(exports, "DEFAULT_ENDPOINT", { enumerable: true, get: function () { return config_2.DEFAULT_ENDPOINT; } });
+Object.defineProperty(exports, "TAG_ATTRIBUTE", { enumerable: true, get: function () { return config_2.TAG_ATTRIBUTE; } });
+/**
+ * Start standard OpenTelemetry tracing, exporting to errorbar.
+ *
+ * Call ONCE, before constructing any LLM client (the instrumentations patch
+ * module loading, so clients created earlier are not captured — use
+ * `tracing.instrumentations.<lib>.manuallyInstrument(client)` for those).
+ *
+ * Everything this function does is standard OTel configuration; see
+ * docs/eject.md for the identical setup without this package.
+ */
+function setup(opts = {}) {
+    const config = (0, config_1.resolveConfig)(opts);
+    const openai = new OpenAIInstrumentationWide();
+    const anthropic = new instrumentation_anthropic_1.AnthropicInstrumentation();
+    const langchain = new instrumentation_langchain_1.LangChainInstrumentation();
+    const vertexai = new instrumentation_vertexai_1.VertexAIInstrumentation();
+    // The population tag rides the standard resource-attributes env var so the
+    // resource pipeline stays 100% stock OTel (no Resource construction here —
+    // that API has churned across SDK majors; the env contract hasn't).
+    const tagPairs = Object.entries(config.resourceAttributes)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(",");
+    if (tagPairs) {
+        process.env.OTEL_RESOURCE_ATTRIBUTES = process.env.OTEL_RESOURCE_ATTRIBUTES
+            ? `${process.env.OTEL_RESOURCE_ATTRIBUTES},${tagPairs}`
+            : tagPairs;
+    }
+    const sdk = new sdk_node_1.NodeSDK({
+        serviceName: config.serviceName,
+        traceExporter: new exporter_trace_otlp_proto_1.OTLPTraceExporter({
+            url: config.endpoint,
+            headers: config.headers,
+        }),
+        instrumentations: [
+            openai,
+            anthropic,
+            langchain,
+            vertexai,
+            ...(opts.instrumentations ?? []),
+        ],
+    });
+    sdk.start();
+    return {
+        shutdown: () => sdk.shutdown(),
+        instrumentations: { openai, anthropic, langchain, vertexai },
+    };
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@error-bar/tracing",
+  "version": "0.2.0",
+  "description": "errorbar tracing \u2014 standard OpenTelemetry, curated. One install, one line; eject anytime, your spans don't change.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/omnia-v/omnia-tracing.git",
+    "directory": "packages/typescript"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "register.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.221.0",
+    "@opentelemetry/instrumentation": "^0.203.0",
+    "@opentelemetry/sdk-node": "^0.221.0",
+    "@traceloop/instrumentation-anthropic": "^0.27.0",
+    "@traceloop/instrumentation-langchain": "^0.27.0",
+    "@traceloop/instrumentation-openai": "^0.27.0",
+    "@traceloop/instrumentation-vertexai": "^0.27.0"
+  },
+  "devDependencies": {
+    "openai": "^7.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./register": "./register.mjs"
+  }
+}

package/register.mjs

@@ -0,0 +1,44 @@
+/**
+ * ESM auto-instrumentation entrypoint:
+ *
+ *   node --import @error-bar/tracing/register app.mjs
+ *
+ * Pure-ESM apps import their LLM clients before any runtime call could patch
+ * them, so interception has to happen at the module loader. This registers
+ * OpenTelemetry's import-in-the-middle hook FIRST, then starts setup() from
+ * env (ERRORBAR_API_KEY, ERRORBAR_TAG, ERRORBAR_OTLP_ENDPOINT, OTEL_SERVICE_NAME; the OMNIA_* names still work).
+ *
+ * CommonJS apps don't need this file — calling setup() before creating
+ * clients is enough.
+ */
+import { register, createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+
+const require = createRequire(import.meta.url);
+
+// Register the hook from the SAME @opentelemetry/instrumentation copy the
+// instrumentations extend. With two copies in the tree (ours vs the one
+// nested under @traceloop/*), the loader hook and the instrumentations'
+// Hook class hold separate registries and ESM interception silently
+// no-ops — the exact bug this resolution path prevents.
+const hookPath = require.resolve("@opentelemetry/instrumentation/hook.mjs", {
+  paths: [require.resolve("@traceloop/instrumentation-openai/package.json")],
+});
+register(pathToFileURL(hookPath).href, import.meta.url);
+
+const { setup } = require("./dist/index.js");
+const tracing = setup();
+
+// This entrypoint keeps the only shutdown handle, so it owns the flush: the
+// batch exporter holds spans up to 5s, and a short-lived script exits before
+// that timer ever fires — dropping its spans silently (drilled 2026-08-22).
+// beforeExit fires when the event loop drains; the async flush schedules
+// work, which keeps the process alive until the export completes. Does not
+// fire on process.exit() or fatal signals — servers killed by SIGTERM lose
+// at most the final 5s window, same as any OTel batch exporter.
+let flushed = false;
+process.once("beforeExit", () => {
+  if (flushed) return;
+  flushed = true;
+  tracing.shutdown().catch(() => {});
+});