@traccia2/sdk 0.0.1

package/src/integrations/langchain-callback.ts

@@ -0,0 +1,229 @@
+/**
+ * LangChain callback handler for automatic tracing.
+ * Integrates with LangChain's callback system to automatically instrument
+ * LLM calls, chains, agents, and tools.
+ */
+
+import { ISpan } from '../types';
+import { getTracer } from '../auto';
+
+/**
+ * LangChain Callback Handler for Traccia SDK.
+ * Automatically traces LLM calls, chains, agents, and tools.
+ *
+ * @example
+ * import { ChatOpenAI } from 'langchain/chat_models/openai';
+ * import { LLMChain } from 'langchain/chains';
+ * import { TraciaCallbackHandler } from '@traccia/sdk/integrations/langchain';
+ *
+ * const handler = new TraciaCallbackHandler();
+ * const chain = new LLMChain({
+ *   llm: new ChatOpenAI(),
+ *   callbacks: [handler],
+ * });
+ *
+ * await chain.run({ input: 'What is 2+2?' });
+ * // Automatically traced with spans for LLM, chain execution, tokens, etc.
+ */
+export class TraciaCallbackHandler {
+  private tracer = getTracer('langchain');
+  private spanStack: Map<string, ISpan> = new Map();
+
+  /**
+   * Handle LLM start - called when an LLM begins execution.
+   */
+  public async handleLLMStart(
+    llm: any,
+    prompts: string[],
+    runId: string,
+    _parentRunId?: string
+  ): Promise<void> {
+    const span = this.tracer.startSpan('llm', {
+      attributes: {
+        type: 'llm',
+        model: llm.name || llm._modelType || 'unknown',
+        prompt_count: prompts.length,
+        first_prompt_length: prompts[0]?.length || 0,
+      },
+    });
+
+    this.spanStack.set(runId, span);
+  }
+
+  /**
+   * Handle LLM end - called when an LLM finishes execution.
+   */
+  public async handleLLMEnd(output: any, runId: string): Promise<void> {
+    const span = this.spanStack.get(runId);
+    if (span) {
+      try {
+        const tokenUsage = output?.llmOutput?.token_usage || output?.token_usage;
+        if (tokenUsage) {
+          span.setAttribute('prompt_tokens', tokenUsage.prompt_tokens);
+          span.setAttribute('completion_tokens', tokenUsage.completion_tokens);
+          span.setAttribute(
+            'total_tokens',
+            (tokenUsage.prompt_tokens || 0) + (tokenUsage.completion_tokens || 0)
+          );
+        }
+
+        if (output?.text) {
+          span.setAttribute('output_length', output.text.length);
+        }
+      } catch (error) {
+        // Silently fail on attribute setting
+      }
+
+      span.end();
+      this.spanStack.delete(runId);
+    }
+  }
+
+  /**
+   * Handle LLM error.
+   */
+  public async handleLLMError(error: Error, runId: string): Promise<void> {
+    const span = this.spanStack.get(runId);
+    if (span) {
+      span.recordException(error, { source: 'langchain-llm' });
+      span.end();
+      this.spanStack.delete(runId);
+    }
+  }
+
+  /**
+   * Handle chain start - called when a chain begins execution.
+   */
+  public async handleChainStart(
+    chain: any,
+    inputs: any,
+    runId: string,
+    _parentRunId?: string
+  ): Promise<void> {
+    const chainName = chain.name || chain._chainType || 'chain';
+    const span = this.tracer.startSpan(`chain:${chainName}`, {
+      attributes: {
+        type: 'chain',
+        chain_name: chainName,
+        chain_type: chain._chainType,
+        input_keys: Object.keys(inputs).join(','),
+      },
+    });
+
+    this.spanStack.set(runId, span);
+  }
+
+  /**
+   * Handle chain end - called when a chain finishes execution.
+   */
+  public async handleChainEnd(output: any, runId: string): Promise<void> {
+    const span = this.spanStack.get(runId);
+    if (span) {
+      try {
+        if (output) {
+          const outputStr = typeof output === 'string' ? output : JSON.stringify(output);
+          span.setAttribute('output_length', outputStr.length);
+        }
+      } catch (error) {
+        // Silently fail
+      }
+
+      span.end();
+      this.spanStack.delete(runId);
+    }
+  }
+
+  /**
+   * Handle chain error.
+   */
+  public async handleChainError(error: Error, runId: string): Promise<void> {
+    const span = this.spanStack.get(runId);
+    if (span) {
+      span.recordException(error, { source: 'langchain-chain' });
+      span.end();
+      this.spanStack.delete(runId);
+    }
+  }
+
+  /**
+   * Handle tool start - called when a tool is invoked.
+   */
+  public async handleToolStart(
+    tool: any,
+    input: string,
+    runId: string,
+    _parentRunId?: string
+  ): Promise<void> {
+    const toolName = tool.name || 'unknown-tool';
+    const span = this.tracer.startSpan(`tool:${toolName}`, {
+      attributes: {
+        type: 'tool',
+        tool_name: toolName,
+        tool_description: tool.description,
+        input_length: typeof input === 'string' ? input.length : 0,
+      },
+    });
+
+    this.spanStack.set(runId, span);
+  }
+
+  /**
+   * Handle tool end - called when a tool finishes execution.
+   */
+  public async handleToolEnd(output: string, runId: string): Promise<void> {
+    const span = this.spanStack.get(runId);
+    if (span) {
+      try {
+        span.setAttribute('output_length', output?.length || 0);
+      } catch (error) {
+        // Silently fail
+      }
+
+      span.end();
+      this.spanStack.delete(runId);
+    }
+  }
+
+  /**
+   * Handle tool error.
+   */
+  public async handleToolError(error: Error, runId: string): Promise<void> {
+    const span = this.spanStack.get(runId);
+    if (span) {
+      span.recordException(error, { source: 'langchain-tool' });
+      span.end();
+      this.spanStack.delete(runId);
+    }
+  }
+
+  /**
+   * Handle agent action.
+   */
+  public async handleAgentAction(action: any, runId: string): Promise<void> {
+    const span = this.spanStack.get(runId);
+    if (span) {
+      try {
+        span.setAttribute('agent_action', action.tool);
+      } catch (error) {
+        // Silently fail
+      }
+    }
+  }
+
+  /**
+   * Handle agent finish.
+   */
+  public async handleAgentFinish(finish: any, runId: string): Promise<void> {
+    const span = this.spanStack.get(runId);
+    if (span) {
+      try {
+        span.setAttribute('agent_finish_output', JSON.stringify(finish.returnValues));
+      } catch (error) {
+        // Silently fail
+      }
+
+      span.end();
+      this.spanStack.delete(runId);
+    }
+  }
+}

package/src/integrations/langgraph-instrumentation.ts

@@ -0,0 +1,174 @@
+/**
+ * LangGraph instrumentation for automatic tracing.
+ * Provides utilities to instrument LangGraph state graphs for automatic tracing.
+ */
+
+import { getTracer } from '../auto';
+
+/**
+ * Instrument a LangGraph to automatically trace execution.
+ * Wraps graph invocation to create spans for the entire graph execution.
+ *
+ * @example
+ * import { StateGraph } from 'langchain/graph';
+ * import { instrumentLangGraph } from '@traccia/sdk/integrations/langgraph';
+ *
+ * const graph = new StateGraph(AgentState)
+ *   .addNode('agent', agentNode)
+ *   .addNode('tools', toolsNode)
+ *   .addEdge('agent', 'tools')
+ *   .addEdge('tools', 'agent');
+ *
+ * const instrumented = instrumentLangGraph(graph, { graphName: 'my-agent' });
+ * const compiled = instrumented.compile();
+ *
+ * await compiled.invoke({ messages: [...] });
+ * // Automatically traced with span for graph execution
+ */
+export function instrumentLangGraph(graph: any, options?: { graphName?: string }): any {
+  const tracer = getTracer('langgraph');
+  const graphName = options?.graphName || graph.graph_name || 'langgraph';
+
+  // Store original compile method
+  const originalCompile = graph.compile.bind(graph);
+
+  // Override compile to wrap invocation
+  graph.compile = function() {
+    const compiled = originalCompile();
+    const originalInvoke = compiled.invoke.bind(compiled);
+    const originalStream = compiled.stream?.bind(compiled);
+
+    /**
+     * Wrap invoke calls with tracing.
+     */
+    compiled.invoke = async function(input: any, config?: any) {
+      const span = tracer.startSpan('langgraph-invoke', {
+        attributes: {
+          graph_name: graphName,
+          config_thread_id: config?.configurable?.thread_id,
+        },
+      });
+
+      try {
+        const result = await originalInvoke(input, config);
+        span.end();
+        return result;
+      } catch (error) {
+        span.recordException(error as Error, { context: 'langgraph-invoke' });
+        span.end();
+        throw error;
+      }
+    };
+
+    /**
+     * Wrap stream calls with tracing.
+     */
+    if (originalStream) {
+      compiled.stream = async function*(input: any, config?: any) {
+        const span = tracer.startSpan('langgraph-stream', {
+          attributes: {
+            graph_name: graphName,
+            config_thread_id: config?.configurable?.thread_id,
+          },
+        });
+
+        let eventCount = 0;
+        try {
+          for await (const event of originalStream(input, config)) {
+            eventCount++;
+            yield event;
+          }
+          span.setAttribute('stream_events', eventCount);
+          span.end();
+        } catch (error) {
+          span.recordException(error as Error, { context: 'langgraph-stream' });
+          span.setAttribute('stream_events', eventCount);
+          span.end();
+          throw error;
+        }
+      };
+    }
+
+    return compiled;
+  };
+
+  return graph;
+}
+
+/**
+ * Create a traced node function wrapper for LangGraph nodes.
+ * Automatically wraps node execution with tracing spans.
+ *
+ * @example
+ * import { createTracedNode } from '@traccia/sdk/integrations/langgraph';
+ *
+ * const agentNode = createTracedNode('agent', async (state) => {
+ *   // Your agent logic here
+ *   return { messages: [...] };
+ * });
+ *
+ * graph.addNode('agent', agentNode);
+ */
+export function createTracedNode(
+  nodeName: string,
+  nodeFunc: (state: any) => Promise<any>
+): (state: any) => Promise<any> {
+  const tracer = getTracer('langgraph');
+
+  return async function tracedNode(state: any) {
+    const span = tracer.startSpan(`node:${nodeName}`, {
+      attributes: {
+        node_name: nodeName,
+      },
+    });
+
+    try {
+      const result = await nodeFunc(state);
+      span.end();
+      return result;
+    } catch (error) {
+      span.recordException(error as Error, { node: nodeName });
+      span.end();
+      throw error;
+    }
+  };
+}
+
+/**
+ * Create a traced conditional edge function for LangGraph.
+ * Wraps conditional routing logic with tracing.
+ *
+ * @example
+ * import { createTracedConditional } from '@traccia/sdk/integrations/langgraph';
+ *
+ * const shouldContinue = createTracedConditional('should_continue', (state) => {
+ *   return state.messages.length > 10 ? 'end' : 'continue';
+ * });
+ *
+ * graph.addConditionalEdges('agent', shouldContinue);
+ */
+export function createTracedConditional(
+  conditionName: string,
+  conditionFunc: (state: any) => string
+): (state: any) => string {
+  const tracer = getTracer('langgraph');
+
+  return function tracedConditional(state: any) {
+    const span = tracer.startSpan(`condition:${conditionName}`, {
+      attributes: {
+        condition_name: conditionName,
+      },
+    });
+
+    try {
+      const result = conditionFunc(state);
+      span.setAttribute('condition_result', result);
+      span.end();
+      return result;
+    } catch (error) {
+      span.recordException(error as Error, { condition: conditionName });
+      span.end();
+      throw error;
+    }
+  };
+}

package/src/processor/batch-processor.ts

@@ -0,0 +1,180 @@
+/**
+ * Batch span processor with queue management and background flush.
+ */
+
+import { ISpan, ISpanProcessor, ISpanExporter } from '../types';
+import { ISampler } from '../types';
+
+const DEFAULT_MAX_QUEUE_SIZE = 5000;
+const DEFAULT_MAX_EXPORT_BATCH_SIZE = 512;
+const DEFAULT_SCHEDULE_DELAY_MS = 5000;
+
+/**
+ * Drop policy for handling queue overflow.
+ */
+export enum DropPolicy {
+  DROP_OLDEST = 'drop_oldest',
+  DROP_NEWEST = 'drop_newest',
+}
+
+/**
+ * Batch span processor.
+ */
+export class BatchSpanProcessor implements ISpanProcessor {
+  private exporter?: ISpanExporter;
+  private maxQueueSize: number;
+  private maxExportBatchSize: number;
+  private scheduleDelayMs: number;
+  private dropPolicy: DropPolicy;
+  private sampler?: ISampler;
+
+  private queue: ISpan[] = [];
+  private _shutdown = false;
+  private timer?: NodeJS.Timeout;
+  private processing = false;
+
+  constructor(options: {
+    exporter?: ISpanExporter;
+    maxQueueSize?: number;
+    maxExportBatchSize?: number;
+    scheduleDelayMs?: number;
+    dropPolicy?: DropPolicy;
+    sampler?: ISampler;
+  } = {}) {
+    this.exporter = options.exporter;
+    this.maxQueueSize = options.maxQueueSize || DEFAULT_MAX_QUEUE_SIZE;
+    this.maxExportBatchSize = options.maxExportBatchSize || DEFAULT_MAX_EXPORT_BATCH_SIZE;
+    this.scheduleDelayMs = options.scheduleDelayMs || DEFAULT_SCHEDULE_DELAY_MS;
+    this.dropPolicy = options.dropPolicy || DropPolicy.DROP_OLDEST;
+    this.sampler = options.sampler;
+
+    this.startSchedule();
+  }
+
+  /**
+   * Handle span end.
+   */
+  onEnd(span: ISpan): void {
+    if (this._shutdown) {
+      return;
+    }
+
+    // Apply head-based sampling: drop non-sampled traces
+    if (this.sampler && span.context.traceFlags === 0) {
+      return;
+    }
+
+    this.enqueue(span);
+  }
+
+  /**
+   * Force flush pending spans.
+   */
+  async forceFlush(timeout?: number): Promise<void> {
+    const deadline = timeout ? Date.now() + timeout : undefined;
+
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const flushed = await this.flushOnce(deadline);
+      if (!flushed || (deadline && Date.now() >= deadline)) {
+        break;
+      }
+    }
+  }
+
+  /**
+   * Shutdown the processor.
+   */
+  async shutdown(): Promise<void> {
+    this._shutdown = true;
+    if (this.timer) {
+      clearTimeout(this.timer);
+    }
+    await this.forceFlush();
+    if (this.exporter) {
+      await this.exporter.shutdown();
+    }
+  }
+
+  /**
+   * Enqueue a span.
+   */
+  private enqueue(span: ISpan): void {
+    if (this.queue.length >= this.maxQueueSize) {
+      if (this.dropPolicy === DropPolicy.DROP_OLDEST) {
+        this.queue.shift();
+      } else {
+        return; // Drop newest
+      }
+    }
+    this.queue.push(span);
+  }
+
+  /**
+   * Flush once (export one batch).
+   */
+  private async flushOnce(deadline?: number): Promise<boolean> {
+    if (this.processing) {
+      return false;
+    }
+
+    if (deadline && Date.now() >= deadline) {
+      return false;
+    }
+
+    const batch = this.drainQueue(this.maxExportBatchSize);
+    if (batch.length === 0) {
+      return false;
+    }
+
+    await this.export(batch);
+    return true;
+  }
+
+  /**
+   * Drain queue.
+   */
+  private drainQueue(limit: number): ISpan[] {
+    const batch: ISpan[] = [];
+    while (batch.length < limit && this.queue.length > 0) {
+      const span = this.queue.shift();
+      if (span) {
+        batch.push(span);
+      }
+    }
+    return batch;
+  }
+
+  /**
+   * Export spans.
+   */
+  private async export(spans: ISpan[]): Promise<void> {
+    if (!this.exporter) {
+      return;
+    }
+
+    this.processing = true;
+    try {
+      await this.exporter.export(spans);
+    } catch {
+      // Export errors are swallowed for resilience
+    } finally {
+      this.processing = false;
+    }
+  }
+
+  /**
+   * Start the background scheduling.
+   */
+  private startSchedule(): void {
+    // eslint-disable-next-line @typescript-eslint/no-misused-promises
+    this.timer = setInterval(async () => {
+      await this.flushOnce();
+    }, this.scheduleDelayMs);
+
+    // Ensure the timer doesn't keep the process alive
+    if (this.timer.unref) {
+      this.timer.unref();
+    }
+  }
+}

package/src/processor/cost-processor.ts

@@ -0,0 +1,57 @@
+/**
+ * Cost annotation processor.
+ */
+
+import { ISpan, ISpanProcessor } from '../types';
+import { PricingTable } from '../config/pricing-config';
+
+/**
+ * Cost annotation processor.
+ */
+export class CostAnnotatingProcessor implements ISpanProcessor {
+  private pricingTable: PricingTable;
+
+  constructor(pricingTable: PricingTable) {
+    this.pricingTable = pricingTable;
+  }
+
+  onEnd(span: ISpan): void {
+    try {
+      const model = span.attributes['model'] as string | undefined;
+      if (!model) {
+        return;
+      }
+
+      const pricing = this.pricingTable[model];
+      if (!pricing) {
+        return;
+      }
+
+      const inputTokens = span.attributes['input_tokens'] as number | undefined;
+      const outputTokens = span.attributes['output_tokens'] as number | undefined;
+
+      let cost = 0;
+      if (inputTokens) {
+        cost += (inputTokens / 1000) * pricing.inputCost;
+      }
+      if (outputTokens) {
+        cost += (outputTokens / 1000) * pricing.outputCost;
+      }
+
+      if (cost > 0) {
+        // Direct attribute modification for processors (after span ends)
+        span.attributes['cost_usd'] = cost;
+      }
+    } catch {
+      // Silently fail
+    }
+  }
+
+  async shutdown(): Promise<void> {
+    // No-op
+  }
+
+  async forceFlush(): Promise<void> {
+    // No-op
+  }
+}

package/src/processor/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Processor module exports.
+ */
+
+export { Sampler } from './sampler';
+export { BatchSpanProcessor, DropPolicy } from './batch-processor';
+export { TokenCountingProcessor } from './token-counter';
+export { CostAnnotatingProcessor } from './cost-processor';
+export { LoggingSpanProcessor } from './logging-processor';

package/src/processor/logging-processor.ts

@@ -0,0 +1,26 @@
+/**
+ * Logging span processor for debugging.
+ */
+
+import { ISpan, ISpanProcessor } from '../types';
+
+/**
+ * Logging span processor.
+ */
+export class LoggingSpanProcessor implements ISpanProcessor {
+  onEnd(span: ISpan): void {
+    console.log(`[Span] ${span.name} (${span.context.traceId})`, {
+      spanId: span.context.spanId,
+      duration: span.durationNs,
+      attributes: span.attributes,
+    });
+  }
+
+  async shutdown(): Promise<void> {
+    // No-op
+  }
+
+  async forceFlush(): Promise<void> {
+    // No-op
+  }
+}

package/src/processor/sampler.ts

@@ -0,0 +1,35 @@
+/**
+ * Sampler for making sampling decisions.
+ */
+
+import { ISampler, SamplingResult } from '../types';
+
+/**
+ * Probability-based sampler.
+ */
+export class Sampler implements ISampler {
+  private sampleRate: number;
+
+  constructor(sampleRate: number = 1.0) {
+    if (sampleRate < 0 || sampleRate > 1) {
+      throw new Error('sampleRate must be between 0.0 and 1.0');
+    }
+    this.sampleRate = sampleRate;
+  }
+
+  /**
+   * Decide whether to sample.
+   */
+  shouldSample(): SamplingResult {
+    return {
+      sampled: Math.random() <= this.sampleRate,
+    };
+  }
+
+  /**
+   * Get the current sample rate.
+   */
+  getSampleRate(): number {
+    return this.sampleRate;
+  }
+}