Event Model

AccordKit writes events as newline-delimited JSON (.jsonl). Each line is a discriminated union that shares a common envelope and diverges by type.

Base envelope

Every event exported by @accordkit/tracer extends the BaseEvent shape:

Field	Type	Description
ts	string	ISO-8601 timestamp generated when the event is emitted.
sessionId	string	Logical session or conversation identifier. Generated automatically unless you pass sessionId to the tracer.
level	'debug' | 'info' | 'warn' | 'error'	Default severity for the event.
ctx	{ traceId: string; spanId: string; parentSpanId?: string }	Trace context used to correlate related events.
provider?	'openai' | 'anthropic' | …	Optional provider label supplied by adapters.
model?	string	Model identifier if known (e.g., gpt-4o).
requestId?	string	Upstream request identifier (when returned by the provider).
service?/env?/region?	string	Tags inherited from the tracer options.
type	string	Discriminant that determines the rest of the payload.
$ext?	Record<string, unknown>	Bucket for provider specific metadata.

In JSONL form it resembles:

Partial event

{
  "ts": "2024-06-20T12:45:11.981Z",
  "sessionId": "sess_c0l2t9_1718880311981",
  "level": "info",
  "ctx": { "traceId": "tr_31w6n2_1718880311981", "spanId": "sp_5jwvt5_1718880311981" },
  "type": "message",
  "provider": "openai"
}

Event kinds

message

Field	Type	Description
role	'system' | 'user' | 'assistant' | 'tool'	Role the content belongs to.
content	string	Text payload (adapters may stringify structured objects).
format?	'text' | 'json' | 'tool_result'	Optional hint for rendering.

Adapters emit message events for prompts and completions when emitPrompts / emitResponses are enabled.

tool_call

Field	Type	Description
tool	string	Name or identifier of the requested tool.
input	unknown	Arguments supplied by the model or application.

tool_result

Field	Type	Description
tool	string	Tool or function that produced the result.
output	unknown	Return value (redact if it contains sensitive data).
ok?	boolean	Indicates success (true) or failure (false).
latencyMs?	number	Optional latency measurement for the tool call.

usage

Field	Type	Description
inputTokens?	number	Prompt tokens counted by the provider.
outputTokens?	number	Completion tokens counted by the provider.
cost?	number	Monetary cost if calculated.

span

Field	Type	Description
operation	string	Name of the work being measured (e.g., db.query).
durationMs	number	Duration computed by spanEnd.
status?	'ok' | 'error'	Result of the operation.
attrs?	Record<string, unknown>	Key/value attributes collected at start or end.

SpanEvent is emitted when you call tracer.spanEnd(spanToken, { ... }).

Creating related events

Reuse the ctx object to link events to the same span:

const span = tracer.spanStart({ operation: 'search' });

await tracer.message({
  ctx: span.ctx,
  role: 'assistant',
  content: 'Searching for documentation…',
});

await tracer.spanEnd(span, { attrs: { hits: 12 } });

All events that share the same traceId are grouped together meaningfully in downstream tooling such as the AccordKit Viewer.