site_id.
This page explains how to build metric queries. For every field of each request and response, see the metrics endpoint reference.
Migrate from GraphQL metrics
Reading metrics through the GraphQL API is deprecated. If your integration reads metric data through GraphQL, use this comparison to move it to the REST API (V2) timeseries endpoint.Query a timeseries
This endpoint returns one or more series of data points over a time range. Use it to draw graphs.site_id, a from and to time range, and a select
array. Leave out resolution and AppSignal picks one for the time range. See
resolutions.
Each select entry requests one metric field. Provide a metric name, a tags
object, and a field (see fields). Tag values may use * as a
wildcard. You can also provide an aggregation (see
aggregations) and a fill value.
The fill values are ZERO (the default), PREVIOUS, and NONE. Existing
integrations can also use the optional draw_null_as_zero field. true fills
missing points with zero, like ZERO. false carries the previous value
forward, like PREVIOUS. If you send both fields, fill takes precedence.
Use uppercase values for field and aggregation. The timeseries endpoint does
not support group_by.
The reference lists a limit field, but the timeseries endpoint doesn’t apply
it. The number of series is capped by the processing
limits instead.
This request fetches the mean trace_duration of the web namespace. Its
draw_null_as_zero: false carries the last value forward over missing points.
series array, with one series per tag and field
combination that returned data.
Unlike the GraphQL metrics API, this endpoint does not require a separate metric
keys request. Use the series array to see which tag and field combinations
returned data. If a query may reach the processing
limits, do not use series.length as the
total number of matching metric keys.
Query a list
This endpoint returns aggregated metric values grouped into rows. Use it to build tables.site_id, from, to, and optional resolution
as a timeseries query, plus a group_by array. See
resolutions. To cap the number of rows, add
limit, or page through the list.
A list selector is like a timeseries selector, with an extra id. The id
names the selector’s value in each row’s data object.
Each group_by entry is one of these, and both are case-sensitive:
- The string
"Name", to group by metric name. - An object such as
{"Tag": "hostname"}, to group by a tag’s value.
field and aggregation. If a
selector uses * for a tag in tags, add the same tag to group_by as
{"Tag": "tag_name"} or the request fails.
rows array. Each row has a group object with the tag
values that define it. Its data object holds the aggregated values, keyed by
selector id, for example { "mean": 42.5 }.
Page through a list
Add apagination object to the request body to read the list in pages. It
needs all three of these fields:
per_page: how many rows to return per page.order:ASCorDESC. Rows are sorted by theirid.cursor:{ "id": null }for the first page.
pagination and limit, pagination takes precedence.
To get the next page, send the same request with cursor.id set to the last
row’s id. Repeat until a page comes back with fewer rows than
per_page. That page is the last one.
A paginated response has the same shape as any other list response.
400 response whose
error field names the problem:
per_pageaccepts values from 1 to 1,000. Other values returnpagination_invalid_per_page.- A paginated query reads up to 100,000 metric keys or rows across all its pages. Past
that limit, it returns
pagination_key_limit_exceededinstead of a partial result. Narrow the tag filters or the time range and send the request again. - For custom metrics, every tag that uses a
*wildcard must also appear ingroup_by. The metricnamecannot contain a wildcard. Otherwise the query returnspagination_requires_deterministic_grouping. - The event metrics
event_durationandevent_metric, and the incident error metricincident_error_count, cannot be paginated yet. They returnpagination_unsupported_for_selector. Query them in a separate request withoutpagination.
List metric names
Return every metric name available for a site.name in a query’s
select entries. To see how to query it, get its type and
tags. For the full response, see the List
metric names reference.
To narrow the list, add a filter query parameter, such as ?filter=queue. It returns only names containing that term, ignoring case, up to 200 characters.
Custom metrics appear only if they reported in the last 24 hours. The list holds at most 1,000 of them, and filter searches beyond those 1,000.
Get a metric’s type and tags
Return a metric’s type and the tag combinations it can be queried with.metric_type (GAUGE, COUNTER, or MEASUREMENT) and
available_tags, an array where each entry is one valid combination of tag keys.
The type decides which fields you can select. A GAUGE metric has
the GAUGE field, and a COUNTER metric has the COUNTER field. A
MEASUREMENT metric has MEAN, COUNT, MIN, MAX, and the percentiles. Use
a tag combination as the keys of a selector’s tags. For the full response, see
the Get a metric’s type and tags
reference.
Uptime monitor timings
Theuptime_monitor_timing gauge records how long each phase of an uptime
check took, in milliseconds. The phase tag selects the phase: dns,
connect, tls, ttfb, download, or total. See
request timing for what each phase
measures. Query the metric with region, phase, and either the monitor
name or id.
phase behaves differently in the two query endpoints:
- In a timeseries query,
phaseaccepts the*wildcard and returns one series per phase. - In a list query, each selector must name one phase. Add one selector per
phase you want, and group by
region,name, orid, not byphase.
tls on a plain HTTP URL and to download without a body check.
This list request returns the mean time per phase and region for one monitor:
Log metrics
Thelog_metrics metric turns log lines into numbers. It counts matching lines, or sums, averages, or finds the minimum or maximum of a numeric field. AppSignal computes it when you query, so it also covers logs you already sent. Query it through the timeseries or list endpoint, and configure it with the selector’s tags:
For each selector:
- Set
fieldtoGAUGE. Theaggregationtag sets the value; the selector’saggregationproperty is ignored. - Include both
source_idandquery. Without them, the selector returns nothing, and no error. - Name fields in dot notation, such as
user.age. - Aggregate only fields from your log’s JSON. Built-in fields such as
severityreturn a400.
- Timeseries: one series per
group_bycombination, with the field values as the seriestags. - List: one row per group, over the whole time range. Group with the
request’s
group_by, such as[{"Tag": "severity"}]. Agroup_bytag on the selector returns a400. Selectors that share a group merge into one row.
signup lines and averages their duration, per
severity:
- A row leaves out a selector whose field has no numeric value in that group.
- Lines without the grouped field are grouped under an empty string.
- The aggregated field can’t also be a
group_byfield. - Without pagination,
limitcaps each selector separately. A merged row can then miss some selectors’ values.
High-cardinality metric queries
A metric query has high cardinality when it matches more series than the endpoint can process. AppSignal stores each unique tag combination as a separate metric key. For example, every combination ofqueue and worker values
creates a separate metric key.
The limits in this section apply to custom metrics and transaction_duration.
They also apply to incident_error_count when a query uses a wildcard for
incident_digest or revision. They do not apply to other metrics in the
current V2 implementation.
Each metric key and field combination counts as one series. For example,
requesting MEAN and COUNT for one metric key counts as two series.
For affected metrics, AppSignal limits how many series it processes before fetching their data:
/api/v2/metrics/timeseriesprocesses up to 100 series./api/v2/metrics/listprocesses up to 1,000 series per page. A paginated query can read up to 100,000 metric keys across all its pages. See Page through a list.
select
entry. The limit field cannot raise them. Dashboard charts load their data
from /api/v2/metrics/timeseries, so the 100-series limit applies to charts too.
If a query matches more series than the endpoint can process, AppSignal returns
only part of the data. The response does not indicate that it is incomplete, so
aggregated totals may be too low. Repeating the same query returns the same
subset, but the result is still incomplete. To read more series from a list
query, page through it. A paginated query that matches
more than 100,000 metric keys returns pagination_key_limit_exceeded instead
of a partial result.
The Limits page shows which custom metrics report the
most unique tag combinations per minute. When tag values change over time, a
query over a longer range can match more series than the page shows.
Custom metrics work best with tags that have a small,
fixed set of values, such as region, plan, or queue. If an existing metric
has high-cardinality tags, exact tag filters can reduce the number of matching
series. However, the response cannot confirm that it contains every series. See
Metric tags for guidance on choosing tag values.
Reference
Fields
Thefield selects which measurement to retrieve from a metric:
To see which fields a metric has, get its type and
tags. For every type in the API, see
the machine-readable reference.
Aggregations
Theaggregation combines multiple values within a time bucket: SUM, AVERAGE, MIN, MAX, FIRST, or LAST.
If you leave out aggregation, the default depends on the field:
Resolutions
resolution accepts MINUTELY, HOURLY, or DAILY.
MINUTELY applies only when the range is 12 hours or shorter and starts within
the last 48 hours. Outside that window, AppSignal uses HOURLY instead and
reports it in the response’s resolution field.