Honeycomb supports defining queries via JSON for use in Query Template Links, the Query API, Boards API, and the Triggers API.
All fields are optional, but a query without any calculations
defined will default to a COUNT
.
breakdowns
: a list of strings describing the columns by which to break events down into groupscalculations
: a list of objects describing the calculations to return as a time series and summary table. Each calculation consists of an op
and a column
(except for COUNT
, which needs no column). If no calculations
are provided, COUNT
is applied. See below for a list of valid op
s.filters
: a list of objects describing the filters with which to restrict the considered events. Each filter consists of a column
, op
, and (sometimes) value
. See below for a list of valid op
s.filter_combination
: either "AND"
or "OR"
. If multiple filters are specified, filter_combination
determines how they are applied; set to "OR"
to match ANY filter in the filter list. Defaults to "AND"
.granularity
: an integer describing the time resolution of the query’s graph, in seconds. Valid values are the query’s time range /10 at maximum, and /1000 at minimum.orders
: a list of objects describing the terms on which to order the query results. Each term must appear in either the breakdowns
field or the calculations
field.limit
: an integer describing the maximum number of query results.time_range
: an integer describing the time range of query in seconds, for relative-time queries. Cannot be combined with both start_time
and end_time
(See caveat below.) Defaults to two hours.start_time
: an integer describing the UNIX timestamp of the absolute start time of the query.end_time
: an integer describing the UNIX timestamp of the absolute end time of the query.Specify columns using their key_name
s, even if they have an alias defined.
A Derived Column, however, must be specified by its alias as it is displayed in the Honeycomb UI.
To specify an absolute time range, use start_time
and end_time
(both UNIX timestamps) to describe the desired range:
{
"start_time": 1525125600,
"end_time": 1525132800
}
start_time
or end_time
can also be used in combination with time_range
to specify a fixed time plus a range.
Specifying values for all three fields, however, will result in an error.
The following describes “the one-hour period leading up to the absolute time 2018-05-01 00:00 UTC”:
{
"end_time": 1525132800,
"time_range": 3600
}
Without a start_time
or end_time
, a single time_range
argument will default to an end_time
of “now.”
The following describes “the last hour” relative to the time of invocation:
{
"time_range": 3600
}
This query specification calculates the top 10 (by volume, or COUNT
) unique user_agents
for the hour leading up to the absolute time 2018-01-01 00:00 UTC:
{
"breakdowns": ["user_agent"],
"calculations": [{ "op": "COUNT" }],
"orders": [{ "op": "COUNT", "order": "descending" }],
"limit": 10,
"time_range": 3600,
"end_time": 1514768400
}
This query specification calculates the AVG(content_length)
of events from the last hour matching kafka_partition = 3
or kafka_partition = 6
:
{
"calculations": [{ "column": "content_length", "op": "AVG" }],
"filters": [
{ "column": "kafka_partition", "op": "=", "value": 3 },
{ "column": "kafka_partition", "op": "=", "value": 6 }
],
"filter_combination": "OR",
"time_range": 3600
}
This query specification matches events with duration_ms > 500
and service_name != "fraud"
, then calculates a HEATMAP(match_quality)
(where the graph spans the last 3 hours, drawn at 15-minute intervals):
{
"calculations": [{ "column": "match_quality", "op": "HEATMAP" }],
"filters": [
{ "column": "duration_ms", "op": ">", "value": 500 },
{ "column": "service_name", "op": "!=", "value": "fraud" }
],
"granularity": 900,
"time_range": 10800
}
This query specification describes an absolute-time query which matches events with result = 200
, then calculates the AVG(duration_ms)
and P99(duration_ms)
broken down into unique (user_id
, build_id
) pairs. It then returns the first 100 results, ordered first by P99(duration_ms)
values, then user_id
:
{
"breakdowns": ["user_id", "build_id"],
"calculations": [
{ "column": "duration_ms", "op": "AVG" },
{ "column": "duration_ms", "op": "P99" }
],
"filters": [{ "column": "result", "op": "=", "value": 200 }],
"orders": [
{ "column": "duration_ms", "op": "P99", "order": "descending" },
{ "column": "user_id" }
],
"limit": 100,
"start_time": 1515542451,
"end_time": 1515546051
}
Calculation operators are consistent between the API and the UI.
These are the available calculation "op"
values:
COUNT
(does not expect an accompanying "column"
value)SUM
AVG
COUNT_DISTINCT
MAX
MIN
P001
P01
P05
P10
P25
P50
P75
P90
P95
P99
P999
HEATMAP
Filter operators are consistent between the API and the UI.
These are the available filter "op"
values:
=
!=
>
>=
<
<=
starts-with
does-not-start-with
exists
(does not expect an accompanying "value"
)does-not-exist
(does not expect an accompanying "value"
)contains
does-not-contain
in
(filter "value"
must be present and be an array),not-in
(filter "value"
must be present and be an array)