@overmind-lab/trace-sdk 0.0.2 → 0.0.4

package/README.md

@@ -31,7 +31,7 @@ const overmindClient = new OvermindClient({
 // 2. Initialize tracing — must be called before any OpenAI calls
 overmindClient.initTracing({
   enableBatching: false,
-  enabledProviders: { openai: true },
+  enabledProviders: { openai: OpenAI }, // this is important to patch the correct client
   instrumentations: [],
 });
 
@@ -64,7 +64,7 @@ Traces are sent automatically to `https://api.overmindlab.ai` and will appear in
 
 | Option | Type | Required | Description |
 |---|---|---|---|
-| `enabledProviders` | `{ openai?: boolean; anthropic?: boolean }` | Yes | Which LLM providers to instrument. |
+| `enabledProviders` | `{ openai?: typeof OpenAI }` | Yes | Pass the imported provider class to monkey-patch. e.g. `{ openai: OpenAI }` where `OpenAI` is imported from `"openai"`. |
 | `enableBatching` | `boolean` | Yes | `true` to batch spans before export (recommended for production), `false` to export immediately. |
 | `instrumentations` | `Instrumentation[]` | No | Additional OpenTelemetry instrumentations to register. |
 | `spanProcessors` | `SpanProcessor[]` | No | Additional span processors (e.g. custom exporters). |
@@ -84,7 +84,7 @@ Traces are sent automatically to `https://api.overmindlab.ai` and will appear in
 
 ## What Gets Traced
 
-When `enabledProviders: { openai: true }` is set, the SDK automatically captures:
+When `enabledProviders: { openai: OpenAI }` is set, the SDK automatically captures:
 
 - Prompts and completions
 - Model name, temperature, top-p, max tokens
@@ -103,7 +103,7 @@ Enable batching in production to reduce network overhead:
 ```ts
 overmindClient.initTracing({
   enableBatching: true, // buffer spans and flush in batches
-  enabledProviders: { openai: true },
+  enabledProviders: { openai: OpenAI },
 });
 ```
 

package/package/README.md

@@ -0,0 +1,124 @@
+# @overmind-lab/trace-sdk
+
+JavaScript/TypeScript SDK for [Overmind](https://overmindlab.ai) — automatic LLM observability powered by OpenTelemetry.
+
+Instrument your OpenAI calls with a single `initTracing()` call. Traces are exported to the Overmind platform with zero changes to your existing AI code.
+
+---
+
+## Installation
+
+```bash
+bun add @overmind-lab/trace-sdk openai
+# or
+npm install @overmind-lab/trace-sdk openai
+```
+
+---
+
+## Quick Start with OpenAI
+
+```ts
+import { OpenAI } from "openai";
+import { OvermindClient } from "@overmind-lab/trace-sdk";
+
+// 1. Create the client
+const overmindClient = new OvermindClient({
+  apiKey: process.env.OVERMIND_API_KEY!,
+  appName: "my fintech app",
+});
+
+// 2. Initialize tracing — must be called before any OpenAI calls
+overmindClient.initTracing({
+  enableBatching: false,
+  enabledProviders: { openai: OpenAI }, // this is important to patch the correct client
+  instrumentations: [],
+});
+
+// 3. Use OpenAI as normal — all calls are automatically traced
+const openai = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+});
+
+const response = await openai.chat.completions.create({
+  model: "gpt-4o-mini",
+  messages: [{ role: "user", content: "Hello, how are you?" }],
+});
+```
+
+Traces are sent automatically to `https://api.overmindlab.ai` and will appear in your Overmind dashboard.
+
+---
+
+## Configuration
+
+### `OvermindClient(config)`
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `apiKey` | `string` | Yes | Your Overmind API key. Falls back to `OVERMIND_API_KEY` env var. |
+| `appName` | `string` | No | Name of your service, shown in the dashboard. Defaults to `"overmind-js"`. |
+| `baseUrl` | `string` | No | Override the Overmind ingest endpoint. Defaults to `OVERMIND_TRACES_URL` env var or `https://api.overmindlab.ai`. |
+
+### `initTracing(options)`
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `enabledProviders` | `{ openai?: typeof OpenAI }` | Yes | Pass the imported provider class to monkey-patch. e.g. `{ openai: OpenAI }` where `OpenAI` is imported from `"openai"`. |
+| `enableBatching` | `boolean` | Yes | `true` to batch spans before export (recommended for production), `false` to export immediately. |
+| `instrumentations` | `Instrumentation[]` | No | Additional OpenTelemetry instrumentations to register. |
+| `spanProcessors` | `SpanProcessor[]` | No | Additional span processors (e.g. custom exporters). |
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `OVERMIND_API_KEY` | Your Overmind API key |
+| `OVERMIND_TRACES_URL` | Override the traces ingest base URL |
+| `DEPLOYMENT_ENVIRONMENT` | Tag traces with an environment (e.g. `production`, `staging`). Defaults to `development`. |
+| `OPENAI_API_KEY` | Your OpenAI API key |
+
+---
+
+## What Gets Traced
+
+When `enabledProviders: { openai: OpenAI }` is set, the SDK automatically captures:
+
+- Prompts and completions
+- Model name, temperature, top-p, max tokens
+- Token usage
+- Latency per request
+- Errors and exceptions
+
+All data is attached to OpenTelemetry spans and exported to Overmind.
+
+---
+
+## Production Recommendations
+
+Enable batching in production to reduce network overhead:
+
+```ts
+overmindClient.initTracing({
+  enableBatching: true, // buffer spans and flush in batches
+  enabledProviders: { openai: OpenAI },
+});
+```
+
+Use `enableBatching: false` during local development to see traces immediately.
+
+---
+
+## Resource Attributes
+
+Every trace is tagged with the following attributes automatically:
+
+| Attribute | Value |
+|---|---|
+| `service.name` | Value of `appName` |
+| `service.version` | SDK version |
+| `deployment.environment` | `DEPLOYMENT_ENVIRONMENT` env var or `"development"` |
+| `overmind.sdk.name` | `overmind-js` |
+| `overmind.sdk.version` | SDK version |

package/package/biome.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.4.3/schema.json",
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": {
+          "level": "on",
+          "options": {
+            "groups": [
+              ["@opentelemetry/**"],
+              ":BLANK_LINE:",
+              [":PACKAGE:", ":PACKAGE_WITH_PROTOCOL:"],
+              ":BLANK_LINE:",
+              [":PATH:"],
+              ":BLANK_LINE:"
+            ]
+          }
+        },
+        "useSortedKeys": {
+          "level": "on",
+          "options": {}
+        },
+        "useSortedProperties": {
+          "level": "on",
+          "options": {}
+        }
+      }
+    },
+    "enabled": true
+  },
+  "files": {
+    "ignoreUnknown": true,
+    "includes": ["**"]
+  },
+  "formatter": {
+    "attributePosition": "auto",
+    "enabled": true,
+    "formatWithErrors": false,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineEnding": "lf",
+    "lineWidth": 100
+  },
+  "javascript": {
+    "formatter": {
+      "lineWidth": 100,
+      "quoteStyle": "double",
+      "trailingCommas": "es5"
+    }
+  },
+  "json": {
+    "formatter": {
+      "trailingCommas": "none"
+    }
+  },
+  "linter": {
+    "domains": {
+      "project": "recommended",
+      "test": "recommended"
+    },
+    "enabled": true,
+    "rules": {
+      "suspicious": {
+        "noArrayIndexKey": "off",
+        "noUnknownAtRules": "off"
+      }
+    }
+  },
+  "vcs": {
+    "clientKind": "git",
+    "enabled": true,
+    "useIgnoreFile": true
+  }
+}

package/package/package.json

@@ -0,0 +1,39 @@
+{
+  "dependencies": {
+    "@opentelemetry/auto-instrumentations-node": "^0.70.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.212.0",
+    "@opentelemetry/instrumentation-openai": "^0.10.0",
+    "@opentelemetry/sdk-node": "^0.212.0",
+    "@opentelemetry/sdk-trace-node": "^2.5.1",
+    "@traceloop/ai-semantic-conventions": "^0.22.5",
+    "js-tiktoken": "^1.0.21"
+  },
+  "optionalDependencies": {
+    "@biomejs/biome": "^2.4.3"
+  },
+  "devDependencies": {},
+  "peerDependencies": {
+    "openai": "*"
+  },
+  "name": "@overmind-lab/trace-sdk",
+  "main": "src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "require": "./src/index.ts"
+    }
+  },
+  "packageManager": "bun@1.3.5",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "build": "tsc",
+    "check": "biome check --write",
+    "dev": "tsx watch src/index.ts",
+    "format": "biome format --write"
+  },
+  "version": "0.0.4"
+}

package/package.json

@@ -5,18 +5,29 @@
     "@opentelemetry/instrumentation-openai": "^0.10.0",
     "@opentelemetry/sdk-node": "^0.212.0",
     "@opentelemetry/sdk-trace-node": "^2.5.1",
-    "@traceloop/instrumentation-openai": "^0.22.5",
-    "openai": "^6.22.0"
+    "@traceloop/ai-semantic-conventions": "^0.22.5",
+    "js-tiktoken": "^1.0.21"
   },
-  "devDependencies": {
+  "optionalDependencies": {
     "@biomejs/biome": "^2.4.3"
   },
+  "devDependencies": {},
+  "peerDependencies": {
+    "openai": "*"
+  },
   "name": "@overmind-lab/trace-sdk",
+  "main": "src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "require": "./src/index.ts"
+    }
+  },
   "packageManager": "bun@1.3.5",
   "private": false,
   "publishConfig": {
     "access": "public",
-    "tag": "alpha"
+    "tag": "latest"
   },
   "scripts": {
     "build": "tsc",
@@ -24,5 +35,5 @@
     "dev": "tsx watch src/index.ts",
     "format": "biome format --write"
   },
-  "version": "0.0.2"
+  "version": "0.0.4"
 }

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./overmind-client";
+export * from "./instrumentation-openai";

package/src/overmind-client.ts

@@ -10,10 +10,10 @@ import {
 import { ConsoleSpanExporter } from "@opentelemetry/sdk-trace-node";
 import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
 
-import OpenAI from "openai";
-import { OpenAIInstrumentation } from "./instrumentation-openai";
+import type { OpenAI } from "openai";
 
 import { name, version } from "../package.json";
+import { OpenAIInstrumentation } from "./instrumentation-openai";
 
 type OvermindClientConfig = {
   apiKey: string;
@@ -26,6 +26,7 @@ export class OvermindClient {
   private version: string = version;
   private baseUrl: string;
   private apiKey: string;
+  private sdk?: NodeSDK;
   public experimentSlug?: string;
 
   constructor(config: OvermindClientConfig) {
@@ -51,14 +52,14 @@ export class OvermindClient {
     instrumentations?: Instrumentation[];
     spanProcessors?: SpanProcessor[];
     enableBatching: boolean;
-    enabledProviders: Partial<Record<"openai" | "anthropic", boolean>>;
+    enabledProviders: { openai: OpenAI };
   }) {
-    const traceExporter = !this.baseUrl
+    const traceExporter = this.baseUrl
       ? new OTLPTraceExporter({
-          url: `${this.baseUrl}/api/v1/traces/create`,
           headers: {
-            "X-API-TOKEN": `Bearer ${this.apiKey}`,
+            "X-API-TOKEN": this.apiKey,
           },
+          url: `${this.baseUrl}/api/v1/traces/create`,
         })
       : new ConsoleSpanExporter();
 
@@ -80,16 +81,20 @@ export class OvermindClient {
       const openaiInstrumentation = new OpenAIInstrumentation({
         enabled: true,
       });
-      openaiInstrumentation.manuallyInstrument(OpenAI);
+      openaiInstrumentation.manuallyInstrument(config.enabledProviders.openai);
       instrumentations.push(openaiInstrumentation);
     }
 
-    const _sdk = new NodeSDK({
+    this.sdk = new NodeSDK({
+      instrumentations: [...instrumentations],
       resource,
       spanProcessors,
-      instrumentations: [...instrumentations],
     });
 
-    _sdk.start();
+    this.sdk.start();
+  }
+
+  async shutdown() {
+    await this.sdk?.shutdown();
   }
 }