SDK Overview

The @ladger/sdk package provides a lightweight TypeScript SDK for tracking AI workload costs and traces.

Core Concepts

Tracer

The LadgerTracer is the main entry point. It manages span creation, batching, and sending data to the Ladger API.

import { LadgerTracer } from '@ladger/sdk';

const tracer = new LadgerTracer({
  apiKey: 'ladger_sk_live_...',
  flowName: 'my-chatbot',
});

Spans

A span represents a unit of work in your AI pipeline. Spans can be nested to create trace hierarchies.

const span = tracer.startSpan('generate-response');
// ... do work ...
span.end();

Cost Events

Cost events capture AI API usage data: provider, model, tokens, and optional cost in USD.

span.recordCost({
  provider: 'openai',
  model: 'gpt-4o',
  inputTokens: 100,
  outputTokens: 50,
});

Sessions

Sessions group related spans together (e.g., a conversation with multiple turns).

tracer.newSession(); // Starts a new session

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Your Application                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐         │
│   │  AI Call 1  │    │  AI Call 2  │    │  AI Call 3  │         │
│   └──────┬──────┘    └──────┬──────┘    └──────┬──────┘         │
│          │                  │                  │                 │
│          └────────────┬─────┴─────┬────────────┘                 │
│                       │           │                              │
│                       ▼           ▼                              │
│                 ┌─────────────────────┐                          │
│                 │    LadgerTracer      │                          │
│                 │  ┌───────────────┐  │                          │
│                 │  │ Pending Spans │  │                          │
│                 │  └───────────────┘  │                          │
│                 └──────────┬──────────┘                          │
│                            │                                      │
└────────────────────────────┼──────────────────────────────────────┘
                             │ Batch flush (10 spans or 5s interval)
                             ▼
                    ┌────────────────┐
                    │   Ladger API    │
                    │   /v1/ingest   │
                    └────────────────┘

Configuration Options

Option	Type	Default	Description
apiKey	string	required	Your Ladger API key
flowName	string	required	Groups traces by workflow
projectUrl	string	https://ladger.pages.dev/api	API endpoint
batchSize	number	10	Spans to batch before sending
flushInterval	number	5000	Auto-flush interval (ms)
debug	boolean	false	Enable console logging

Data Flow

1. Create Span → Span is stored in memory
2. End Span → Span added to pending queue
3. Batch Full OR Timer → Spans sent to API
4. API Response → Success: clear sent spans, Failure: retry

Tip

The SDK automatically retries failed requests by re-adding spans to the queue.

Performance

The SDK is designed for minimal overhead:

• Async-first: All network calls are non-blocking
• Batching: Reduces HTTP requests by grouping spans
• Lightweight: ~3KB gzipped, no heavy dependencies
• Type-safe: Full TypeScript support

Exports

// Main class
export { LadgerTracer } from '@ladger/sdk';

// Types
export type {
  LadgerConfig,
  LadgerSpan,
  SpanOptions,
  SpanAttributes,
  CostEvent,
  SerializedSpan,
} from '@ladger/sdk';

Next Steps

• LadgerTracer Reference - Detailed tracer API
• Working with Spans - Create and manage spans
• Cost Tracking - Record usage and costs