Data model

Foglamp’s model maps directly onto how the Vercel AI SDK executes. Five concepts cover everything you see in the dashboard.

Trace

A trace is one top-level model call — a single generateText, streamText, generateObject, or streamObject invocation. It carries the call’s identity (name, agent, workflow, run, session), free-form metadata, and a list of spans.

Field	Type	Notes
`traceId`	string	1–128 chars, unique per call
`traceName`	string?	up to 256 chars — required if `agentName` is absent
`agentName`	string?	up to 256 chars
`workflowName`	string?	up to 256 chars
`workflowRunId`	string?	up to 128 chars — groups traces into one run
`sessionId`	string?	up to 128 chars
`customer`	object?	`{ id, name?, imageUrl? }` — the end-customer served (see Customer)
`metadata`	map?	string → string
`spans`	span[]	1–2000 spans

Two rules are enforced at compile time (SDK) and at ingest:

Every trace must set traceName or agentName (both is fine — see Trace name).
workflowName and workflowRunId go together — pass both or neither.

Span

A span is a unit of work inside a trace — a model step, a tool call, an embedding, or anything else. Spans carry timing, status, model identity, token usage, and optional input/output.

Field	Type	Notes
`spanId`	string	1–128 chars
`parentSpanId`	string?	builds the waterfall
`spanType`	enum	`agent`, `llm`, `tool`, `embedding`, `other`
`name`	string	up to 512 chars
`startTime` / `endTime`	int	epoch milliseconds; `endTime ≥ startTime`
`status`	enum	`ok` (default) or `error`
`errorMessage`	string?	up to 8192 chars
`provider`	string?	e.g. `openai`
`modelId`	string?	e.g. `gpt-4o`
`usage`	object?	token dimensions, see below
`ttftMs`	number?	time to first token (may be fractional)
`input` / `output`	string?	up to 1,000,000 chars each
`metadata`	map?	string → string

Usage

Every usage dimension is an optional non-negative integer. Each is priced independently at ingest.

Field	Meaning
`inputTokens`	prompt tokens
`outputTokens`	completion tokens
`totalTokens`	total reported by the provider
`reasoningTokens`	reasoning/thinking tokens
`cachedInputTokens`	prompt tokens served from cache
`cacheWriteInputTokens`	tokens written to cache
`imageCount`	images generated
`webSearchCount`	web search calls
`requestCount`	provider requests

Workflow & run

A workflow is a named, repeatable process (e.g. deploy-digest). A workflow run is one execution of it, identified by workflowRunId. Every trace sharing a workflowRunId belongs to the same run, and the dashboard stitches them into a single timeline.

Trace name

A trace name (traceName) is the call’s human label. Use it for a one-off call that isn’t an agent — fog.integration({ traceName: "classify-email" }) — so it’s identifiable and groupable in the dashboard instead of landing in an unnamed bucket. The effective label a trace displays as is traceName ?? agentName: if you set only agentName, that’s the label; if you set both, the call is attributed to the agent and shows the traceName. Every trace must set one of the two.

Agent

An agent is a named actor (agentName) responsible for a call. Agents give you per-agent rollups — cost, latency, error rate — across every trace they produced, independent of which workflow they ran in.

Session

A session (sessionId) ties together traces that belong to one conversation or user interaction, cutting across workflows and agents. Use it to follow a single end-user thread end to end.

Customer

A customer (customer) is the end-customer a call serves — the tenant or user your app is acting on behalf of. It rolls cost up per customer (the Customers card on the Overview), so it’s the building block for usage-based pricing on top of Foglamp.

Field	Type	Notes
`id`	string	required — 1–128 chars, the stable grouping key. Unlike names, this is a high-cardinality identifier (one per customer), so a dynamic id is correct here
`name`	string?	up to 256 chars — display label; the latest value seen wins
`imageUrl`	string?	up to 2048 chars — avatar URL; falls back to a generated icon

name and imageUrl are display-only and may change over time (Foglamp keeps the latest). Only id is denormalized onto spans for attribution; the name and image live in a small dimension table. customer is optional and purely additive — omitting it changes nothing.

How it streams

generateText() ─────────────▶ trace
  ├─ step (model call) ──────▶ llm span   (tokens, cost, ttft)
  ├─ tool call ──────────────▶ tool span
  └─ step (model call) ──────▶ llm span

The SDK opens a span per step and tool execution, reads the SDK’s own performance metrics for TTFT, and closes the trace when the call ends.

Embeddings aren’t captured yet. The wire contract reserves an embedding span type, but neither SDK path emits one today. Both paths instrument generateText, streamText, generateObject, and streamObject (plus the ToolLoopAgent/Experimental_Agent classes); embed/embedMany and rerank are not yet traced. Instrumenting an embed call today produces a trace with a root span but no token usage or cost. Embedding capture is planned — until then, treat the embedding span type as reserved.

Get started

Core concepts

SDK

Trace

Span

Usage

Workflow & run

Trace name

Agent

Session

Customer

How it streams

​Trace

​Span

​Usage

​Workflow & run

​Trace name

​Agent

​Session

​Customer

​How it streams

Trace

Span

Usage

Workflow & run

Trace name

Agent

Session

Customer

How it streams