@traccia2/sdk 0.0.1

package/src/processor/token-counter.ts

@@ -0,0 +1,42 @@
+/**
+ * Token counting processor for LLM spans.
+ */
+
+import { ISpan, ISpanProcessor } from '../types';
+
+const BYTES_PER_TOKEN = 4; // Rough approximation
+
+/**
+ * Token counting processor.
+ */
+export class TokenCountingProcessor implements ISpanProcessor {
+  onEnd(span: ISpan): void {
+    try {
+      // Estimate tokens from attributes if available
+      const promptText = span.attributes['prompt'] as string | undefined;
+      const completionText = span.attributes['completion'] as string | undefined;
+
+      if (promptText) {
+        const inputTokens = Math.ceil(promptText.length / BYTES_PER_TOKEN);
+        // Direct attribute modification for processors (after span ends)
+        span.attributes['input_tokens'] = inputTokens;
+      }
+
+      if (completionText) {
+        const outputTokens = Math.ceil(completionText.length / BYTES_PER_TOKEN);
+        // Direct attribute modification for processors (after span ends)
+        span.attributes['output_tokens'] = outputTokens;
+      }
+    } catch {
+      // Silently fail
+    }
+  }
+
+  async shutdown(): Promise<void> {
+    // No-op
+  }
+
+  async forceFlush(): Promise<void> {
+    // No-op
+  }
+}

package/src/tracer/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Tracer module exports.
+ */
+
+export { Span } from './span';
+export { SpanContext } from './span-context';
+export { Tracer } from './tracer';
+export { TracerProvider } from './provider';

package/src/tracer/provider.ts

@@ -0,0 +1,130 @@
+/**
+ * Tracer provider for managing tracers and span processors.
+ */
+
+import { randomBytes } from 'crypto';
+import { ITracerProvider, ITracer, ISpanProcessor, ISampler, ISpan } from '../types';
+import { Tracer } from './tracer';
+
+/**
+ * TracerProvider manages tracers and span processors.
+ */
+export class TracerProvider implements ITracerProvider {
+  private tracers: Map<string, Tracer> = new Map();
+  private spanProcessors: ISpanProcessor[] = [];
+  private sampler?: ISampler;
+  private resource: Record<string, string | number | boolean> = {};
+
+  constructor(resource?: Record<string, string | number | boolean>) {
+    this.resource = resource || {};
+  }
+
+  /**
+   * Get or create a tracer.
+   */
+  getTracer(name: string, version?: string): ITracer {
+    const key = version ? `${name}@${version}` : name;
+    let tracer = this.tracers.get(key);
+
+    if (!tracer) {
+      tracer = new Tracer(this, key);
+      this.tracers.set(key, tracer);
+    }
+
+    return tracer;
+  }
+
+  /**
+   * Add a span processor.
+   */
+  addSpanProcessor(processor: ISpanProcessor): void {
+    this.spanProcessors.push(processor);
+  }
+
+  /**
+   * Remove a span processor.
+   */
+  removeSpanProcessor(processor: ISpanProcessor): void {
+    const index = this.spanProcessors.indexOf(processor);
+    if (index > -1) {
+      this.spanProcessors.splice(index, 1);
+    }
+  }
+
+  /**
+   * Set the sampler.
+   */
+  setSampler(sampler: ISampler): void {
+    this.sampler = sampler;
+  }
+
+  /**
+   * Get the sampler.
+   */
+  getSampler(): ISampler | undefined {
+    return this.sampler;
+  }
+
+  /**
+   * Notify all processors that a span has ended.
+   */
+  notifySpanEnd(span: ISpan): void {
+    for (const processor of this.spanProcessors) {
+      try {
+        processor.onEnd(span);
+      } catch {
+        // Processors should not crash the tracing system
+        // Errors are silently swallowed for resilience
+      }
+    }
+  }
+
+  /**
+   * Force flush all processors.
+   */
+  async forceFlush(timeout?: number): Promise<void> {
+    const promises: Promise<void>[] = [];
+
+    for (const processor of this.spanProcessors) {
+      const promise = Promise.resolve(processor.forceFlush(timeout));
+      promises.push(promise);
+    }
+
+    await Promise.all(promises);
+  }
+
+  /**
+   * Shutdown all processors.
+   */
+  async shutdown(): Promise<void> {
+    const promises: Promise<void>[] = [];
+
+    for (const processor of this.spanProcessors) {
+      const promise = Promise.resolve(processor.shutdown());
+      promises.push(promise);
+    }
+
+    await Promise.all(promises);
+  }
+
+  /**
+   * Generate a random trace ID.
+   */
+  generateTraceId(): string {
+    return randomBytes(16).toString('hex');
+  }
+
+  /**
+   * Generate a random span ID.
+   */
+  generateSpanId(): string {
+    return randomBytes(8).toString('hex');
+  }
+
+  /**
+   * Get the resource attributes.
+   */
+  getResource(): Record<string, string | number | boolean> {
+    return this.resource;
+  }
+}

package/src/tracer/span-context.ts

@@ -0,0 +1,46 @@
+/**
+ * Span context implementation.
+ */
+
+import { ISpanContext } from '../types';
+
+/**
+ * Implementation of span context carrying trace and span identification.
+ */
+export class SpanContext implements ISpanContext {
+  public readonly traceId: string;
+  public readonly spanId: string;
+  public readonly traceFlags: number;
+  public readonly traceState?: string;
+
+  constructor(
+    traceId: string,
+    spanId: string,
+    traceFlags: number = 1,
+    traceState?: string
+  ) {
+    this.traceId = traceId;
+    this.spanId = spanId;
+    this.traceFlags = traceFlags;
+    this.traceState = traceState;
+  }
+
+  /**
+   * Check if this span context is valid.
+   */
+  isValid(): boolean {
+    return (
+      this.traceId.length > 0 &&
+      this.spanId.length > 0 &&
+      this.traceId !== '0'.repeat(32) &&
+      this.spanId !== '0'.repeat(16)
+    );
+  }
+
+  /**
+   * Check if this context is sampled.
+   */
+  isSampled(): boolean {
+    return this.traceFlags === 1;
+  }
+}

package/src/tracer/span.ts

@@ -0,0 +1,145 @@
+/**
+ * Span implementation with lifecycle management.
+ */
+
+import { ISpan, ITracer, SpanStatus, SpanEvent, ISpanContext } from '../types';
+import { SpanContext } from './span-context';
+import { getConfig } from '../config/runtime-config';
+
+/**
+ * Span implementation representing a unit of work.
+ */
+export class Span implements ISpan {
+  public context: ISpanContext;
+  public name: string;
+  public parentSpanId?: string;
+  public attributes: Record<string, unknown>;
+  public events: SpanEvent[] = [];
+  public status: SpanStatus = SpanStatus.UNSET;
+  public statusDescription?: string;
+  public startTimeNs: number;
+  public endTimeNs?: number;
+
+  private ended = false;
+
+  constructor(
+    name: string,
+    _tracer: ITracer,
+    context: ISpanContext,
+    parentSpanId?: string,
+    attributes?: Record<string, unknown>
+  ) {
+    this.name = name;
+    this.context = context;
+    this.parentSpanId = parentSpanId;
+    this.attributes = attributes ? { ...attributes } : {};
+    this.startTimeNs = performance.now() * 1_000_000;
+
+    // Apply runtime metadata to tracestate
+    this.enrichTraceState();
+  }
+
+  /**
+   * Get the duration in nanoseconds.
+   */
+  get durationNs(): number | undefined {
+    if (this.endTimeNs === undefined) {
+      return undefined;
+    }
+    return this.endTimeNs - this.startTimeNs;
+  }
+
+  /**
+   * Set an attribute on the span.
+   */
+  setAttribute(key: string, value: unknown): void {
+    if (this.ended) {
+      return;
+    }
+    this.attributes[key] = value;
+  }
+
+  /**
+   * Add an event to the span.
+   */
+  addEvent(name: string, attributes?: Record<string, unknown>): void {
+    if (this.ended) {
+      return;
+    }
+    this.events.push({
+      name,
+      timestamp: performance.now() * 1_000_000,
+      attributes: attributes ? { ...attributes } : {},
+    });
+  }
+
+  /**
+   * Record an exception on the span.
+   */
+  recordException(error: Error, attributes?: Record<string, unknown>): void {
+    if (this.ended) {
+      return;
+    }
+    this.status = SpanStatus.ERROR;
+    this.statusDescription = error.message;
+    this.addEvent('exception', {
+      ...attributes,
+      'exception.type': error.name,
+      'exception.message': error.message,
+      'exception.stacktrace': error.stack,
+    });
+  }
+
+  /**
+   * End the span.
+   */
+  end(): void {
+    if (this.ended) {
+      return;
+    }
+    this.ended = true;
+    this.endTimeNs = performance.now() * 1_000_000;
+  }
+
+  /**
+   * Check if the span is still recording.
+   */
+  isRecording(): boolean {
+    return !this.ended;
+  }
+
+  /**
+   * Enrich the trace state with runtime metadata.
+   */
+  private enrichTraceState(): void {
+    try {
+      const config = getConfig();
+      let traceState = this.context.traceState || '';
+
+      const metadata: Record<string, string> = {};
+      if (config.tenantId) {
+        metadata['tenant'] = config.tenantId;
+      }
+      if (config.projectId) {
+        metadata['project'] = config.projectId;
+      }
+      if (config.debug) {
+        metadata['dbg'] = '1';
+      }
+
+      if (Object.keys(metadata).length > 0) {
+        const pairs = Object.entries(metadata).map(([k, v]) => `${k}=${v}`);
+        traceState = pairs.join(',');
+
+        this.context = new SpanContext(
+          this.context.traceId,
+          this.context.spanId,
+          this.context.traceFlags,
+          traceState
+        );
+      }
+    } catch {
+      // Silently fail on trace state enrichment
+    }
+  }
+}

package/src/tracer/tracer.ts

@@ -0,0 +1,100 @@
+/**
+ * Tracer implementation for creating and managing spans.
+ */
+
+import { ITracer, ISpan, ISpanContext } from '../types';
+import { Span } from './span';
+import { SpanContext } from './span-context';
+import { getCurrentSpan, runWithSpanAsync } from '../context/context';
+import { TracerProvider } from './provider';
+import { getConfig } from '../config/runtime-config';
+
+/**
+ * Tracer for creating and managing spans.
+ */
+export class Tracer implements ITracer {
+  private provider: TracerProvider;
+
+  constructor(provider: TracerProvider, _instrumentationScope: string) {
+    this.provider = provider;
+  }
+
+  /**
+   * Start a new span.
+   */
+  startSpan(
+    name: string,
+    options?: {
+      attributes?: Record<string, unknown>;
+      parent?: ISpan | null;
+      parentContext?: ISpanContext | null;
+    }
+  ): ISpan {
+    const parentSpan = options?.parent ?? getCurrentSpan();
+    const effectiveContext = options?.parentContext || (parentSpan?.context as ISpanContext);
+
+    let traceId: string;
+    let parentSpanId: string | undefined;
+    let traceFlags: number;
+
+    if (parentSpan) {
+      traceId = parentSpan.context.traceId;
+      parentSpanId = parentSpan.context.spanId;
+      traceFlags = parentSpan.context.traceFlags;
+    } else if (effectiveContext && new SpanContext(effectiveContext.traceId, effectiveContext.spanId).isValid()) {
+      traceId = effectiveContext.traceId;
+      parentSpanId = effectiveContext.spanId;
+      traceFlags = effectiveContext.traceFlags;
+    } else {
+      traceId = this.provider.generateTraceId();
+      parentSpanId = undefined;
+
+      const sampler = this.provider.getSampler();
+      const sampled = sampler ? sampler.shouldSample().sampled : true;
+      traceFlags = sampled ? 1 : 0;
+
+      // Debug override: force sampling for new root traces
+      const config = getConfig();
+      if (config.debug) {
+        traceFlags = 1;
+      }
+    }
+
+    const spanContext = new SpanContext(
+      traceId,
+      this.provider.generateSpanId(),
+      traceFlags,
+      effectiveContext?.traceState
+    );
+
+    return new Span(name, this, spanContext, parentSpanId, options?.attributes);
+  }
+
+  /**
+   * Start an active span and run a function within it.
+   */
+  async startActiveSpan<T = unknown>(
+    name: string,
+    fn: (span: ISpan) => Promise<T> | T,
+    options?: {
+      attributes?: Record<string, unknown>;
+      parent?: ISpan | null;
+    }
+  ): Promise<T> {
+    const span = this.startSpan(name, options);
+
+    try {
+      const result = await runWithSpanAsync(span, async () => {
+        return await Promise.resolve(fn(span));
+      });
+      return result;
+    } catch (error) {
+      if (error instanceof Error) {
+        span.recordException(error);
+      }
+      throw error;
+    } finally {
+      span.end();
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,155 @@
+/**
+ * Core types and interfaces for the tracing SDK.
+ */
+
+/**
+ * Span status enumeration.
+ */
+export enum SpanStatus {
+  UNSET = 0,
+  OK = 1,
+  ERROR = 2,
+}
+
+/**
+ * Span context carries trace and span identification across process boundaries.
+ */
+export interface ISpanContext {
+  traceId: string;
+  spanId: string;
+  traceFlags: number;
+  traceState?: string;
+}
+
+/**
+ * Span event for capturing events during span execution.
+ */
+export interface SpanEvent {
+  name: string;
+  timestamp: number;
+  attributes?: Record<string, unknown>;
+}
+
+/**
+ * Span interface for creating and ending spans.
+ */
+export interface ISpan {
+  context: ISpanContext;
+  name: string;
+  parentSpanId?: string;
+  attributes: Record<string, unknown>;
+  events: SpanEvent[];
+  status: SpanStatus;
+  statusDescription?: string;
+  startTimeNs: number;
+  endTimeNs?: number;
+  durationNs: number | undefined;
+
+  setAttribute(key: string, value: unknown): void;
+  addEvent(name: string, attributes?: Record<string, unknown>): void;
+  end(): void;
+  recordException(error: Error, attributes?: Record<string, unknown>): void;
+  isRecording(): boolean;
+}
+
+/**
+ * Tracer for creating and managing spans.
+ */
+export interface ITracer {
+  startSpan(
+    name: string,
+    options?: {
+      attributes?: Record<string, unknown>;
+      parent?: ISpan | null;
+      parentContext?: ISpanContext | null;
+    }
+  ): ISpan;
+
+  startActiveSpan<T = unknown>(
+    name: string,
+    fn: (span: ISpan) => Promise<T> | T,
+    options?: {
+      attributes?: Record<string, unknown>;
+      parent?: ISpan | null;
+    }
+  ): Promise<T> | T;
+}
+
+/**
+ * Span processor for handling spans at various lifecycle points.
+ */
+export interface ISpanProcessor {
+  onStart?(span: ISpan): void;
+  onEnd(span: ISpan): void;
+  shutdown(): Promise<void> | void;
+  forceFlush(timeout?: number): Promise<void> | void;
+}
+
+/**
+ * Span exporter for sending spans to a backend.
+ */
+export interface ISpanExporter {
+  export(spans: ISpan[]): Promise<boolean> | boolean;
+  shutdown(): Promise<void> | void;
+}
+
+/**
+ * Resource attributes describing the service.
+ */
+export interface Resource {
+  [key: string]: string | number | boolean;
+}
+
+/**
+ * Tracer provider for managing tracers and processors.
+ */
+export interface ITracerProvider {
+  getTracer(name: string, version?: string): ITracer;
+  addSpanProcessor(processor: ISpanProcessor): void;
+  removeSpanProcessor(processor: ISpanProcessor): void;
+  forceFlush(timeout?: number): Promise<void>;
+  shutdown(): Promise<void>;
+}
+
+/**
+ * Configuration for the SDK initialization.
+ */
+export interface SDKConfig {
+  apiKey?: string;
+  endpoint?: string;
+  sampleRate?: number;
+  maxQueueSize?: number;
+  maxExportBatchSize?: number;
+  scheduleDelayMs?: number;
+  enableConsoleExporter?: boolean;
+  enableTokenCounting?: boolean;
+  enableCostTracking?: boolean;
+  enableSpanLogging?: boolean;
+  pricingOverride?: Record<string, Record<string, number>>;
+  sessionId?: string;
+  userId?: string;
+  tenantId?: string;
+  projectId?: string;
+  debug?: boolean;
+  attrTruncationLimit?: number;
+  loadEnv?: boolean;
+  autoInstrument?: boolean;
+  toolInclude?: string[];
+  maxToolSpans?: number;
+  maxSpanDepth?: number;
+  resource?: Resource;
+}
+
+/**
+ * Sampling result for span sampling decisions.
+ */
+export interface SamplingResult {
+  sampled: boolean;
+}
+
+/**
+ * Sampler interface for making sampling decisions.
+ */
+export interface ISampler {
+  shouldSample(): SamplingResult;
+}