@traccia2/sdk 0.0.1

package/LICENSE

@@ -0,0 +1,23 @@
+# License
+
+MIT License
+
+Copyright (c) 2024 Traccia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,503 @@
+# Traccia SDK for TypeScript
+
+Production-grade distributed tracing SDK for agent applications. Built with TypeScript and designed for high performance, reliability, and ease of integration.
+
+## Features
+
+- **Distributed Tracing**: Create, propagate, and manage spans across service boundaries
+- **Automatic Instrumentation**: Optional auto-instrumentation for popular LLM libraries (OpenAI, Anthropic)
+- **Span Processors**: Built-in processors for sampling, batching, token counting, and cost analysis
+- **Token & Cost Tracking**: Automatic token counting and cost calculation for LLM calls
+- **Flexible Exporters**: Export spans via HTTP, console, or custom exporters
+- **Context Management**: Automatic context propagation using AsyncLocalStorage
+- **Production Ready**: Thread-safe, performant, and battle-tested patterns
+
+## Installation
+
+```bash
+npm install @traccia/sdk
+```
+
+## Quick Start
+
+### Basic Setup
+
+```typescript
+import { startTracing, getTracer } from '@traccia/sdk';
+
+// Initialize tracing
+await startTracing({
+  apiKey: 'your-api-key',
+  endpoint: 'https://api.example.com/traces',
+});
+
+// Get a tracer
+const tracer = getTracer('my-app');
+
+// Create a span
+const span = tracer.startSpan('process-request', {
+  attributes: {
+    userId: '123',
+    action: 'process',
+  },
+});
+
+try {
+  // Do work
+  span.setAttribute('status', 'success');
+} catch (error) {
+  span.recordException(error as Error);
+} finally {
+  span.end();
+}
+```
+
+### Using Active Spans
+
+For better context management, use active spans which automatically handle parent-child relationships:
+
+```typescript
+const tracer = getTracer('my-app');
+
+await tracer.startActiveSpan('api-call', async (span) => {
+  span.setAttribute('method', 'POST');
+  
+  // Child spans automatically use this span as parent
+  const childSpan = tracer.startSpan('database-query');
+  // ... do work ...
+  childSpan.end();
+});
+```
+
+### Configuration
+
+Pass a `SDKConfig` object to `startTracing()`:
+
+```typescript
+interface SDKConfig {
+  // API Configuration
+  apiKey?: string;                    // API key for authentication
+  endpoint?: string;                  // Backend endpoint URL
+  
+  // Sampling
+  sampleRate?: number;                // Span sampling rate (0.0 to 1.0)
+  
+  // Queue Management
+  maxQueueSize?: number;              // Max pending spans (default: 5000)
+  maxExportBatchSize?: number;        // Max spans per export (default: 512)
+  scheduleDelayMs?: number;           // Flush interval (default: 5000)
+  
+  // Features
+  enableConsoleExporter?: boolean;    // Also log to console
+  enableTokenCounting?: boolean;      // Auto-count tokens (default: true)
+  enableCostTracking?: boolean;       // Calculate costs (default: true)
+  enableSpanLogging?: boolean;        // Log spans to console
+  
+  // Context
+  sessionId?: string;                 // Session identifier
+  userId?: string;                    // User identifier
+  tenantId?: string;                  // Tenant identifier
+  projectId?: string;                 // Project identifier
+  
+  // Instrumentation
+  autoInstrument?: boolean;           // Enable auto-instrumentation
+  toolInclude?: string[];             // Which tools to instrument
+  maxToolSpans?: number;              // Max tool spans (default: 100)
+  maxSpanDepth?: number;              // Max depth (default: 10)
+  
+  // Debugging
+  debug?: boolean;                    // Force sampling all traces
+  attrTruncationLimit?: number;       // Max attribute size
+  
+  // Environment
+  loadEnv?: boolean;                  // Load .env file
+  pricingOverride?: PricingTable;     // Custom pricing
+  
+  resource?: Resource;                // Service resource info
+}
+```
+
+### Environment Variables
+
+Configure via environment variables (useful for deployment):
+
+```bash
+# Authentication
+AGENT_DASHBOARD_API_KEY=your-key
+
+# Backend
+AGENT_DASHBOARD_ENDPOINT=https://api.example.com/traces
+
+# Sampling
+AGENT_DASHBOARD_SAMPLE_RATE=0.1
+
+# Pricing (JSON string)
+AGENT_DASHBOARD_PRICING_JSON='{"gpt-4":{"inputCost":0.03,"outputCost":0.06}}'
+```
+
+### .env File
+
+Create a `.env` file in your project root:
+
+```
+AGENT_DASHBOARD_API_KEY=your-api-key
+AGENT_DASHBOARD_ENDPOINT=https://api.example.com/traces
+AGENT_DASHBOARD_SAMPLE_RATE=1.0
+```
+
+## API Reference
+
+### Tracer
+
+#### `startSpan(name, options?): ISpan`
+
+Create a new span.
+
+```typescript
+const span = tracer.startSpan('operation', {
+  attributes: {
+    userId: '123',
+    action: 'create',
+  },
+  parent: parentSpan, // Optional: explicit parent
+});
+```
+
+#### `startActiveSpan(name, fn, options?): Promise<any>`
+
+Create an active span and run a function within it. Automatically handles parent-child relationships.
+
+```typescript
+const result = await tracer.startActiveSpan(
+  'api-call',
+  async (span) => {
+    span.setAttribute('endpoint', '/users');
+    // Nested spans automatically use this as parent
+    return await fetchUser('123');
+  },
+  {
+    attributes: { timeout: 5000 },
+  }
+);
+```
+
+### Span
+
+#### `setAttribute(key, value): void`
+
+Set an attribute on the span.
+
+```typescript
+span.setAttribute('userId', '123');
+span.setAttribute('items', 5);
+```
+
+#### `addEvent(name, attributes?): void`
+
+Add an event to the span.
+
+```typescript
+span.addEvent('cache-hit', {
+  cacheKey: 'user:123',
+  ttl: 3600,
+});
+```
+
+#### `recordException(error, attributes?): void`
+
+Record an exception on the span.
+
+```typescript
+try {
+  // do work
+} catch (error) {
+  span.recordException(error as Error, {
+    errorType: 'NetworkError',
+  });
+}
+```
+
+#### `end(): void`
+
+End the span and mark it for export.
+
+```typescript
+span.end();
+```
+
+#### Properties
+
+- `context: ISpanContext` - Span context (trace ID, span ID, flags)
+- `name: string` - Span name
+- `attributes: Record<string, unknown>` - Span attributes
+- `events: SpanEvent[]` - Recorded events
+- `status: SpanStatus` - Span status (UNSET, OK, ERROR)
+- `durationNs: number | undefined` - Duration in nanoseconds
+- `isRecording(): boolean` - Whether span is still open
+
+### Processors
+
+The SDK includes several built-in processors:
+
+#### TokenCountingProcessor
+
+Automatically estimates token counts from text attributes:
+
+```typescript
+const tracer = getTracer('app');
+const span = tracer.startSpan('llm-call', {
+  attributes: {
+    prompt: 'Hello, how are you?',
+    completion: 'I am doing well, thank you!',
+  },
+});
+
+// After processing:
+span.attributes.input_tokens; // Auto-populated
+span.attributes.output_tokens; // Auto-populated
+```
+
+#### CostAnnotatingProcessor
+
+Calculates costs based on token counts and pricing:
+
+```typescript
+span.setAttribute('model', 'gpt-4');
+span.setAttribute('input_tokens', 100);
+span.setAttribute('output_tokens', 50);
+
+// After processing:
+span.attributes.cost_usd; // 0.003 (example)
+```
+
+#### LoggingSpanProcessor
+
+Logs completed spans to console (for debugging).
+
+#### BatchSpanProcessor
+
+Batches spans and exports them efficiently (enabled by default).
+
+### Global Functions
+
+#### `getTracer(name, version?): ITracer`
+
+Get a tracer instance.
+
+```typescript
+const tracer = getTracer('my-service', '1.0.0');
+```
+
+#### `getTracerProvider(): ITracerProvider`
+
+Get the global tracer provider.
+
+```typescript
+const provider = getTracerProvider();
+provider.forceFlush();
+```
+
+#### `setTracerProvider(provider): void`
+
+Override the global tracer provider (useful for testing).
+
+```typescript
+const testProvider = new TracerProvider();
+setTracerProvider(testProvider);
+```
+
+#### `startTracing(config): Promise<ITracerProvider>`
+
+Initialize the SDK with configuration.
+
+```typescript
+await startTracing({
+  apiKey: 'key',
+  sampleRate: 0.1,
+});
+```
+
+#### `stopTracing(): Promise<void>`
+
+Gracefully shutdown the SDK.
+
+```typescript
+await stopTracing();
+```
+
+## Advanced Usage
+
+### Custom Exporters
+
+Implement the `ISpanExporter` interface:
+
+```typescript
+import { ISpanExporter, ISpan } from '@traccia/sdk';
+
+class MyExporter implements ISpanExporter {
+  async export(spans: ISpan[]): Promise<boolean> {
+    // Send spans somewhere
+    console.log(`Exporting ${spans.length} spans`);
+    return true;
+  }
+
+  async shutdown(): Promise<void> {
+    // Cleanup
+  }
+}
+
+// Use it
+const provider = getTracerProvider();
+provider.addSpanProcessor(new BatchSpanProcessor({
+  exporter: new MyExporter(),
+}));
+```
+
+### Custom Processors
+
+Implement the `ISpanProcessor` interface:
+
+```typescript
+import { ISpanProcessor, ISpan } from '@traccia/sdk';
+
+class CustomProcessor implements ISpanProcessor {
+  onEnd(span: ISpan): void {
+    // Process span
+    if (span.name.startsWith('error')) {
+      // Handle errors
+    }
+  }
+
+  async shutdown(): Promise<void> {}
+  async forceFlush(): Promise<void> {}
+}
+
+// Use it
+const provider = getTracerProvider();
+provider.addSpanProcessor(new CustomProcessor());
+```
+
+### Span Context Propagation
+
+Spans are automatically propagated through `AsyncLocalStorage`:
+
+```typescript
+const tracer = getTracer('app');
+
+await tracer.startActiveSpan('parent', async () => {
+  // Nested span automatically gets parent as context
+  const childSpan = tracer.startSpan('child');
+  // childSpan.parentSpanId === parent.spanId
+});
+```
+
+### Force Flush
+
+Flush pending spans before shutdown:
+
+```typescript
+const provider = getTracerProvider();
+await provider.forceFlush(5000); // 5 second timeout
+await provider.shutdown();
+```
+
+## Performance Considerations
+
+### Sampling
+
+Use sampling to reduce span volume:
+
+```typescript
+await startTracing({
+  sampleRate: 0.1, // Keep 10% of traces
+});
+```
+
+### Batch Export
+
+Configure batching to optimize network usage:
+
+```typescript
+await startTracing({
+  maxExportBatchSize: 1024,  // Export up to 1024 spans
+  scheduleDelayMs: 10000,    // Flush every 10 seconds
+  maxQueueSize: 10000,       // Queue up to 10k spans
+});
+```
+
+### Attribute Management
+
+Keep attributes minimal and use truncation:
+
+```typescript
+await startTracing({
+  attrTruncationLimit: 256, // Max 256 chars per attribute
+});
+```
+
+## Testing
+
+The SDK includes comprehensive examples and tests:
+
+```typescript
+import { TracerProvider } from '@traccia/sdk';
+
+describe('My Integration', () => {
+  let provider: TracerProvider;
+  let tracer: ITracer;
+
+  beforeEach(() => {
+    provider = new TracerProvider();
+    tracer = provider.getTracer('test');
+  });
+
+  it('should create spans', () => {
+    const span = tracer.startSpan('test');
+    span.setAttribute('test', true);
+    span.end();
+
+    expect(span.endTimeNs).toBeDefined();
+  });
+});
+```
+
+## Error Handling
+
+The SDK is designed to be resilient:
+
+- **Processor errors** are silently caught to prevent cascading failures
+- **Export errors** trigger automatic retry with exponential backoff
+- **Configuration errors** are logged but don't prevent tracing
+
+For critical errors, enable debug mode:
+
+```typescript
+await startTracing({
+  debug: true,
+  enableSpanLogging: true,
+});
+```
+
+## Monitoring
+
+Monitor SDK health:
+
+```typescript
+const provider = getTracerProvider();
+
+// Force flush to ensure all spans are sent
+await provider.forceFlush(30000); // 30 second timeout
+```
+
+## Contributing
+
+Contributions are welcome! Please ensure:
+
+- Code passes linting: `npm run lint:fix`
+- Code is formatted: `npm run format`
+- Tests pass: `npm test`
+- Coverage is maintained
+
+## License
+
+MIT

package/dist/auto.d.ts

@@ -0,0 +1,27 @@
+/**
+ * SDK initialization and global tracer management.
+ */
+import { TracerProvider } from './tracer/provider';
+import { SDKConfig, ITracer } from './types';
+/**
+ * Get the global tracer provider.
+ */
+export declare function getTracerProvider(): TracerProvider;
+/**
+ * Set the global tracer provider.
+ */
+export declare function setTracerProvider(provider: TracerProvider): void;
+/**
+ * Get a tracer from the global provider.
+ */
+export declare function getTracer(name: string, version?: string): ITracer;
+/**
+ * Initialize tracing with automatic setup.
+ */
+export declare function startTracing(config?: SDKConfig): Promise<TracerProvider>;
+/**
+ * Stop tracing and shutdown all processors.
+ */
+export declare function stopTracing(): Promise<void>;
+export { getTracerProvider as initSDK };
+//# sourceMappingURL=auto.d.ts.map

package/dist/auto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto.d.ts","sourceRoot":"","sources":["../src/auto.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAiBnD,OAAO,EAAE,SAAS,EAAiB,OAAO,EAAE,MAAM,SAAS,CAAC;AAK5D;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAKlD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAEhE;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,MAAM,GAAE,SAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CA2FlF;AAED;;GAEG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAQjD;AAwCD,OAAO,EAAE,iBAAiB,IAAI,OAAO,EAAE,CAAC"}