Tracing & observability

The SDK ships with a structured tracing pipeline that records every agent invocation as JSON. Traces capture model/tool calls, timing, token usage, and (optionally) full payloads so you can drive dashboards, analytics, or remote monitoring.

Quick start

Enable tracing when creating your agent:

const agent = createSmartAgent({
	model,
	tools,
	tracing: {
		enabled: true,
		logData: true,
	},
});

Each invoke creates a new session directory under logs/<SESSION_ID>/ and writes trace.session.json once the run finishes.

Configuration

Option Description
enabled Required. Turn tracing on/off per agent.
logData When true, include prompt/response/tool payloads alongside metrics. Set to false to store only metadata.
sink Controls where finalized traces go. Defaults to fileSink() which writes trace.session.json under <cwd>/logs/<session>/. Swap in httpSink(url, headers?), cognipeerSink(apiKey, url?), or customSink({ onEvent, onSession }) for remote delivery or custom processing.

Example with an HTTP sink:

const agent = createSmartAgent({
	model,
	tools,
	tracing: {
		enabled: true,
		logData: false,
		sink: httpSink("https://observability.example.com/trace", {
			Authorization: `Bearer ${process.env.TRACE_TOKEN}`,
		}),
	},
});

Session payload

trace.session.json summarises the entire invocation:

  • Session metadatasessionId, start/end timestamps, duration, and resolved tracing config (logData flag plus a sanitized sink summary).
  • Agent runtime – name, version, model, and provider (when available).
  • Summary – aggregated token counts, byte totals, and per-event classifications.
  • Events – ordered list of model/tool/summarization events. Each record carries a stable eventId, a human-friendly label, status (success, error, retry, skipped), flattened metrics (durationMs, inputTokens, outputTokens, requestBytes, etc.), and optional tool identifiers.
  • Errors – flattened list of noteworthy errors (either per-event or session-level) for quick surfacing.

When logData is true, payload sections expose sanitized snapshots under a data.sections array. Each section is one of a handful of kinds (message, tool_call, tool_result, summary, metadata) with concise, user-facing labels. Circular references, functions, and bigints are handled automatically. Prefer customSink({ onEvent }) if you want a realtime feed of recorded events.

Example structure

{
	"sessionId": "sess_pK4y6xQd2Z9LcvGk",
	"startedAt": "2025-09-29T08:15:30.123Z",
	"endedAt": "2025-09-29T08:15:35.412Z",
	"durationMs": 5289,
	"agent": { "name": "SupportAgent", "version": "2025.09", "model": "gpt-4.1-mini", "provider": "openai" },
	"config": { "enabled": true, "logData": true, "sink": { "type": "file", "path": ".../logs" } },
	"summary": { "totalDurationMs": 3120, "totalInputTokens": 812, "totalOutputTokens": 431, "totalCachedInputTokens": 48, "totalBytesIn": 18240, "totalBytesOut": 9211, "eventCounts": { "ai_call": 2, "tool_call": 1 } },
	"events": [
		{
			"id": "evt_0001_abcd",
			"sessionId": "sess_pK4y6xQd2Z9LcvGk",
			"type": "ai_call",
			"label": "Assistant Response #1",
			"sequence": 1,
			"timestamp": "2025-09-29T08:15:30.987Z",
			"actor": { "scope": "agent", "name": "SupportAgent", "role": "assistant", "version": "2025.09" },
			"status": "success",
			"durationMs": 1780,
			"inputTokens": 320,
			"outputTokens": 198,
			"totalTokens": 518,
			"cachedInputTokens": 12,
			"requestBytes": 14280,
			"responseBytes": 9211,
			"model": "gpt-4.1-mini",
			"provider": "openai",
			"data": {
				"sections": [
					{
						"id": "message-evt_0001_abcd-01",
						"kind": "message",
						"label": "User Prompt",
						"role": "user",
						"content": "How do I reset my password?"
					},
					{
						"id": "message-evt_0001_abcd-02",
						"kind": "message",
						"label": "Assistant Response",
						"role": "assistant",
						"content": "Here are the steps to reset your password..."
					}
				]
			}
		}
	],
	"status": "success",
	"errors": []
}

Operational tips

  • Retention – traces are plain JSON. Rotate or purge logs/ on a schedule if you generate many sessions.
  • Privacy – disable logData when prompts contain sensitive information, or redact inside your own tooling before forwarding via your sink.
  • Streamingmode is currently "batched" for all sessions. Streaming hooks are reserved for future versions.
  • Correlation – events include both sessionId and eventId, making it simple to join with other telemetry sources.

File layout

logs/
	sess_pK4y6xQd2Z9LcvGk/
		trace.session.json

Traces are safe to delete after ingestion. If you prefer remote storage, configure an httpSink/cognipeerSink and periodically clear the local directory.


Copyright © 2025 Cognipeer