We support defining queries via JSON.
You can use defined queries in Honeycomb with:
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 or CONCURRENCY, which need no column). If no calculations are provided, COUNT is applied. See below for a list of valid ops.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 ops.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.havings: a list of objects describing filters with which to restrict returned groups. Each having consists of a calculate_op (the same set used for op in calculations, but excluding HEATMAP), a column (except for COUNT, which needs no column), an op (=, >, >=, <, <=), and a value (currently assumed to be numeric). Each column/calculate_op pair must appear in the calculations field. There can be multiple havings for the same column/calculate_op pair.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. 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
}
This query specification describes a query over the last hour that 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 that have a P99(duration_ms) > 10000, 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" }
],
"havings": [
{ "calculate_op": "P99", "column": "duration_ms", "op": ">", "value": 10000 }
],
"limit": 100,
"time_range": 3600
}
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)CONCURRENCY (does not expect an accompanying "column" value)SUMAVGCOUNT_DISTINCTMAXMINP001P01P05P10P25P50P75P90P95P99P999HEATMAPRATE_AVGRATE_SUMRATE_MAX Filter operators are consistent between the API and the UI.
These are the available filter "op" values:
=!=>>=<<=starts-withdoes-not-start-withexists (does not expect an accompanying "value")does-not-exist (does not expect an accompanying "value")containsdoes-not-containin (filter "value" must be present and be an array),not-in (filter "value" must be present and be an array)