@anyway-sh/node-server-sdk 0.22.9 → 0.22.11

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 };