Flow Mapping

Flow Mapping automatically builds an interactive topology of your AI system, showing how components connect, where costs accumulate, and where to optimize.

What is Flow Mapping?

When you instrument your AI workloads with the Ladger SDK, the platform automatically:

Traces relationships between spans (parent-child)
Groups spans by flow name
Builds a visual map of your AI pipeline
Highlights cost hotspots with color intensity

Dashboard Visualization

The Flow Map in the Ladger dashboard provides:

┌────────────────────────────────────────────────────────────────┐
│                         FLOW MAP                                │
├────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌─────────────┐                                              │
│   │   Intake    │                                              │
│   │  $0.02/req  │                                              │
│   └──────┬──────┘                                              │
│          │                                                      │
│          ▼                                                      │
│   ┌─────────────┐      ┌─────────────┐                         │
│   │  Classify   │─────►│   Router    │                         │
│   │  $0.01/req  │      │  $0.00/req  │                         │
│   └─────────────┘      └──────┬──────┘                         │
│                               │                                 │
│                    ┌──────────┼──────────┐                     │
│                    ▼          ▼          ▼                     │
│             ┌──────────┐ ┌──────────┐ ┌──────────┐            │
│             │  Answer  │ │ Summarize│ │  Search  │            │
│             │ $0.15/req│ │ $0.05/req│ │ $0.08/req│            │
│             └──────────┘ └──────────┘ └──────────┘            │
│                                                                 │
│   Legend: █ High Cost  ▓ Medium Cost  ░ Low Cost              │
│                                                                 │
└────────────────────────────────────────────────────────────────┘

Creating Flows

Flows are defined by the flowName in your tracer configuration:

const tracer = new LadgerTracer({
  apiKey: process.env.LADGER_API_KEY!,
  flowName: 'customer-support-agent', // This creates/uses the flow
});

All spans created by this tracer are automatically grouped under the flow.

Flow Naming Best Practices

Pattern	Example	Use Case
`feature-agent`	`support-agent`	Single-purpose agent
`service-action`	`api-chat`	Service endpoints
`pipeline-name`	`rag-pipeline`	Multi-step pipelines
`environment-feature`	`prod-classifier`	Environment-specific

// Good flow names
'customer-support-agent'
'document-qa-pipeline'
'content-generator'
'intent-classifier'

// Avoid generic names
'main'
'default'
'test'

Trace Hierarchies

Create meaningful trace hierarchies using nested spans:

async function handleSupport(query: string) {
  // Root span for the entire operation
  return tracer.trace('handle-support-request', async (rootSpan) => {

    // Child: Intent classification
    const intent = await tracer.trace('classify-intent', async (span) => {
      span.setAttributes({ 'query.length': query.length });
      const result = await classifyIntent(query);
      span.recordCost({ provider: 'openai', model: 'gpt-4o-mini', ... });
      return result;
    }, { parent: rootSpan });

    // Child: Route and respond
    const response = await tracer.trace('generate-response', async (span) => {
      span.setAttributes({ intent });
      const result = await generateResponse(query, intent);
      span.recordCost({ provider: 'openai', model: 'gpt-4o', ... });
      return result;
    }, { parent: rootSpan });

    return response;
  });
}

This creates a trace tree:

handle-support-request
├── classify-intent
└── generate-response

Flow Metrics

Each flow tracks:

Metric	Description
Total Cost	Sum of all costs in the flow
Request Count	Number of sessions/requests
Avg Cost/Request	Total cost ÷ request count
Avg Latency	Mean end-to-end time
P95 Latency	95th percentile latency
Error Rate	Percentage of failed spans

Identifying Hotspots

The flow map uses color intensity to highlight expensive components:

Red/Orange: High cost (more than 50% of flow cost)
Yellow: Medium cost (20-50%)
Green: Low cost (less than 20%)

Multi-Model Flows

For flows using multiple models, the map shows model usage:

// First call: fast classification
await tracer.trace('classify', async (span) => {
  span.recordCost({ model: 'gpt-4o-mini', ... });
}, { parent: rootSpan });

// Second call: detailed response
await tracer.trace('respond', async (span) => {
  span.recordCost({ model: 'gpt-4o', ... });
}, { parent: rootSpan });

Dashboard shows:

classify → GPT-4o-mini (low cost)
respond → GPT-4o (high cost)

Comparing Flows

Compare flow performance over time:

Flow	Last 7 Days	Previous 7 Days	Change
support-agent	$234.50	$289.20	-19% ✓
content-gen	$156.80	$142.30	+10% ↑
qa-pipeline	$89.20	$91.50	-3% ✓