@observyze/sdk 0.1.2 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
-# Observyze Node.js SDK
+# @observyze/sdk
 
-The official Node.js SDK for Observyze.
+Node.js SDK for Observyze AI Observability Platform.
 
 ## Installation
 
@@ -8,26 +8,191 @@ The official Node.js SDK for Observyze.
 npm install @observyze/sdk
 ```
 
-## Basic Usage
+## Quick Start
+
+### Auto-Instrumentation (Recommended)
+
+The easiest way to get started is with auto-instrumentation:
 
 ```typescript
-import { ObservyzeClient } from '@observyze/sdk'
 import OpenAI from 'openai'
+import { ObservyzeClient } from '@observyze/sdk'
 
+// Initialize Observyze
 const nw = new ObservyzeClient({
-  apiKey: process.env.OBSERVYZE_API_KEY,
-  projectId: 'my-project'
+  apiKey: process.env.Observyze_API_KEY!,
+  organizationId: 'your-org-id',
+  projectId: 'your-project-id'
 })
 
-const openai = nw.wrap(new OpenAI())
+// Initialize your LLM client
+const openai = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY!
+})
 
-// All calls are now automatically traced!
+// Wrap the client - that's it!
+nw.wrap(openai)
+
+// All calls are now automatically traced
 const response = await openai.chat.completions.create({
   model: 'gpt-4',
   messages: [{ role: 'user', content: 'Hello!' }]
 })
 ```
 
-## Documentation
+**Supported Providers:**
+- OpenAI (`chat.completions.create`)
+- Anthropic (`messages.create`)
+- Streaming responses fully supported
+
+See [Auto-Instrumentation Guide](./src/instrumentation/README.md) for more details.
+
+### Manual Instrumentation
+
+For more control, you can manually create traces and spans:
+
+```typescript
+import { ObservyzeClient, SpanType, TraceStatus } from '@observyze/sdk'
+
+// Initialize the client
+const nw = new ObservyzeClient({
+  apiKey: 'your-api-key',
+  endpoint: 'https://api.observyze.com',
+  projectId: 'your-project-id'
+})
+
+// Create a trace
+const trace = nw.startTrace('my-ai-workflow')
+
+// Add a span for an LLM call
+const span = trace.startSpan('openai-completion', SpanType.LLM)
+span.setInput({ prompt: 'Hello, world!' })
+span.setMetadata('model', 'gpt-4')
+span.setMetadata('temperature', 0.7)
+
+// ... perform your LLM call ...
+
+span.setOutput({ completion: 'Hello! How can I help you?' })
+span.setTokens({ input: 10, output: 15, total: 25 })
+span.end()
+
+// End the trace
+trace.end(TraceStatus.SUCCESS)
+
+// Flush traces (or wait for auto-flush)
+await nw.flush()
+
+// Shutdown when done
+await nw.shutdown()
+```
+
+## Configuration
+
+```typescript
+interface ClientConfig {
+  apiKey: string              // Required: Your Observyze API key
+  endpoint?: string           // Optional: Ingestion endpoint (default: http://localhost:3001)
+  batchSize?: number          // Optional: Max traces per batch (default: 100)
+  flushInterval?: number      // Optional: Auto-flush interval in ms (default: 5000)
+  organizationId?: string     // Optional: Organization ID
+  projectId?: string          // Optional: Project ID
+  debug?: boolean             // Optional: Enable debug logging (default: false)
+  dryRun?: boolean            // Optional: Don't send traces (default: false)
+}
+```
+
+## API Reference
+
+### ObservyzeClient
+
+#### `startTrace(name: string, metadata?: Record<string, any>): Trace`
+
+Start a new trace for an AI workflow.
+
+#### `flush(): Promise<void>`
+
+Manually flush buffered traces to the Ingestion Service.
+
+#### `shutdown(): Promise<void>`
+
+Shutdown the SDK and flush remaining traces.
+
+#### `wrap<T>(client: T): T`
+
+Wrap an LLM client (OpenAI, Anthropic) to enable auto-instrumentation. Returns the wrapped client.
+
+```typescript
+const openai = new OpenAI({ apiKey: 'key' })
+nw.wrap(openai)
+```
+
+### Trace
+
+#### `startSpan(name: string, type: SpanType, parentSpanId?: string): Span`
+
+Start a new span within the trace.
+
+#### `setMetadata(key: string, value: any): this`
+
+Add metadata to the trace.
+
+#### `addTag(tag: string): this`
+
+Add a tag to the trace.
+
+#### `setUserId(userId: string): this`
+
+Set the user ID associated with this trace.
+
+#### `setSessionId(sessionId: string): this`
+
+Set the session ID associated with this trace.
+
+#### `end(status?: TraceStatus): void`
+
+End the trace with a final status.
+
+### Span
+
+#### `setInput(input: any): this`
+
+Set the input data for the span.
+
+#### `setOutput(output: any): this`
+
+Set the output data for the span.
+
+#### `setError(error: Error): this`
+
+Record an error that occurred during span execution.
+
+#### `setMetadata(key: string, value: any): this`
+
+Add metadata to the span.
+
+#### `setTokens(tokens: TokenUsage): this`
+
+Set token usage information.
+
+#### `end(): void`
+
+End the span and calculate duration.
+
+## Span Types
+
+- `SpanType.LLM` - LLM API calls (OpenAI, Anthropic, etc.)
+- `SpanType.TOOL` - Tool invocations
+- `SpanType.AGENT` - Agent executions
+- `SpanType.CHAIN` - Chain operations
+- `SpanType.RETRIEVAL` - Retrieval operations (RAG)
+
+## Trace Status
+
+- `TraceStatus.SUCCESS` - Workflow completed successfully
+- `TraceStatus.ERROR` - Workflow failed with an error
+- `TraceStatus.TIMEOUT` - Workflow timed out
+- `TraceStatus.RUNNING` - Workflow is still running
+
+## License
 
-Full documentation is available at [observyze.com/docs](https://observyze.com/docs).
+MIT

package/dist/chunk-FQBYUOJB.mjs

@@ -0,0 +1,316 @@
+// src/types.ts
+import { SpanType, TraceStatus } from "@observyze/types";
+
+// src/trace.ts
+import { randomUUID } from "crypto";
+function generateId() {
+  return `${Date.now()}-${randomUUID().substring(0, 8)}`;
+}
+var Span = class {
+  data;
+  startTime;
+  constructor(name, type, parentSpanId) {
+    this.startTime = Date.now();
+    this.data = {
+      span_id: generateId(),
+      parent_span_id: parentSpanId,
+      name,
+      type,
+      start_time: new Date(this.startTime),
+      end_time: new Date(this.startTime),
+      // Will be updated on end()
+      duration_ms: 0,
+      input: null,
+      output: null,
+      metadata: {}
+    };
+  }
+  /**
+   * Set the input data for this span
+   */
+  setInput(input) {
+    this.data.input = input;
+    return this;
+  }
+  /**
+   * Set the output data for this span
+   */
+  setOutput(output) {
+    this.data.output = output;
+    return this;
+  }
+  /**
+   * Record an error that occurred during span execution
+   */
+  setError(error) {
+    this.data.error = {
+      message: error.message,
+      stack: error.stack,
+      code: error.code
+    };
+    return this;
+  }
+  /**
+   * Set metadata for this span
+   */
+  setMetadata(key, value) {
+    this.data.metadata[key] = value;
+    return this;
+  }
+  /**
+   * Set multiple metadata fields at once
+   */
+  setMetadataAll(metadata) {
+    this.data.metadata = { ...this.data.metadata, ...metadata };
+    return this;
+  }
+  /**
+   * Set token usage information
+   */
+  setTokens(tokens) {
+    this.data.tokens = tokens;
+    return this;
+  }
+  /**
+   * End the span and calculate duration
+   */
+  end() {
+    const endTime = Date.now();
+    this.data.end_time = new Date(endTime);
+    this.data.duration_ms = endTime - this.startTime;
+  }
+  /**
+   * Get the span ID
+   */
+  get id() {
+    return this.data.span_id;
+  }
+  /**
+   * Get the span data for serialization
+   */
+  toJSON() {
+    return { ...this.data };
+  }
+};
+var Trace = class {
+  data;
+  startTime;
+  spans = [];
+  ended = false;
+  constructor(name, organizationId, projectId) {
+    this.startTime = Date.now();
+    this.data = {
+      trace_id: generateId(),
+      organization_id: organizationId,
+      project_id: projectId,
+      name,
+      status: TraceStatus.RUNNING,
+      start_time: new Date(this.startTime),
+      end_time: new Date(this.startTime),
+      // Will be updated on end()
+      duration_ms: 0,
+      metadata: {},
+      spans: [],
+      tags: []
+    };
+  }
+  /**
+   * Start a new span within this trace
+   */
+  startSpan(name, type, parentSpanId) {
+    if (this.ended) {
+      throw new Error("Cannot start span on an ended trace");
+    }
+    const span = new Span(name, type, parentSpanId);
+    this.spans.push(span);
+    return span;
+  }
+  /**
+   * Add metadata to the trace
+   */
+  setMetadata(key, value) {
+    this.data.metadata[key] = value;
+    return this;
+  }
+  /**
+   * Set multiple metadata fields at once
+   */
+  setMetadataAll(metadata) {
+    this.data.metadata = { ...this.data.metadata, ...metadata };
+    return this;
+  }
+  /**
+   * Add tags to the trace
+   */
+  addTag(tag) {
+    if (!this.data.tags.includes(tag)) {
+      this.data.tags.push(tag);
+    }
+    return this;
+  }
+  /**
+   * Add multiple tags at once
+   */
+  addTags(tags) {
+    tags.forEach((tag) => this.addTag(tag));
+    return this;
+  }
+  /**
+   * Set the user ID associated with this trace
+   */
+  setUserId(userId) {
+    this.data.user_id = userId;
+    return this;
+  }
+  /**
+   * Set the session ID associated with this trace
+   */
+  setSessionId(sessionId) {
+    this.data.session_id = sessionId;
+    return this;
+  }
+  /**
+   * End the trace with a final status
+   */
+  end(status = TraceStatus.SUCCESS) {
+    if (this.ended) {
+      return;
+    }
+    const endTime = Date.now();
+    this.data.end_time = new Date(endTime);
+    this.data.duration_ms = endTime - this.startTime;
+    this.data.status = status;
+    this.data.spans = this.spans.map((span) => span.toJSON());
+    this.ended = true;
+  }
+  /**
+   * Get the trace ID
+   */
+  get id() {
+    return this.data.trace_id;
+  }
+  /**
+   * Check if the trace has ended
+   */
+  get isEnded() {
+    return this.ended;
+  }
+  /**
+   * Get the trace data for serialization
+   */
+  toJSON() {
+    return { ...this.data };
+  }
+};
+
+// src/opentelemetry/exporter.ts
+var ObservyzeSpanExporter = class {
+  client;
+  config;
+  constructor(client, config) {
+    this.client = client;
+    this.config = {
+      serviceName: config?.serviceName || "unknown-service",
+      projectId: config?.projectId || "",
+      defaultSpanType: config?.defaultSpanType || "llm",
+      headers: config?.headers || {}
+    };
+  }
+  /**
+   * Export spans — called by OTel SDK when spans are ready.
+   * Converts OTel spans to Observyze traces and buffers them.
+   */
+  async export(spans, resultCallback) {
+    if (!spans || spans.length === 0) {
+      resultCallback({ code: 0 });
+      return;
+    }
+    try {
+      const organizationId = this.client.config?.organizationId || "";
+      const projectId = this.config.projectId || this.client.config?.projectId || "";
+      for (const span of spans) {
+        const spanContext = span.spanContext();
+        const traceId = spanContext?.traceId || span.spanId();
+        const trace = new Trace(
+          span.name || "otel-span",
+          organizationId,
+          projectId
+        );
+        trace.setMetadata("source", "opentelemetry");
+        trace.setMetadata("otel.trace_id", traceId);
+        trace.setMetadata("otel.span_id", spanContext?.spanId || "");
+        trace.setMetadata("service.name", this.config.serviceName);
+        trace.setMetadataAll(span.attributes || {});
+        if (span.resource?.attributes) {
+          trace.setMetadataAll(span.resource.attributes);
+        }
+        const input = span.attributes?.["gen_ai.prompt.0.content"] || span.attributes?.["gen_ai.completion.0.content"] || span.attributes?.["llm.input"] || void 0;
+        const output = span.attributes?.["gen_ai.completion.0.content"] || span.attributes?.["llm.output"] || void 0;
+        const model = span.attributes?.["gen_ai.request.model"] || span.attributes?.["llm.model"] || void 0;
+        const provider = span.attributes?.["gen_ai.request.provider"] || span.attributes?.["llm.provider"] || void 0;
+        const inputTokens = typeof span.attributes?.["gen_ai.usage.input_tokens"] === "number" ? span.attributes["gen_ai.usage.input_tokens"] : void 0;
+        const outputTokens = typeof span.attributes?.["gen_ai.usage.output_tokens"] === "number" ? span.attributes["gen_ai.usage.output_tokens"] : void 0;
+        trace.setMetadata("provider", provider || "unknown");
+        trace.setMetadata("model", model || "unknown");
+        const nsDuration = span.duration;
+        const durationMs = nsDuration ? Math.round(nsDuration / 1e6) : 0;
+        trace.setMetadata("latency_ms", durationMs);
+        trace.setMetadata("otel.duration_ns", nsDuration);
+        const oSpan = trace.startSpan(span.name || "otel-operation", this.config.defaultSpanType);
+        if (input) oSpan.setInput(input);
+        if (output) oSpan.setOutput(output);
+        if (inputTokens || outputTokens) {
+          oSpan.setTokens({
+            input: inputTokens || 0,
+            output: outputTokens || 0,
+            total: (inputTokens || 0) + (outputTokens || 0)
+          });
+        }
+        if (model) oSpan.setMetadata("model", model);
+        if (provider) oSpan.setMetadata("provider", provider);
+        if (span.attributes) oSpan.setMetadataAll(span.attributes);
+        const status = span.status;
+        const statusCode = status?.code;
+        if (statusCode === 2) {
+          oSpan.setError(new Error(status?.message || "OTel span error"));
+          trace.end(TraceStatus.ERROR);
+        } else {
+          trace.end(TraceStatus.SUCCESS);
+        }
+      }
+      resultCallback({ code: 0 });
+    } catch (error) {
+      resultCallback({
+        code: 1,
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    }
+  }
+  /**
+   * Called when the exporter is shut down.
+   * Flushes any remaining buffered traces via the SDK client.
+   */
+  async shutdown() {
+    try {
+      await this.client.flush();
+    } catch {
+    }
+  }
+  /**
+   * Called by the OTel SDK to force-export buffered spans.
+   */
+  async forceFlush() {
+    try {
+      await this.client.flush();
+    } catch {
+    }
+  }
+};
+
+export {
+  SpanType,
+  TraceStatus,
+  Span,
+  Trace,
+  ObservyzeSpanExporter
+};

package/dist/{chunk-YRMQCX2P.mjs → chunk-YSYKPKKX.mjs}

@@ -26,25 +26,10 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/types.ts
-var SpanType, TraceStatus;
+import { SpanType, TraceStatus } from "@observyze/types";
 var init_types = __esm({
   "src/types.ts"() {
     "use strict";
-    SpanType = /* @__PURE__ */ ((SpanType3) => {
-      SpanType3["LLM"] = "llm";
-      SpanType3["TOOL"] = "tool";
-      SpanType3["AGENT"] = "agent";
-      SpanType3["CHAIN"] = "chain";
-      SpanType3["RETRIEVAL"] = "retrieval";
-      return SpanType3;
-    })(SpanType || {});
-    TraceStatus = /* @__PURE__ */ ((TraceStatus2) => {
-      TraceStatus2["SUCCESS"] = "success";
-      TraceStatus2["ERROR"] = "error";
-      TraceStatus2["TIMEOUT"] = "timeout";
-      TraceStatus2["RUNNING"] = "running";
-      return TraceStatus2;
-    })(TraceStatus || {});
   }
 });
 
@@ -155,7 +140,7 @@ var Trace = class {
       organization_id: organizationId,
       project_id: projectId,
       name,
-      status: "running" /* RUNNING */,
+      status: TraceStatus.RUNNING,
       start_time: new Date(this.startTime),
       end_time: new Date(this.startTime),
       // Will be updated on end()
@@ -223,7 +208,7 @@ var Trace = class {
   /**
    * End the trace with a final status
    */
-  end(status = "success" /* SUCCESS */) {
+  end(status = TraceStatus.SUCCESS) {
     if (this.ended) {
       return;
     }
@@ -324,9 +309,9 @@ var ObservyzeSpanExporter = class {
         const statusCode = status?.code;
         if (statusCode === 2) {
           oSpan.setError(new Error(status?.message || "OTel span error"));
-          trace.end("error" /* ERROR */);
+          trace.end(TraceStatus.ERROR);
         } else {
-          trace.end("success" /* SUCCESS */);
+          trace.end(TraceStatus.SUCCESS);
         }
       }
       resultCallback({ code: 0 });