opik-vercel 1.0.1

package/README.md

@@ -0,0 +1,187 @@
+# Opik Vercel AI SDK Integration
+
+[![npm version](https://img.shields.io/npm/v/opik-vercel.svg)](https://www.npmjs.com/package/opik-vercel)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/comet-ml/opik/blob/main/LICENSE)
+
+Seamlessly integrate [Opik](https://www.comet.com/docs/opik/) observability with your [Vercel AI SDK](https://sdk.vercel.ai/docs) applications to trace, monitor, and debug your AI workflows.
+
+## Features
+
+- 🔍 **Comprehensive Tracing**: Automatically trace AI SDK calls and completions
+- 📊 **Hierarchical Visualization**: View your AI execution as a structured trace with parent-child relationships
+- 📝 **Detailed Metadata Capture**: Record model names, prompts, completions, token usage, and custom metadata
+- 🚨 **Error Handling**: Capture and visualize errors in your AI API interactions
+- 🏷️ **Custom Tagging**: Add custom tags to organize and filter your traces
+- 🔄 **Streaming Support**: Full support for streamed completions and chat responses
+
+## Installation
+
+### Node.js
+
+```bash
+npm install opik-vercel ai @ai-sdk/openai @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node
+```
+
+### Next.js
+
+```bash
+npm install opik-vercel @vercel/otel @opentelemetry/api-logs @opentelemetry/instrumentation @opentelemetry/sdk-logs
+```
+
+### Requirements
+
+- Node.js ≥ 18
+- Vercel AI SDK (`ai` ≥ 3.0.0)
+- Opik SDK (automatically installed as a peer dependency)
+- OpenTelemetry packages (see installation commands above)
+
+## Configuration
+
+Set your environment variables:
+
+```bash
+OPIK_API_KEY="<your-api-key>"
+OPIK_URL_OVERRIDE="https://www.comet.com/opik/api"  # Cloud version
+OPIK_PROJECT_NAME="<custom-project-name>"
+OPIK_WORKSPACE="<your-workspace>"
+OPENAI_API_KEY="<your-openai-api-key>"  # If using OpenAI models
+```
+
+## Usage
+
+### Node.js
+
+```typescript
+import { openai } from "@ai-sdk/openai";
+import { generateText } from "ai";
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
+import { OpikExporter } from "opik-vercel";
+
+const sdk = new NodeSDK({
+  traceExporter: new OpikExporter(),
+  instrumentations: [getNodeAutoInstrumentations()],
+});
+
+sdk.start();
+
+async function main() {
+  const result = await generateText({
+    model: openai("gpt-4o"),
+    maxTokens: 50,
+    prompt: "What is love?",
+    experimental_telemetry: OpikExporter.getSettings({
+      name: "opik-nodejs-example",
+    }),
+  });
+
+  console.log(result.text);
+
+  await sdk.shutdown(); // Flushes the trace to Opik
+}
+
+main().catch(console.error);
+```
+
+### Next.js
+
+For Next.js applications, use the framework's built-in OpenTelemetry support:
+
+```typescript
+// instrumentation.ts
+import { registerOTel } from "@vercel/otel";
+import { OpikExporter } from "opik-vercel";
+
+export function register() {
+  registerOTel({
+    serviceName: "opik-vercel-ai-nextjs-example",
+    traceExporter: new OpikExporter(),
+  });
+}
+```
+
+Then use the AI SDK with telemetry enabled:
+
+```typescript
+import { openai } from "@ai-sdk/openai";
+import { generateText } from "ai";
+
+const result = await generateText({
+  model: openai("gpt-4o"),
+  prompt: "What is love?",
+  experimental_telemetry: { isEnabled: true },
+});
+```
+
+## Advanced Configuration
+
+### Custom Tags and Metadata
+
+You can add custom tags and metadata to all traces generated by the OpikExporter:
+
+```typescript
+const exporter = new OpikExporter({
+  // Optional: add custom tags to all traces
+  tags: ["production", "gpt-4o"],
+  // Optional: add custom metadata to all traces
+  metadata: {
+    environment: "production",
+    version: "1.0.0",
+    team: "ai-team",
+  },
+});
+```
+
+Tags are useful for filtering and grouping traces, while metadata adds additional context for debugging and analysis.
+
+### Telemetry Settings
+
+Use `OpikExporter.getSettings()` to configure telemetry for individual AI SDK calls:
+
+```typescript
+const result = await generateText({
+  model: openai("gpt-4o"),
+  prompt: "Tell a joke",
+  experimental_telemetry: OpikExporter.getSettings({
+    name: "custom-trace-name",
+  }),
+});
+```
+
+Or use the basic telemetry settings:
+
+```typescript
+const result = await generateText({
+  model: openai("gpt-4o"),
+  prompt: "Tell a joke",
+  experimental_telemetry: { isEnabled: true },
+});
+```
+
+## Viewing Traces
+
+To view your traces:
+
+1. Sign in to your [Comet account](https://www.comet.com/signin)
+2. Navigate to the Opik section
+3. Select your project to view all traces
+4. Click on a specific trace to see the detailed execution flow
+
+## Debugging
+
+To enable more verbose logging for troubleshooting:
+
+```bash
+OPIK_LOG_LEVEL=DEBUG
+```
+
+## Learn More
+
+- [Opik Vercel AI SDK Integration Guide](https://www.comet.com/docs/opik/tracing/integrations/vercel-ai-sdk)
+- [Opik Documentation](https://www.comet.com/docs/opik/)
+- [Vercel AI SDK Documentation](https://sdk.vercel.ai/docs)
+- [Opik TypeScript SDK](https://github.com/comet-ml/opik/tree/main/sdks/typescript)
+
+## License
+
+Apache 2.0

package/dist/index.cjs

@@ -0,0 +1 @@
+'use strict';var opik=require('opik');var E=new opik.Opik,f=class{constructor({client:e=E,tags:t=[],metadata:n={}}={}){this.traces=new Map;this.spans=new Map;this.getSpanInput=e=>{let t={},{attributes:n}=e;return Object.keys(n).forEach(o=>{if(o==="ai.prompt"||o==="gen_ai.request"){let a=C(n[o]);a&&(t={...t,...a});}if(o.startsWith("ai.prompt.")){let a=o.replace("ai.prompt.","");t[a]=m(n[o]);}if(o.startsWith("gen_ai.request.")){let a=o.replace("gen_ai.request.","");t[a]=m(n[o]);}}),Object.keys(t).length>0||("ai.toolCall.name"in n&&(t.toolName=n["ai.toolCall.name"]),"ai.toolCall.args"in n&&(t.args=n["ai.toolCall.args"])),t};this.getSpanOutput=e=>{let{attributes:t}=e;return t["ai.response.text"]?{text:t["ai.response.text"]}:t["ai.toolCall.result"]?{result:t["ai.toolCall.result"]}:t["ai.response.toolCalls"]?{toolCalls:m(t["ai.response.toolCalls"])}:{}};this.getSpanMetadata=e=>{let{attributes:t}=e,n={};return t["gen_ai.response.model"]&&(n.model=t["gen_ai.response.model"]),t["gen_ai.system"]&&(n.system=t["gen_ai.system"]),n};this.getSpanUsage=e=>{let{attributes:t}=e,n={};return "ai.usage.promptTokens"in t&&(n.prompt_tokens=t["ai.usage.promptTokens"]),"gen_ai.usage.input_tokens"in t&&(n.prompt_tokens=t["gen_ai.usage.input_tokens"]),"ai.usage.completionTokens"in t&&(n.completion_tokens=t["ai.usage.completionTokens"]),"gen_ai.usage.output_tokens"in t&&(n.completion_tokens=t["gen_ai.usage.output_tokens"]),("prompt_tokens"in n||"completion_tokens"in n)&&(n.total_tokens=(n.prompt_tokens||0)+(n.completion_tokens||0)),n};this.processSpan=({otelSpan:e,parentSpan:t,trace:n})=>n.span({name:e.name,startTime:new Date(l(e.startTime)),endTime:new Date(l(e.endTime)),parentSpanId:t==null?void 0:t.data.id,input:this.getSpanInput(e),output:this.getSpanOutput(e),metadata:this.getSpanMetadata(e),usage:this.getSpanUsage(e),type:"llm"});this.shutdown=async()=>{await this.client.flush();};this.forceFlush=async()=>{await this.client.flush();};this.export=async(e,t)=>{let n=e.filter(a=>a.instrumentationScope.name==="ai"),i=e.length-n.length;if(i>0&&opik.logger.debug(`Ignored ${i} non-AI SDK spans`),n.length===0){opik.logger.debug("No AI SDK spans found"),t({code:0});return}let o=w(n);opik.logger.debug("Exporting spans",n),Object.entries(o).forEach(([a,c])=>{var S,h;let[r,...u]=c,p=this.client.trace({startTime:new Date(l(r.startTime)),endTime:new Date(l(r.endTime)),name:(h=(S=r.attributes["ai.telemetry.metadata.traceName"])==null?void 0:S.toString())!=null?h:r.name,input:this.getSpanInput(r),output:this.getSpanOutput(r),metadata:{...this.getSpanMetadata(r),...this.metadata},tags:this.tags,usage:this.getSpanUsage(r)});this.traces.set(a,p),u.forEach(g=>{var b,y;let R=this.spans.get((y=(b=g.parentSpanContext)==null?void 0:b.spanId)!=null?y:""),x=this.processSpan({parentSpan:R,otelSpan:g,trace:p});this.spans.set(g.spanContext().spanId,x);});});try{await this.client.flush(),t({code:0});}catch(a){opik.logger.error("Error exporting spans",a),t({code:1,error:a instanceof Error?a:new Error("Unknown error")});}};this.client=e,this.tags=[...t],this.metadata={...n};}static getSettings(e){var n,i,o;let t={...e.metadata};return e.name&&(t.traceName=e.name),{isEnabled:(n=e.isEnabled)!=null?n:true,recordInputs:(i=e.recordInputs)!=null?i:true,recordOutputs:(o=e.recordOutputs)!=null?o:true,functionId:e.functionId,metadata:t}}};function w(s){let e={};return s.forEach(t=>{let n=t.spanContext();e[n.traceId]||(e[n.traceId]=[]),e[n.traceId].push(t);}),Object.entries(e).forEach(([t,n])=>{e[t]=I(n);}),e}function l(s){return s[0]*1e3+s[1]/1e6}function m(s){try{return JSON.parse(s)}catch{return s}}function C(s){if(typeof s=="string")try{let e=JSON.parse(s);if(e!==null&&typeof e=="object"&&!Array.isArray(e))return e}catch{return}}function I(s){var a,c;let e=new Map,t=new Map;for(let r of s){let{spanId:u}=r.spanContext(),p=(c=(a=r.parentSpanContext)==null?void 0:a.spanId)!=null?c:"";e.set(u,r),p&&(t.has(p)||t.set(p,[]),t.get(p).push(r));}let n=s.filter(r=>{var u;return !((u=r.parentSpanContext)!=null&&u.spanId)||!e.has(r.parentSpanContext.spanId)}),i=[],o=[...n];for(;o.length>0;){let r=o.shift();i.push(r);let u=r.spanContext().spanId,p=t.get(u)||[];o.push(...p);}return i}exports.OpikExporter=f;

package/dist/index.d.cts

@@ -0,0 +1,46 @@
+import { AttributeValue, Tracer } from '@opentelemetry/api';
+import { NodeSDKConfiguration } from '@opentelemetry/sdk-node';
+import { Opik, Span, Trace } from 'opik';
+
+type SpanExporter = NodeSDKConfiguration["traceExporter"];
+type ExportFunction = SpanExporter["export"];
+type ReadableSpan = Parameters<ExportFunction>[0][0];
+type TelemetrySettings = {
+    isEnabled?: boolean;
+    recordInputs?: boolean;
+    recordOutputs?: boolean;
+    functionId?: string;
+    metadata?: Record<string, AttributeValue>;
+    tracer?: Tracer;
+};
+type OpikExporterSettings = TelemetrySettings & {
+    name?: string;
+};
+type OpikExporterOptions = {
+    client?: Opik;
+    tags?: string[];
+    metadata?: Record<string, AttributeValue>;
+};
+declare class OpikExporter implements SpanExporter {
+    private readonly traces;
+    private readonly spans;
+    private readonly client;
+    private readonly tags;
+    private readonly metadata;
+    constructor({ client, tags, metadata, }?: OpikExporterOptions);
+    private getSpanInput;
+    private getSpanOutput;
+    private getSpanMetadata;
+    private getSpanUsage;
+    processSpan: ({ otelSpan, parentSpan, trace, }: {
+        otelSpan: ReadableSpan;
+        parentSpan?: Span;
+        trace: Trace;
+    }) => Span;
+    shutdown: () => Promise<void>;
+    forceFlush: () => Promise<void>;
+    export: ExportFunction;
+    static getSettings(settings: OpikExporterSettings): TelemetrySettings;
+}
+
+export { OpikExporter };

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { AttributeValue, Tracer } from '@opentelemetry/api';
+import { NodeSDKConfiguration } from '@opentelemetry/sdk-node';
+import { Opik, Span, Trace } from 'opik';
+
+type SpanExporter = NodeSDKConfiguration["traceExporter"];
+type ExportFunction = SpanExporter["export"];
+type ReadableSpan = Parameters<ExportFunction>[0][0];
+type TelemetrySettings = {
+    isEnabled?: boolean;
+    recordInputs?: boolean;
+    recordOutputs?: boolean;
+    functionId?: string;
+    metadata?: Record<string, AttributeValue>;
+    tracer?: Tracer;
+};
+type OpikExporterSettings = TelemetrySettings & {
+    name?: string;
+};
+type OpikExporterOptions = {
+    client?: Opik;
+    tags?: string[];
+    metadata?: Record<string, AttributeValue>;
+};
+declare class OpikExporter implements SpanExporter {
+    private readonly traces;
+    private readonly spans;
+    private readonly client;
+    private readonly tags;
+    private readonly metadata;
+    constructor({ client, tags, metadata, }?: OpikExporterOptions);
+    private getSpanInput;
+    private getSpanOutput;
+    private getSpanMetadata;
+    private getSpanUsage;
+    processSpan: ({ otelSpan, parentSpan, trace, }: {
+        otelSpan: ReadableSpan;
+        parentSpan?: Span;
+        trace: Trace;
+    }) => Span;
+    shutdown: () => Promise<void>;
+    forceFlush: () => Promise<void>;
+    export: ExportFunction;
+    static getSettings(settings: OpikExporterSettings): TelemetrySettings;
+}
+
+export { OpikExporter };

package/dist/index.js

@@ -0,0 +1 @@
+import {Opik,logger}from'opik';var E=new Opik,f=class{constructor({client:e=E,tags:t=[],metadata:n={}}={}){this.traces=new Map;this.spans=new Map;this.getSpanInput=e=>{let t={},{attributes:n}=e;return Object.keys(n).forEach(o=>{if(o==="ai.prompt"||o==="gen_ai.request"){let a=C(n[o]);a&&(t={...t,...a});}if(o.startsWith("ai.prompt.")){let a=o.replace("ai.prompt.","");t[a]=m(n[o]);}if(o.startsWith("gen_ai.request.")){let a=o.replace("gen_ai.request.","");t[a]=m(n[o]);}}),Object.keys(t).length>0||("ai.toolCall.name"in n&&(t.toolName=n["ai.toolCall.name"]),"ai.toolCall.args"in n&&(t.args=n["ai.toolCall.args"])),t};this.getSpanOutput=e=>{let{attributes:t}=e;return t["ai.response.text"]?{text:t["ai.response.text"]}:t["ai.toolCall.result"]?{result:t["ai.toolCall.result"]}:t["ai.response.toolCalls"]?{toolCalls:m(t["ai.response.toolCalls"])}:{}};this.getSpanMetadata=e=>{let{attributes:t}=e,n={};return t["gen_ai.response.model"]&&(n.model=t["gen_ai.response.model"]),t["gen_ai.system"]&&(n.system=t["gen_ai.system"]),n};this.getSpanUsage=e=>{let{attributes:t}=e,n={};return "ai.usage.promptTokens"in t&&(n.prompt_tokens=t["ai.usage.promptTokens"]),"gen_ai.usage.input_tokens"in t&&(n.prompt_tokens=t["gen_ai.usage.input_tokens"]),"ai.usage.completionTokens"in t&&(n.completion_tokens=t["ai.usage.completionTokens"]),"gen_ai.usage.output_tokens"in t&&(n.completion_tokens=t["gen_ai.usage.output_tokens"]),("prompt_tokens"in n||"completion_tokens"in n)&&(n.total_tokens=(n.prompt_tokens||0)+(n.completion_tokens||0)),n};this.processSpan=({otelSpan:e,parentSpan:t,trace:n})=>n.span({name:e.name,startTime:new Date(l(e.startTime)),endTime:new Date(l(e.endTime)),parentSpanId:t==null?void 0:t.data.id,input:this.getSpanInput(e),output:this.getSpanOutput(e),metadata:this.getSpanMetadata(e),usage:this.getSpanUsage(e),type:"llm"});this.shutdown=async()=>{await this.client.flush();};this.forceFlush=async()=>{await this.client.flush();};this.export=async(e,t)=>{let n=e.filter(a=>a.instrumentationScope.name==="ai"),i=e.length-n.length;if(i>0&&logger.debug(`Ignored ${i} non-AI SDK spans`),n.length===0){logger.debug("No AI SDK spans found"),t({code:0});return}let o=w(n);logger.debug("Exporting spans",n),Object.entries(o).forEach(([a,c])=>{var S,h;let[r,...u]=c,p=this.client.trace({startTime:new Date(l(r.startTime)),endTime:new Date(l(r.endTime)),name:(h=(S=r.attributes["ai.telemetry.metadata.traceName"])==null?void 0:S.toString())!=null?h:r.name,input:this.getSpanInput(r),output:this.getSpanOutput(r),metadata:{...this.getSpanMetadata(r),...this.metadata},tags:this.tags,usage:this.getSpanUsage(r)});this.traces.set(a,p),u.forEach(g=>{var b,y;let R=this.spans.get((y=(b=g.parentSpanContext)==null?void 0:b.spanId)!=null?y:""),x=this.processSpan({parentSpan:R,otelSpan:g,trace:p});this.spans.set(g.spanContext().spanId,x);});});try{await this.client.flush(),t({code:0});}catch(a){logger.error("Error exporting spans",a),t({code:1,error:a instanceof Error?a:new Error("Unknown error")});}};this.client=e,this.tags=[...t],this.metadata={...n};}static getSettings(e){var n,i,o;let t={...e.metadata};return e.name&&(t.traceName=e.name),{isEnabled:(n=e.isEnabled)!=null?n:true,recordInputs:(i=e.recordInputs)!=null?i:true,recordOutputs:(o=e.recordOutputs)!=null?o:true,functionId:e.functionId,metadata:t}}};function w(s){let e={};return s.forEach(t=>{let n=t.spanContext();e[n.traceId]||(e[n.traceId]=[]),e[n.traceId].push(t);}),Object.entries(e).forEach(([t,n])=>{e[t]=I(n);}),e}function l(s){return s[0]*1e3+s[1]/1e6}function m(s){try{return JSON.parse(s)}catch{return s}}function C(s){if(typeof s=="string")try{let e=JSON.parse(s);if(e!==null&&typeof e=="object"&&!Array.isArray(e))return e}catch{return}}function I(s){var a,c;let e=new Map,t=new Map;for(let r of s){let{spanId:u}=r.spanContext(),p=(c=(a=r.parentSpanContext)==null?void 0:a.spanId)!=null?c:"";e.set(u,r),p&&(t.has(p)||t.set(p,[]),t.get(p).push(r));}let n=s.filter(r=>{var u;return !((u=r.parentSpanContext)!=null&&u.spanId)||!e.has(r.parentSpanContext.spanId)}),i=[],o=[...n];for(;o.length>0;){let r=o.shift();i.push(r);let u=r.spanContext().spanId,p=t.get(u)||[];o.push(...p);}return i}export{f as OpikExporter};

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "opik-vercel",
+  "description": "Opik TypeScript and JavaScript SDK integration with Vercel AI SDK",
+  "version": "1.0.1",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/comet-ml/opik.git",
+    "directory": "sdks/typescript/src/opik/integrations/opik-vercel"
+  },
+  "homepage": "https://www.comet.com/docs/opik/",
+  "author": {
+    "name": "Comet",
+    "email": "support@comet.com",
+    "url": "https://github.com/comet-ml"
+  },
+  "bugs": {
+    "url": "https://github.com/comet-ml/opik/issues",
+    "email": "support@comet.com"
+  },
+  "license": "Apache-2.0",
+  "keywords": [
+    "opik",
+    "vercel",
+    "vercel-ai-sdk",
+    "vercel-integration",
+    "sdk",
+    "javascript",
+    "javascript-sdk",
+    "typescript",
+    "typescript-sdk",
+    "comet"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsup",
+    "watch": "tsup --watch",
+    "lint": "eslint '**/*.{ts,tsx}'",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write 'src/**/*.{ts,tsx,js,jsx,json,md}'",
+    "test": "vitest run"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "opik": "^1.8.75",
+    "@opentelemetry/api": "^1.0.0",
+    "@opentelemetry/core": "^2.0.0",
+    "@opentelemetry/sdk-node": ">=0.56.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.38.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.66.0",
+    "ai": "^5.0.76",
+    "eslint": "^9.38.0",
+    "globals": "^16.4.0",
+    "msw": "^2.7.0",
+    "prettier": "^3.6.2",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.2",
+    "vitest": "^3.2.4",
+    "zod": "^3.25.55"
+  }
+}