Monitor agents
Query metrics from your application
Discover a metric in your account, read its values for a recent window, and inspect the returned series. This guide covers the public read workflow. Use the Console to author custom metrics.
Before you begin
The examples use Bash, curl 7.76 or later for --fail-with-body, and Python 3 to choose a recent UTC window and inspect JSON. Run the blocks in the same shell. Supply a key associated with your account through VECTARA_API_KEY without putting it in source control. See API key management.
These examples target the Vectara SaaS endpoint. Use the endpoint provided for your deployment if it differs. No credentials are sent by the setup block itself.
Permissions
Reading metrics requires at least one account role: metrics_viewer, corpus_viewer, corpus_developer, corpus_administrator, viewer, administrator, or owner.
Creating, editing, and deleting custom metrics in the Console requires administrator or owner. Metrics access does not grant trace inspection access.
1. Prepare a recent window
The following setup chooses the last complete five-minute boundary as the end and a start one hour earlier. Rounded boundaries make a whole-window comparison easier to interpret. The window is recent enough for a built-in metric but is not guaranteed to contain activity for your agent.
Prepare the shell
Code example with bash syntax.1
2. Discover the catalog
List metrics and inspect the built-in invocation counter
Code example with bash syntax.1
Expected result: the selected descriptor names agent.trace.count, type counter, unit count, and dimension agent_keys. Despite its stable name and display description, this metric counts recorded invoke_agent spans, not distinct trace IDs. See observation scope.
The catalog also contains your custom metrics. Inspect origin to distinguish system and custom metrics. The optional category parameter narrows categories, not origins. Preserve unknown future origin values rather than assuming only the current values can ever appear.
3. Read and inspect an agent's series
Set AGENT_KEY to a key from your account. The interactive prompt avoids supplying a fictitious agent as a supposedly working default.
Read an invocation count series
Code example with bash syntax.1
Expected result: the response echoes the metric name and dimension filter and reports its chosen bin width. Scalar points contain bin_start and value. Inspect the returned timestamps, not an assumed sequence starting exactly at your requested start. With no recorded matching activity, do not expect a particular positive value.
Illustrative response
The following is a synthetic schema-format fixture, not a production capture or the result of the preceding commands. The agent key, date, and value are illustrative. Do not reuse its date as a current system-metric query window.
Illustrative counter series
Code example with json syntax.1
The scalar value is the bin's aggregate, not a process-lifetime counter. The response also carries the metric descriptor. Percentile points instead carry a percentiles array and distribution points a bins array. See series interpretation rather than treating every type as a scalar.
Query custom metrics and dimensions
Replace the URL's metric name with the exact custom name from the catalog. Use that descriptor's dimension names, not an assumed agent_keys. A custom dimension reading the agent key can be named agent_key or another valid name chosen when it was created.
An undeclared dimension is rejected. Several values for a dimension match any of those values and merge into one series. An absent filter merges across that dimension. This is filtering, not a native group-by request. Prefer dimensions over the deprecated labels query parameter. The illustrative response retains deprecated aliases because the response schema includes them.
Time windows and bins
| Setting | Behavior |
|---|---|
start | Inclusive requested start. For system metrics it must be no more than 30 days before now. |
end | Exclusive requested end, after start. |
| Window length | At most 30 days. Custom metrics may have older retained data readable in additional windows. |
max_bins | Upper bound from 1 to 1000, default 60. Fewer points can be returned. |
bin_size_seconds | Actual bin width chosen by the platform. |
Bins align to a time grid. With max_bins=1, the start rounds down and the end rounds up to five-minute boundaries. Use already-aligned boundaries, like the setup block, when comparing whole-window aggregates.
Do not sum distinct counts or average percentiles from smaller bins to obtain a whole-window result. Request the aggregate for that window. For external ratios, keep the window and scope aligned, distinguish numerator and denominator intentionally, and handle a zero denominator. See measurement recipes.
Diagnose a failed or unexpected read
The curl commands exit unsuccessfully on HTTP errors but preserve the response body in the output file. The Python extraction runs only after curl succeeds. On failure, inspect metrics-catalog.json or metric-series.json before retrying. Do not treat either file as a successful response just because it exists.
| Status or symptom | Next check |
|---|---|
400 | Window order/length, max_bins, and declared dimension names and values. Read the returned detail. |
403 | Account association and the roles listed under Permissions. |
404 | Exact metric name in the catalog. |
422 | Whether a custom metric's stored definition can still be evaluated. Inspect it in the Console. |
| Empty or unexpected values | Agent/filter population, returned bin boundaries, and custom-metric lifecycle and coverage. |
See the creation diagnostic sequence for custom metrics. An empty result alone does not identify a platform failure.
API reference
Use List available metrics for the catalog and Query a metric time series for series reads. Those generated operation pages are the authoritative parameter and response contracts. This guide covers the integration sequence rather than duplicating their full schemas.