Monitor agents
Use agent measurements to understand activity, latency, token consumption, and failures. Start with a question, choose the observations that answer it, and inspect individual runs when an aggregate needs explanation. Operational measurements do not, by themselves, establish answer quality or business success.
Choose the question before the metric
| Your question | Starting measurement | What it does not establish |
|---|---|---|
| How much agent activity was recorded? | agent.trace.count, or a custom count with an explicit scope | Unique people, resolved requests, or successful business outcomes |
| Are recorded agent invocations taking longer? | agent.trace.duration_ms | Time to the first streamed token or answer correctness |
| How many tool calls report errors? | agent.tool.error_count alongside agent.tool.call_count | Whether a later retry or another tool completed the user's task |
| How many tokens were recorded? | Built-in input/output token metrics | A monetary bill or price calculation |
| Which operations match my conditions? | A custom metric over the supported span fields | Arbitrary business-database fields or session metadata |
| Why did this particular run behave that way? | Session events and trace spans | An aggregate across all runs |
Use the built-in reference for metric definitions and custom metric reference for supported fields. Use quality evaluation for a separate assessment of answer quality.
Understand what is being counted
| Term | Meaning for this section |
|---|---|
| Session | A conversation that can contain multiple interactions. A session count is not an invocation count. |
| Span | One recorded operation, such as invoke_agent, chat, or execute_tool, with its own duration and attributes. |
| Agent invocation | Work represented by an invoke_agent span. One invocation can contain model calls and tool calls. |
| Trace | Related spans describing a run. Use its trace ID to retrieve spans. Do not assume one trace ID per session or one span per trace. |
| Time bin | A time interval into which observations are aggregated. It is separate from a distribution's value ranges. |
The built-in agent.trace.* names are stable API identifiers. Their source observations are recorded invoke_agent spans, not a count of distinct trace IDs. Their duration metrics measure those spans. Tool metrics use execute_tool spans. The built-in aggregation does not apply the custom wizard's Top-level sessions only filter. See Built-in observation scope before comparing built-in and custom values.
Before interpreting a number, record four choices: observation (what is counted), population (which agents and session depths), window, and aggregation. Use the same choices when comparing values, except for the deliberate condition that distinguishes a numerator from its denominator.
A custom metric stores a measurement definition: its filter, aggregation, agent scope, and dimensions, together with operational settings such as retention. The reporting window, dimension filters, and output binning are chosen when you read the series. Retention limits available history but does not fix the query window. See what you are creating.
For custom metrics, a span contributes to the bin containing its end. Spans arriving more than ten minutes after that bin ends, or lasting more than one hour, are not guaranteed to be counted. Backfill only uses traces still available. Review coverage and retention before treating a report as complete.
Choose your workflow
For application integration, use Query metrics from your application. For definitions rather than procedures, use the built-in and custom references.
Match the docs to the Console
| Task | Developer Console surface | Documentation |
|---|---|---|
| View custom-metric charts | Build > Dashboards | Dashboards |
| Create or manage custom metrics | Dev tools > Custom metrics | Create custom metrics |
| View built-in metrics and traces | Build > Observability | Built-in metrics, Inspect agent runs |
| Open an agent conversation | Dev tools > Agents, then Sessions | Inspect agent runs |
Monitor agents and Evaluate quality are documentation categories, not replacements for Console labels. The existing Evaluate quality section also retains corpus query observability. Use that page for corpus query history, not agent metric authoring.
These navigation paths describe the developer Console. For Business Suite navigation and developer handoff, see View metrics in Business Suite.
View built-in metric charts
Open Build > Observability in the developer Console, or Observability in Business Suite, to review built-in agent metrics. See Built-in agent metrics for what each metric measures.
The Observability time-range control differs from Dashboards. Choose Last hour, Last 24 hours, Last 7 days, or Last 30 days; the default is Last 24 hours when no range is selected. Use the custom-range control to set your own dates. Use the Agent selector, when shown, to view one agent or all agents. Select the range on the page you are reading rather than assuming it carried over from Dashboards.
For custom-metric chart controls and filtering, see View dashboards.