@traccia2/sdk 0.0.1

package/src/exporter/http-exporter.ts

@@ -0,0 +1,188 @@
+/**
+ * HTTP Exporter for sending spans to a backend service.
+ */
+
+import * as https from 'https';
+import * as http from 'http';
+import { ISpan, ISpanExporter } from '../types';
+
+export const DEFAULT_ENDPOINT = 'https://api.dashboard.com/api/v1/traces';
+
+const TRANSIENT_STATUS_CODES = new Set([429, 503, 504]);
+
+/**
+ * HTTP Exporter configuration.
+ */
+export interface HttpExporterOptions {
+  endpoint?: string;
+  apiKey?: string;
+  timeout?: number;
+  maxRetries?: number;
+  backoffBase?: number;
+  backoffJitter?: number;
+}
+
+/**
+ * HTTP Exporter for sending spans to a backend.
+ */
+export class HttpExporter implements ISpanExporter {
+  private endpoint: string;
+  private apiKey?: string;
+  private timeout: number;
+  private maxRetries: number;
+  private backoffBase: number;
+  private backoffJitter: number;
+
+  constructor(options: HttpExporterOptions = {}) {
+    this.endpoint = options.endpoint || DEFAULT_ENDPOINT;
+    this.apiKey = options.apiKey;
+    this.timeout = options.timeout || 10000;
+    this.maxRetries = options.maxRetries || 5;
+    this.backoffBase = options.backoffBase || 1;
+    this.backoffJitter = options.backoffJitter || 0.5;
+  }
+
+  /**
+   * Export spans to the backend.
+   */
+  async export(spans: ISpan[]): Promise<boolean> {
+    if (spans.length === 0) {
+      return true;
+    }
+
+    const payload = this.serializeSpans(spans);
+    const headers = this.getHeaders();
+
+    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+      try {
+        const status = await this.sendRequest(payload, headers);
+
+        if (status >= 200 && status < 300) {
+          return true;
+        }
+
+        if (!TRANSIENT_STATUS_CODES.has(status)) {
+          return false;
+        }
+
+        const backoff = this.computeBackoff(attempt);
+        await this.sleep(backoff);
+      } catch {
+        // Treat transport errors as transient
+        if (attempt < this.maxRetries - 1) {
+          const backoff = this.computeBackoff(attempt);
+          await this.sleep(backoff);
+        }
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Shutdown the exporter.
+   */
+  async shutdown(): Promise<void> {
+    // No-op for HTTP exporter
+  }
+
+  /**
+   * Serialize spans to JSON bytes.
+   */
+  private serializeSpans(spans: ISpan[]): string {
+    const serialized = spans.map((span) => ({
+      traceId: span.context.traceId,
+      spanId: span.context.spanId,
+      parentSpanId: span.parentSpanId,
+      name: span.name,
+      startTimeNs: span.startTimeNs,
+      endTimeNs: span.endTimeNs,
+      durationNs: span.durationNs,
+      attributes: span.attributes,
+      events: span.events,
+      status: span.status,
+      statusDescription: span.statusDescription,
+      traceFlags: span.context.traceFlags,
+      traceState: span.context.traceState,
+    }));
+
+    return JSON.stringify(serialized);
+  }
+
+  /**
+   * Get request headers.
+   */
+  private getHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'User-Agent': 'traccia-sdk-ts/1.0.0',
+    };
+
+    if (this.apiKey) {
+      headers['Authorization'] = `Bearer ${this.apiKey}`;
+    }
+
+    return headers;
+  }
+
+  /**
+   * Send HTTP request.
+   */
+  private sendRequest(payload: string, headers: Record<string, string>): Promise<number> {
+    return new Promise((resolve, reject) => {
+      const url = new URL(this.endpoint);
+      const isHttps = url.protocol === 'https:';
+      const client = isHttps ? https : http;
+
+      const options = {
+        hostname: url.hostname,
+        port: url.port,
+        path: url.pathname + url.search,
+        method: 'POST',
+        headers: {
+          ...headers,
+          'Content-Length': Buffer.byteLength(payload),
+        },
+        timeout: this.timeout,
+      };
+
+      const request = client.request(options, (response) => {
+        response.on('data', () => {
+          // Consume data but don't store
+        });
+
+        response.on('end', () => {
+          resolve(response.statusCode || 500);
+        });
+      });
+
+      request.on('error', (error) => {
+        reject(error);
+      });
+
+      request.on('timeout', () => {
+        request.destroy();
+        reject(new Error('Request timeout'));
+      });
+
+      request.write(payload);
+      request.end();
+    });
+  }
+
+  /**
+   * Compute exponential backoff with jitter.
+   */
+  private computeBackoff(attempt: number): number {
+    const exponential = this.backoffBase * Math.pow(2, attempt);
+    const jitter = Math.random() * this.backoffJitter;
+    return (exponential + jitter) * 1000;
+  }
+
+  /**
+   * Sleep for a given number of milliseconds.
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}

package/src/exporter/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Exporter module exports.
+ */
+
+export { HttpExporter, DEFAULT_ENDPOINT } from './http-exporter';
+export type { HttpExporterOptions } from './http-exporter';
+export { ConsoleExporter } from './console-exporter';

package/src/index.ts

@@ -0,0 +1,51 @@
+/**
+ * Main SDK entry point.
+ */
+
+export {
+  getTracer,
+  getTracerProvider,
+  setTracerProvider,
+  startTracing,
+  stopTracing,
+} from './auto';
+
+export {
+  TracerProvider,
+  Tracer,
+  Span,
+  SpanContext,
+} from './tracer';
+
+export {
+  HttpExporter,
+  ConsoleExporter,
+} from './exporter';
+
+export {
+  Sampler,
+  BatchSpanProcessor,
+  TokenCountingProcessor,
+  CostAnnotatingProcessor,
+  LoggingSpanProcessor,
+} from './processor';
+
+export type {
+  ISpan,
+  ITracer,
+  ITracerProvider,
+  ISpanContext,
+  ISpanProcessor,
+  ISpanExporter,
+  ISampler,
+  SDKConfig,
+  Resource,
+  SpanEvent,
+  SamplingResult,
+} from './types';
+
+export { SpanStatus } from './types';
+
+// Integrations (optional)
+// Import from '@traccia/sdk/integrations' for framework-specific integrations
+// See src/integrations/README.md for documentation

package/src/integrations/README.md

@@ -0,0 +1,287 @@
+# Traccia SDK Integrations
+
+Automatic instrumentation for popular frameworks and libraries. These integrations seamlessly add tracing to your applications without changing your code.
+
+## Available Integrations
+
+### LangChain Integration
+
+Automatically trace LangChain agents, chains, and tools without any code changes.
+
+#### Installation
+
+```bash
+npm install langchain @traccia/sdk
+```
+
+#### Usage
+
+```typescript
+import { ChatOpenAI } from 'langchain/chat_models/openai';
+import { AgentExecutor, createOpenAIToolsAgent } from 'langchain/agents';
+import { Tool } from '@langchain/core/tools';
+import { TraciaCallbackHandler } from '@traccia/sdk/integrations/langchain-callback';
+
+// Create your agent as usual
+const tools = [/* your tools */];
+const llm = new ChatOpenAI({ modelName: 'gpt-4' });
+
+// Create Traccia callback handler
+const traciaHandler = new TraciaCallbackHandler();
+
+// Add callback to your chain/agent
+const agent = await createOpenAIToolsAgent({ llm, tools, callbacks: [traciaHandler] });
+const executor = new AgentExecutor({ agent, tools, callbacks: [traciaHandler] });
+
+// Use as normal - fully traced!
+const result = await executor.invoke({ input: 'What is 2+2?' });
+```
+
+#### Automatic Tracing Features
+
+- **LLM Calls**: Captures model name, prompt length, completion tokens, total tokens
+- **Chain Execution**: Traces chain start/end with chain name and execution time
+- **Tool Usage**: Records tool invocations, inputs, and outputs
+- **Agent Actions**: Captures agent decisions and reasoning steps
+- **Error Handling**: Records exceptions and failures with full context
+- **Nested Execution**: Automatically handles nested chains and tool calls through runId hierarchy
+
+#### Span Hierarchy
+
+Spans are automatically organized in a hierarchy:
+
+```
+agent-executor (root)
+├── chain-1 (input processing)
+│   └── llm-call (model inference)
+├── tool-1 (tool execution)
+│   └── api-call
+└── chain-2 (final processing)
+```
+
+### LangGraph Integration
+
+Automatic instrumentation for LangGraph state graphs and node execution.
+
+#### Installation
+
+```bash
+npm install langraph @traccia/sdk
+```
+
+#### Usage - Option 1: Instrument Graph
+
+```typescript
+import { StateGraph } from '@langchain/langgraph';
+import { instrumentLangGraph } from '@traccia/sdk/integrations/langgraph';
+
+const graph = new StateGraph(AgentState)
+  .addNode('agent', agentNode)
+  .addNode('tools', toolsNode)
+  .addEdge('agent', 'tools');
+
+// Instrument for automatic tracing
+const instrumentedGraph = instrumentLangGraph(graph, {
+  graphName: 'my-agent-graph',
+});
+
+const compiled = instrumentedGraph.compile();
+
+// Automatically traced!
+await compiled.invoke({ messages: [] });
+```
+
+#### Usage - Option 2: Trace Individual Nodes
+
+```typescript
+import { createTracedNode } from '@traccia/sdk/integrations/langgraph';
+
+const agentNode = createTracedNode('agent', async (state) => {
+  // Your agent logic
+  return { messages: [...state.messages, response] };
+});
+
+const toolsNode = createTracedNode('tools', async (state) => {
+  // Your tool logic
+  return { messages: [...state.messages, results] };
+});
+
+const graph = new StateGraph(AgentState)
+  .addNode('agent', agentNode)
+  .addNode('tools', toolsNode);
+```
+
+#### Usage - Option 3: Trace Conditionals
+
+```typescript
+import { createTracedConditional } from '@traccia/sdk/integrations/langgraph';
+
+const shouldContinue = createTracedConditional('should_continue', (state) => {
+  const messages = state.messages;
+  if (messages[messages.length - 1].tool_calls) {
+    return 'tools';
+  }
+  return 'end';
+});
+
+graph.addConditionalEdges('agent', shouldContinue);
+```
+
+#### Automatic Tracing Features
+
+- **Graph Execution**: Root span for entire graph invocation
+- **Streaming**: Traces streaming calls with event counts
+- **Node Execution**: Individual spans for each node with execution context
+- **Conditionals**: Records conditional routing decisions
+- **Thread Context**: Captures thread_id for multi-turn conversations
+- **Error Handling**: Records failures at any level with full stack traces
+
+#### Span Hierarchy
+
+```
+langgraph-invoke (root)
+├── node:agent
+├── condition:should_continue
+└── node:tools
+```
+
+## Configuration
+
+Both integrations respect the standard Traccia SDK configuration through environment variables:
+
+```bash
+# Enable tracing
+AGENT_DASHBOARD_ENABLED=true
+
+# Set API endpoint and key (if using HTTP exporter)
+AGENT_DASHBOARD_API_ENDPOINT=http://localhost:3000
+AGENT_DASHBOARD_API_KEY=your-key
+
+# Sampling and processing
+AGENT_DASHBOARD_SAMPLE_RATE=1.0
+AGENT_DASHBOARD_BATCH_SIZE=10
+AGENT_DASHBOARD_BATCH_INTERVAL_MS=5000
+```
+
+See [Configuration Guide](../README.md#configuration) for all options.
+
+## Error Handling
+
+All integrations implement graceful error handling:
+
+- Integration errors don't crash your application
+- Failed spans are silently dropped if span system has issues
+- Exceptions are recorded to spans with full context
+- Stream/async processing continues on errors
+
+## Performance Considerations
+
+### Overhead
+
+- **LangChain**: ~1-2ms per span creation (async, non-blocking)
+- **LangGraph**: ~2-3ms per node execution overhead
+- **Network**: Async batch export (configurable delays)
+
+### Optimization Tips
+
+1. **Increase Batch Size** for high-throughput apps:
+   ```bash
+   AGENT_DASHBOARD_BATCH_SIZE=100
+   ```
+
+2. **Use Sampling** to reduce data volume:
+   ```bash
+   AGENT_DASHBOARD_SAMPLE_RATE=0.1  # 10% sampling
+   ```
+
+3. **Disable Cost Tracking** if not needed:
+   ```bash
+   AGENT_DASHBOARD_ENABLE_COST_TRACKING=false
+   ```
+
+4. **Use Console Exporter** for development:
+   ```typescript
+   import { ConsoleExporter } from '@traccia/sdk';
+   // No network overhead
+   ```
+
+## Testing
+
+When testing applications with integrations, consider:
+
+```typescript
+import { ConsoleExporter } from '@traccia/sdk';
+import { startTracing } from '@traccia/sdk';
+
+// In test setup
+startTracing({
+  exporters: [new ConsoleExporter()],  // Avoid network calls
+  enableTokenCounting: false,           // Skip token count overhead
+});
+
+// Your tests run with tracing enabled but no external calls
+```
+
+## Best Practices
+
+1. **Initialize Before Creating Tools/Agents**:
+   ```typescript
+   // ✅ Good
+   startTracing({ /* config */ });
+   const llm = new ChatOpenAI();
+   const handler = new TraciaCallbackHandler();
+
+   // ❌ Avoid
+   const llm = new ChatOpenAI();
+   startTracing();
+   ```
+
+2. **Reuse Handler Instances**:
+   ```typescript
+   // ✅ Good - one handler for all chains
+   const handler = new TraciaCallbackHandler();
+   const executor1 = new AgentExecutor({ callbacks: [handler] });
+   const executor2 = new AgentExecutor({ callbacks: [handler] });
+
+   // ❌ Avoid - new handler for each (more overhead)
+   const executor1 = new AgentExecutor({ callbacks: [new TraciaCallbackHandler()] });
+   ```
+
+3. **Use Graph Instrumentation Over Node Wrapping** (when possible):
+   ```typescript
+   // ✅ Good - cleaner API
+   const graph = instrumentLangGraph(graph);
+
+   // ✅ Also good - when you need fine-grained control
+   const agentNode = createTracedNode('agent', func);
+   ```
+
+4. **Capture Domain-Specific Attributes**:
+   ```typescript
+   // Extend with custom metadata
+   const handler = new TraciaCallbackHandler();
+   // (Future: custom span enrichment support)
+   ```
+
+## Limitations & Known Issues
+
+- **LangChain**: Requires langchain ≥ 0.1.0 (callback system)
+- **LangGraph**: Works with compiled graphs; streaming has event-level tracking
+- **Context Propagation**: Traces are linked through runId hierarchy; distributed tracing requires parent trace context
+
+## Contributing
+
+To add new integrations:
+
+1. Create `src/integrations/{framework}-instrumentation.ts`
+2. Export in `src/integrations/index.ts`
+3. Add usage documentation here
+4. Submit PR with tests and examples
+
+## Support
+
+For issues or questions:
+
+- 📖 [Main README](../README.md)
+- 🐛 [GitHub Issues](https://github.com/stratumtech/traccia-sdk)
+- 💬 [Discussions](https://github.com/stratumtech/traccia-sdk/discussions)

package/src/integrations/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Traccia SDK Integrations
+ * Provides automatic instrumentation for popular frameworks and libraries.
+ *
+ * @module integrations
+ */
+
+export { TraciaCallbackHandler } from './langchain-callback';
+export {
+  instrumentLangGraph,
+  createTracedNode,
+  createTracedConditional,
+} from './langgraph-instrumentation';