> For the complete documentation index, see [llms.txt](https://docs.revenium.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.revenium.io/optimize-performance/debug-logs-and-traces.md). # Debug Logs & Traces A cost spike on a dashboard, a slow response a customer complained about, an agent workflow that didn't finish - in each case the question is the same: what actually happened, and where did it go wrong? Without structured transaction data, answering that means stitching together provider logs, application traces, and cost reports that were never designed to talk to each other. By the time you've reconstructed the picture, the same problem has already run hundreds of times more. Revenium captures every AI transaction with full financial and attribution context attached. The logs and trace views are where you stop guessing and start knowing - which call was expensive, which workflow it belonged to, which customer triggered it, and where in a multi-step run things went off track. ### :list-ul: Transaction Logs as a Single Source of Truth The log in **Data > Logs** records every AI call that has flowed through Revenium, with cost, model, duration, and attribution all visible in the same row. There's no separate system for "what it cost" and "who ran it" - they're the same record, queryable in real time with auto-refresh on. Filters at the top let you narrow by time window, metric type, or any column you've added through Manage Columns. The **Include AI coding assistant logs** toggle separates AI development tool traffic - things like Claude Code - from your application's own AI workloads, which matters more than it sounds. Coding assistants generate a high volume of transactions and can dominate the log if you're trying to isolate something else. Beyond standard LLM completions, the same view also covers: * **Product Transactions** : usage events that generate line items for billing (either to your customers, or for cross-charging AI usage to other business units) * **System** : platform-level activity * **Tool Registry** : cost-generating external tools called by agents (i.e. usage-based APIs like Firecrawl or third-party services like Stripe Identity) * **Exports** : downloadable data for finance or analytics workflows Every row links straight into the transaction detail, so moving from "this looks abnormal" to "here's exactly why" never requires leaving the page. ### :rectangle: Everything Revenium Knows About a Single Transaction Open the detail panel on any row and Revenium shows you the full record of what happened on that one call. This is the layer beneath your dashboard - useful when an aggregated metric raises a question that only the underlying data can answer. The detail covers: * **Token usage** broken down across input, output, reasoning, cached, and cache creation - so you can see whether the cost was driven by prompt size, response length, or whether cached context is being reused efficiently * **Cost** split between input and output rather than shown as a blended figure, which makes it obvious what was actually expensive * **Timing** across every phase of the call - request time, time to first token, full duration, tokens per second - which lets you tell apart a slow model from a slow network from a slow upstream prompt chain * **Attribution** to the organization, subscriber, product, agent, and squad responsible - so cost ownership is immediate rather than reconstructed after the fact If a call is missing attribution data, that itself is useful information. It tells you the workflow that triggered it isn't fully instrumented, and the fix is to update the metering payload to include the missing identifiers. From the detail panel, **Open full trace view** drops you into the workflow this transaction belonged to. ### :arrow-right: Seeing How a Workflow Actually Ran Individual transactions are the atomic unit, but problems usually live at the workflow level. An agent run that lasted hours and cost tens of dollars isn't explained by any single call - it's explained by the sequence of calls, the agents involved, and which steps consumed the most time and money. The Trace view assembles that sequence. The summary header gives you the headline figures for the run - total cost, total duration, transaction count, success/error ratio, and the models, providers, and task types involved. Below that, two visualisations show the workflow from different angles: * **The Transaction Timeline** is a Gantt chart of every transaction in the trace, sequenced chronologically and color-coded by agent. Each bar shows the duration and cost of that step. In multi-agent runs the timeline makes handoffs and bottlenecks immediately visible - which agent ran when, which step took longest, which one cost the most - without having to do any arithmetic. * **The Dependency Tree** shows the structural pattern of the run - sequential, parallel, multi-root - and the cost and duration of each branch. This is the right view when you need to know whether the cost is concentrated in one agent or genuinely distributed across the workflow, because the answer changes what you fix. Aggregated breakdowns sit beneath both, summarizing cost by model, cost by provider, the input/output token ratio, and time spent by task type - all scoped to this single trace, not your account-wide averages. ### :layer-group: Grouping Traces by Job A single business process is usually made up of more than one trace. An agentic job that qualifies a lead, or a workflow that resolves a support ticket, can span several related trace types — each captured as its own trace even though they all serve the same outcome. Looked at one trace at a time, the steps that belong together stay scattered, and a cost or latency anomaly in one step is hard to read against the process it's part of. Grouping traces by job collapses those related trace types into a single group, so you can see and compare the steps of one business process together instead of as isolated traces. #### How job grouping works Revenium ties a trace to a job through the job identifier attached when the underlying transactions are metered. Traces that share the same job identifier belong to the same business process; traces without one remain ungrouped. This is the same job model used on the ROI surface — see [Analyze Decision Costs](/instrument-your-agents/analyze-decision-costs.md) for how jobs are defined and how the identifier is supplied when metering. Set the grouping control to **Job** and the cost and anomaly breakdown combines the related trace types under the business process they belong to, so a whole job reads together; set it to **Trace type** to keep each execution type on its own. #### Using the grouping control On the Traces cost view, a grouping control switches how costs and anomalies are broken down: * **Trace type** isolates anomalies within a single execution type — the right view when you're looking at one kind of step. * **Job** combines the multiple trace types involved in the same business process or outcome, so the cost and anomalies for a whole job read together instead of scattered across its steps. Job is the view to reach for when the question spans a whole process rather than a single call — comparing the trace types that make up one outcome, and spotting which step carries the cost or the delay against the related steps around it. ### :bug: Where to Start When Something Goes Wrong Investigations almost always run broad-to-narrow. Start in the transaction log, filter by whatever you know about the problem - the subscriber who complained, the time window of the spike, the trace type that's been flagged - and look for the rows that stand out on cost or duration. Open the transaction detail to confirm what you're looking at, then follow the trace link to see the workflow context around it. The pattern that tends to emerge is that expensive or slow traces aren't random. The same trace type, the same agent, or the same task type appears repeatedly at the top of the cost distribution. When that's the case, the fix is almost always in the prompt or workflow logic for that specific path - not in the infrastructure, and not in the model choice. The role of the logs and traces is to get you to that conclusion in minutes rather than hours. ### :comments: Reading the Prompt Behind a Transaction When a transaction's cost, latency, or output looks wrong, the numbers only tell you *that* something happened - the prompt tells you *why*. Open any transaction's detail panel and, where prompt data is available, the **Prompt Data** section opens a full-screen viewer of the exact conversation that produced the call. The viewer breaks the call into three parts: * **System Prompt** - the instructions that defined the model's behavior for this call. * **Input Messages** - the conversation sent to the model, split message-by-message and tagged by role (system, user, assistant, tool) so a long multi-turn exchange is easy to scan. * **Output Response** - the model's generated reply. Each section carries its own character count and its share of the request's token total, so you can see at a glance whether a bloated system prompt, a long input history, or the response itself drove the token count - and copy any section to the clipboard for closer inspection. Very large prompts are truncated at 50,000 characters per field, and the viewer flags when that has happened so you don't mistake a cut-off prompt for the whole story. Because prompt content is sensitive, access is governed by two independent controls: * **Team prompt capture** must be enabled in the team's **AI Settings** for prompts to be recorded at all - with it off, there is simply no captured content to show. * **The "Can View Prompt Data" permission** controls *who* may read that content. Users without it see a locked placeholder rather than the prompt; Tenant Administrators have access implicitly. Both controls, and why prompt access is deliberately separated from ordinary cost data, are covered in [Manage Users & Teams](/account-and-resources/manage-users-and-teams.md). > **Through MCP, conversationally.** The cost-investigation work this page describes is also accessible to an AI assistant connected to Revenium via the MCP Server. Instead of clicking through filters, you describe the problem in natural language. Ask "why did my costs spike yesterday?", "which customer drove the increase this week?", or "is one model accounting for most of the unusual spend?" and the agent breaks the data down across providers, models, customers, agents, or API keys, and explains what it finds. Useful when the question is exploratory rather than known. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.revenium.io/optimize-performance/debug-logs-and-traces.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.