Data model

Traces, spans, workflows, runs, agents, sessions, and customers.

Foglamp’s model maps directly onto how the Vercel AI SDK runs. A handful of 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 customer served (see Customer)
metadata	map?	string to string
spans	span[]	1-2000 spans

Two rules are checked in the SDK and again 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, or anything else. Spans carry timing, status, model identity, token usage, and optional input/output text.

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 counts, see below
ttftMs	number?	time to first token (may be fractional)
input / output	string?	up to 1,000,000 chars each
metadata	map?	string to string

Usage

Every usage field is an optional non-negative integer. Each is priced on its own 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 and run

A workflow is a named, repeatable process (for example 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 shows them as 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, like fog.integration({ traceName: "classify-email" }), so the call is easy to find and group in the dashboard.

The label a trace displays is traceName ?? agentName. If you set only agentName, that’s the label. If you set both, the call belongs to the agent and shows the traceName. Every trace must set at least one of the two.

Agent

An agent is a named actor (agentName) responsible for a call. Agents give you per-agent totals for cost, latency, and errors across every trace they produced, no matter which workflow they ran in.

Session

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

Customer

A customer (customer) is the person or company your app is serving with a call, such as a tenant or end user. It rolls cost up per customer (the Customers card on the Overview), which is 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 meant to be dynamic: one id per customer
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 can change over time (Foglamp keeps the latest). customer is optional; leaving it out 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 call, reads the AI SDK’s own performance metrics for time to first token, and closes the trace when the call ends.

Embeddings aren’t captured yet. Both SDK paths trace generateText, streamText, generateObject, and streamObject, plus the agent classes. embed, embedMany, and rerank are not traced yet: an embed call today produces a trace with a root span but no token usage or cost. The embedding span type is reserved for when this lands.