Debugging

Always-On Model Telemetry

Every session's execution log includes lightweight model telemetry by default - no configuration needed:

• Model request markers - a model-request entry for every provider call (LLM and media generation) recording when the request happened, plus the provider and model. Without tracing enabled, the entry carries no request payload, so it stays cheap even for high-volume production sessions.
• Step stats - a step-stats entry after each LLM step with the token usage breakdown: input tokens, cache reads and writes, output tokens, and reasoning tokens, plus the prompt-cache mode the provider applied, the thinking the step ran with, the images its request carried, and, on an OpenRouter model, what the response reported (below). This is the primary signal for understanding where a session's tokens and cost go, and which deployment ran each step.

Both appear in the execution log timeline - via getLogs() and in the dashboard's execution log views. To capture the full request payloads as well, enable model request tracing.

Thinking and image fields

Every LLM step's stepStats records how the declared thinking level ran on the model, and what images the request carried:

A level that does not run exactly as declared is also recorded once per run and model as a thinking-adjusted block operation, so a substitution or an off the model cannot honor is visible without reading every step.

OpenRouter step fields

On an OpenRouter model, stepStats also carries what OpenRouter reported about the step:

const result = await client.agentSessions.getLogs(sessionId);

if (result.status !== 'expired') {
  for (const entry of result.entries) {
    if (entry.type !== 'step-stats' || !entry.stepStats) continue;
    const { model, servedModel, reportedCost, router, thinking } = entry.stepStats;
    console.log(model, '->', servedModel, reportedCost?.total, router?.reason, thinking?.applied);
  }
}

Model Request Tracing

Model request tracing upgrades model-request entries to carry the full payload sent to model providers during agent execution. This helps you understand exactly what was sent - system prompts, messages, tool definitions, and provider options - making it easier to debug agent behavior.

Enabling Tracing

Enable tracing by setting traceModelRequests: true in the client config:

import { OctavusClient } from '@octavus/server-sdk';

const client = new OctavusClient({
  baseUrl: process.env.OCTAVUS_API_URL!,
  apiKey: process.env.OCTAVUS_API_KEY!,
  traceModelRequests: true,
});

When enabled, the SDK sends an X-Octavus-Trace: true header with every request. The platform captures the full model request payload before each provider call and stores it in the execution logs.

You can also drive this from an environment variable for per-environment control:

const client = new OctavusClient({
  baseUrl: process.env.OCTAVUS_API_URL!,
  apiKey: process.env.OCTAVUS_API_KEY!,
  traceModelRequests: process.env.TRACE_MODEL_REQUESTS === 'true',
});

What Gets Captured

LLM requests include:

• Full system prompt
• All messages in AI SDK format (post-conversion)
• Tool names, descriptions, and JSON schemas
• Provider-specific options (thinking budgets, etc.)
• Temperature, max steps, and thinking configuration

Media generation requests (image, video, speech, transcription) include:

• The generation prompt (image and video)
• Request parameters - aspect ratio, resolution, duration, voice, format, or language
• Whether reference images were provided

Where Traces Appear

Traces appear as Model Request entries in the execution log timeline, alongside existing entries like triggers, tool calls, and responses. Each trace is linked to the block that made the model call.

In the Octavus dashboard:

• Session debug view - Full execution log with expandable model request entries
• Agent preview - Activity panel shows model requests in the execution steps

Each entry shows the raw JSON payload with a copy button for easy inspection.

Storage

Traces are stored alongside other execution log entries with a 24-hour TTL. They are not permanently stored. A typical LLM trace with 10 messages and 5 tools is 10-50KB; without tracing, model-request markers are a few hundred bytes. Media traces are small even when traced (just the prompt and request parameters).

Recommendations

Preview Sessions

Model request tracing is always enabled for preview sessions in the Octavus dashboard. No configuration needed - the platform automatically traces all model requests when using the agent preview.