@anyway-sh/node-server-sdk 0.22.8 → 0.22.10

package/README.md

@@ -0,0 +1,154 @@
+# @anyway-sh/node-server-sdk
+
+OpenTelemetry-based observability SDK for LLM applications. Automatically instruments LLM provider calls, tracks token usage, and calculates costs.
+
+## Installation
+
+```bash
+npm install @anyway-sh/node-server-sdk
+```
+
+## Quick Start
+
+```typescript
+import { initialize } from "@anyway-sh/node-server-sdk";
+
+initialize({
+  apiKey: process.env.ANYWAY_API_KEY,
+  appName: "my-app",
+});
+```
+
+## ESM / Next.js
+
+ESM projects must pass provider modules explicitly since OpenTelemetry's require-based instrumentation doesn't work with ESM imports:
+
+```typescript
+import { initialize } from "@anyway-sh/node-server-sdk";
+import * as OpenAIModule from "openai";
+
+initialize({
+  apiKey: process.env.ANYWAY_API_KEY,
+  appName: "my-app",
+  instrumentModules: {
+    openAI: OpenAIModule.OpenAI,
+  },
+});
+```
+
+## Tracing Workflows
+
+Use `withWorkflow`, `withTask`, `withAgent`, and `withTool` to create structured trace hierarchies:
+
+```typescript
+import { withWorkflow, withTask } from "@anyway-sh/node-server-sdk";
+
+async function main() {
+  await withWorkflow({ name: "my-pipeline" }, async () => {
+    const result = await withTask({ name: "generate-response" }, async () => {
+      return openai.chat.completions.create({
+        model: "gpt-4",
+        messages: [{ role: "user", content: "Hello" }],
+      });
+    });
+    return result;
+  });
+}
+```
+
+### Class Decorators
+
+```typescript
+import { workflow, task } from "@anyway-sh/node-server-sdk";
+
+class MyPipeline {
+  @workflow({ name: "run" })
+  async run() {
+    return this.step();
+  }
+
+  @task({ name: "step" })
+  async step() {
+    // ...
+  }
+}
+```
+
+### Association Properties
+
+Attach metadata to traces for filtering and grouping:
+
+```typescript
+await withWorkflow(
+  {
+    name: "chat",
+    associationProperties: { userId: "user-123", sessionId: "abc" },
+  },
+  async () => {
+    // All spans in this workflow will carry these properties
+  },
+);
+```
+
+## Configuration
+
+Key options for `initialize()`:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `apiKey` | `ANYWAY_API_KEY` env var | API key for sending traces |
+| `appName` | `npm_package_name` | Application name in traces |
+| `baseUrl` | `ANYWAY_BASE_URL` or `https://api.traceloop.com` | Trace collector endpoint |
+| `disableBatch` | `false` | Send spans immediately (for local dev) |
+| `exporter` | OTLP exporter | Custom OpenTelemetry `SpanExporter` |
+| `processor` | `BatchSpanProcessor` | Custom OpenTelemetry `SpanProcessor` |
+| `instrumentModules` | — | Explicit module references for ESM projects |
+| `pricingEnabled` | `true` | Calculate and attach cost attributes to spans |
+| `pricingJsonPath` | — | Path to custom pricing JSON file |
+| `tracingEnabled` | `true` | Enable/disable tracing entirely |
+| `silenceInitializationMessage` | `false` | Suppress startup console message |
+
+## Supported Providers
+
+LLM providers and vector databases instrumented automatically:
+
+- **OpenAI** — chat completions, embeddings
+- **Anthropic** — messages
+- **AWS Bedrock** — invoke model
+- **Google Vertex AI** — generative models
+- **Cohere** — chat, embed, rerank
+- **Together AI** — chat completions
+- **LangChain** — chains, agents, tools
+- **LlamaIndex** — query engines, retrievers
+- **Pinecone** — vector operations
+- **ChromaDB** — collections, queries
+- **Qdrant** — points, search
+- **MCP** — Model Context Protocol client calls
+
+## Pricing
+
+Cost calculation is enabled by default. The SDK matches model names from spans against bundled pricing data and sets these attributes:
+
+- `gen_ai.usage.input_cost`
+- `gen_ai.usage.output_cost`
+- `gen_ai.usage.cost`
+
+To use custom pricing data:
+
+```typescript
+initialize({
+  pricingJsonPath: "./my-pricing.json",
+});
+```
+
+To disable:
+
+```typescript
+initialize({
+  pricingEnabled: false,
+});
+```
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { SpanExporter, SpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { SpanExporter, SpanProcessor, ReadableSpan } from '@opentelemetry/sdk-trace-base';
 import * as _opentelemetry_api from '@opentelemetry/api';
 import { TextMapPropagator, ContextManager, Span } from '@opentelemetry/api';
 import * as openai from 'openai';
@@ -168,6 +168,16 @@ interface InitializeOptions {
      * This is used to configure the Google Cloud Trace Exporter.
      */
     gcpProjectId?: string;
+    /**
+     * Whether to calculate and add cost attributes to spans. Optional.
+     * Defaults to true.
+     */
+    pricingEnabled?: boolean;
+    /**
+     * Path to a custom pricing JSON file. Optional.
+     * If not set, uses the bundled default pricing data.
+     */
+    pricingJsonPath?: string;
 }
 
 /**
@@ -1859,8 +1869,31 @@ declare function withAssociationProperties<A extends unknown[], F extends (...ar
  */
 declare const reportCustomMetric: (metricName: string, metricValue: number) => void;
 
+interface NormalizedPricing {
+    inputCostPerToken: number;
+    outputCostPerToken: number;
+}
+interface ModelPricing {
+    promptPrice: number;
+    completionPrice: number;
+}
+interface PricingData {
+    chat?: Record<string, ModelPricing>;
+    embeddings?: Record<string, number>;
+    images?: Record<string, unknown>;
+    audio?: Record<string, unknown>;
+}
+declare class PricingCalculator {
+    private chatModels;
+    constructor(pricingData: PricingData);
+    findPricing(modelName: string): NormalizedPricing | null;
+    addCostAttributes(span: ReadableSpan): void;
+    private normalize;
+}
+
 declare const ALL_INSTRUMENTATION_LIBRARIES: "all";
 type AllInstrumentationLibraries = typeof ALL_INSTRUMENTATION_LIBRARIES;
+declare const setPricingCalculator: (calculator: PricingCalculator | null) => void;
 interface SpanProcessorOptions {
     /**
      * The API Key for sending traces data. Optional.
@@ -1953,5 +1986,5 @@ declare class ImageUploader {
     private uploadImageData;
 }
 
-export { ALL_INSTRUMENTATION_LIBRARIES, ArgumentNotProvidedError, AssociationProperty, Attachment, AttachmentReference, AttachmentUploader, Column, Dataset, Datasets, Evaluator, EvaluatorMadeByTraceloop, Experiment, ExternalAttachment, ImageUploader, InitializationError, LLMSpan, NotInitializedError, PromptNotFoundError, Row, SEVERITY, TraceloopClient, TraceloopError, VectorSpan, agent, attachment, conversation, createEvaluator, createSpanProcessor, forceFlush, getAvailableEvaluatorSlugs, getClient, getEvaluatorSchemaInfo, getPrompt, getTraceloopTracer, initialize, isAnyAttachment, isAttachment, isAttachmentReference, isExternalAttachment, reportCustomMetric, task, tool, traceloopInstrumentationLibraries, validateEvaluatorInput, waitForInitialization, withAgent, withAssociationProperties, withConversation, withLLMCall, withTask, withTool, withVectorDBCall, withWorkflow, workflow };
+export { ALL_INSTRUMENTATION_LIBRARIES, ArgumentNotProvidedError, AssociationProperty, Attachment, AttachmentReference, AttachmentUploader, Column, Dataset, Datasets, Evaluator, EvaluatorMadeByTraceloop, Experiment, ExternalAttachment, ImageUploader, InitializationError, LLMSpan, NotInitializedError, PromptNotFoundError, Row, SEVERITY, TraceloopClient, TraceloopError, VectorSpan, agent, attachment, conversation, createEvaluator, createSpanProcessor, forceFlush, getAvailableEvaluatorSlugs, getClient, getEvaluatorSchemaInfo, getPrompt, getTraceloopTracer, initialize, isAnyAttachment, isAttachment, isAttachmentReference, isExternalAttachment, reportCustomMetric, setPricingCalculator, task, tool, traceloopInstrumentationLibraries, validateEvaluatorInput, waitForInitialization, withAgent, withAssociationProperties, withConversation, withLLMCall, withTask, withTool, withVectorDBCall, withWorkflow, workflow };
 export type { AnnotationCreateOptions, AttachmentMetadata, AttachmentOptions, CSVImportOptions, ColumnDefinition, ColumnResponse, ColumnUpdateOptions, DatasetCreateOptions, DatasetListResponse, DatasetPublishOptions, DatasetResponse, DatasetUpdateOptions, DatasetVersion, DatasetVersionsResponse, DecoratorConfig, EvaluatorDetails, EvaluatorWithConfig, EvaluatorWithVersion, ExecutionResponse, ExperimentRunOptions, ExperimentRunResult, ExperimentTaskFunction, ExternalAttachmentOptions, FileCellType, FileStorageType, GithubContext, InitializeOptions, RowData, RowResponse, RowUpdateOptions, RunInGithubOptions, RunInGithubResponse, SSEStreamEvent, Severity, SpanProcessorOptions, StreamEvent, TaskInput, TaskOutput, TaskResponse, TaskResult, TraceloopClientOptions, UploadUrlResponse };

package/dist/index.js

@@ -90,7 +90,7 @@ class PromptNotFoundError extends TraceloopError {
     }
 }
 
-var version = "0.22.8";
+var version = "0.22.10";
 
 /**
  * Base class for handling annotation operations with the Traceloop API.
@@ -3262,6 +3262,10 @@ function parseKeyPairsIntoRecord(keyPairs) {
 }
 
 const ALL_INSTRUMENTATION_LIBRARIES = "all";
+let _pricingCalculator = null;
+const setPricingCalculator = (calculator) => {
+    _pricingCalculator = calculator;
+};
 const spanAgentNames = new Map();
 const SPAN_AGENT_NAME_TTL = 5 * 60 * 1000;
 const AI_TELEMETRY_METADATA_AGENT = "ai.telemetry.metadata.agent";
@@ -3439,6 +3443,9 @@ const onSpanEnd = (originalOnEnd, instrumentationLibraries) => {
         if (Math.random() < 0.01) {
             cleanupExpiredSpanAgentNames();
         }
+        if (_pricingCalculator) {
+            _pricingCalculator.addCostAttributes(span);
+        }
         const compatibleSpan = ensureSpanCompatibility(span);
         originalOnEnd(compatibleSpan);
     };
@@ -3862,6 +3869,80 @@ const initializeRegistry = (options) => {
     });
 };
 
+const DATE_SUFFIX_PATTERN = /-\d{4}-\d{2}-\d{2}$/;
+const DATE_COMPACT_SUFFIX_PATTERN = /-\d{8}$/;
+class PricingCalculator {
+    constructor(pricingData) {
+        var _a;
+        this.chatModels = (_a = pricingData.chat) !== null && _a !== void 0 ? _a : {};
+    }
+    findPricing(modelName) {
+        if (!modelName)
+            return null;
+        const models = this.chatModels;
+        // 1. Exact match
+        if (models[modelName]) {
+            return this.normalize(models[modelName]);
+        }
+        // 2. Strip date suffix and retry
+        let stripped = modelName.replace(DATE_SUFFIX_PATTERN, "");
+        stripped = stripped.replace(DATE_COMPACT_SUFFIX_PATTERN, "");
+        if (stripped !== modelName && models[stripped]) {
+            return this.normalize(models[stripped]);
+        }
+        // 3. Prefix match (longest wins)
+        let bestMatch = null;
+        let bestLen = 0;
+        for (const baseModel of Object.keys(models)) {
+            if (modelName.startsWith(baseModel) && baseModel.length > bestLen) {
+                bestMatch = baseModel;
+                bestLen = baseModel.length;
+            }
+        }
+        if (bestMatch) {
+            return this.normalize(models[bestMatch]);
+        }
+        return null;
+    }
+    addCostAttributes(span) {
+        const attrs = span.attributes;
+        if (!attrs)
+            return;
+        const model = attrs[incubating.ATTR_GEN_AI_RESPONSE_MODEL] ||
+            attrs[incubating.ATTR_GEN_AI_REQUEST_MODEL];
+        if (!model)
+            return;
+        const inputTokens = attrs[incubating.ATTR_GEN_AI_USAGE_INPUT_TOKENS];
+        const outputTokens = attrs[incubating.ATTR_GEN_AI_USAGE_OUTPUT_TOKENS];
+        if (inputTokens == null && outputTokens == null)
+            return;
+        const pricing = this.findPricing(model);
+        if (!pricing)
+            return;
+        const inputCost = (inputTokens !== null && inputTokens !== void 0 ? inputTokens : 0) * pricing.inputCostPerToken;
+        const outputCost = (outputTokens !== null && outputTokens !== void 0 ? outputTokens : 0) * pricing.outputCostPerToken;
+        span.attributes["gen_ai.usage.input_cost"] = inputCost;
+        span.attributes["gen_ai.usage.output_cost"] = outputCost;
+        span.attributes["gen_ai.usage.cost"] = inputCost + outputCost;
+    }
+    normalize(pricing) {
+        var _a, _b;
+        return {
+            inputCostPerToken: ((_a = pricing.promptPrice) !== null && _a !== void 0 ? _a : 0) / 1000,
+            outputCostPerToken: ((_b = pricing.completionPrice) !== null && _b !== void 0 ? _b : 0) / 1000,
+        };
+    }
+}
+
+function loadPricing(pricingJsonPath) {
+    if (pricingJsonPath) {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const fs = require("fs");
+        return JSON.parse(fs.readFileSync(pricingJsonPath, "utf-8"));
+    }
+    return require("./data/default_pricing.json");
+}
+
 let _configuration;
 let _client;
 /**
@@ -3930,6 +4011,15 @@ const initialize = (options = {}) => {
         }
         startTracing(_configuration);
     }
+    if (options.pricingEnabled !== false) {
+        try {
+            const pricingData = loadPricing(options.pricingJsonPath);
+            setPricingCalculator(new PricingCalculator(pricingData));
+        }
+        catch (e) {
+            console.warn(`[Traceloop] Failed to initialize pricing: ${e.message}`);
+        }
+    }
     initializeRegistry(_configuration);
     if (options.apiKey) {
         _client = new TraceloopClient({
@@ -4441,6 +4531,7 @@ exports.isAttachment = isAttachment;
 exports.isAttachmentReference = isAttachmentReference;
 exports.isExternalAttachment = isExternalAttachment;
 exports.reportCustomMetric = reportCustomMetric;
+exports.setPricingCalculator = setPricingCalculator;
 exports.task = task;
 exports.tool = tool;
 exports.traceloopInstrumentationLibraries = traceloopInstrumentationLibraries;