NewRelicのTIMESERIES句。
自分は最初「なんかグラフにするときにつけるやつ」ぐらいの認識しかありませんでした。ドキュメントと挙動を確認しながらまとめてみます。

結論(わたしの理解)

TIMESERIESを使えばデータを指定した粒度で時系列に分割できる。
時系列データにすることで線グラフなどで表示できるようになる。

このデータを

5分間隔で分割する(TIMESERIES 5 minutes)

線グラフ表示などもできるようになる

基本的な動きから確認

ドキュメント::TIMESERIES句

TIMESERIES句を使用して、指定期間単位の時系列としてデータを返します。

設定した間隔を使用する

時間範囲を指定するには、integer unitsを使用します。
例:
TIMESERIES 1 minute
TIMESERIES 30 minutes
TIMESERIES 1 hour
TIMESERIES 30 seconds

TIMESERIES 1 minute

TIMESERIES 5 minutes

設定間隔にあわせた粒度で表示されます。

自動設定した間隔を使用する

TIMESERIESはAUTOに設定することもでき、これによってグラフが適切な数の区分に分割されます。たとえば、1日のチャートは30分間隔で分割され、1週間のチャートは6時間間隔で分割されます。

グラフの対象期間に合わせて間隔を自動で調整してくれます。

60 minutes に対して TIMESERIES AUTO を設定

キャプチャだとわかりにくいですが1分間隔の粒度でグラフが表示されました。

6 hours(=360 minutes) に対して TIMESERIES AUTO を設定

15分間隔の粒度でグラフが表示されました。

MAXインターバルを使用する

TIMESERIESをMAXに設定することで時間枠が自動的に調整され、指定された期間に許可された間隔数を最大にできます。これによって、TIMESERIESバケットを手動で更新することなく時間枠を更新でき、認められた最大インターバル数に時間枠を分割できます。返されるTIMESERIESバケットの最大数は366です。

ここで「許可された間隔数」「バケット」という言葉で出てきました。
TIMESERIESは指定した時間間隔でデータを区切ることができます。その１つの区間をバケットと呼び、その分割数(=バケット数)には366個という限界があります。

指定期間のなかで最大の366分割までできるだけ使って細かい粒度にしてくれるのがMAXという指定です。

6 hours(=360 minutes) に対して TIMESERIES MAX

1分間隔の粒度でグラフが表示されました。360分割なのでMAX近くまでバケットを使って細分化してくれています。
前述の「6 hours(=360 minutes) に対して TIMESERIES AUTO」と比較するとわかりやすいです。

367 minutes に対して TIMESERIES MAX

2分間隔の粒度でグラフが表示されました。(単独のキャプチャだとわかりにくいので「6 hours(=360 minutes)」のグラフと見比べてもらえれば)

367分を1分間隔で分割しようとすると366を超えてしまうので2分間隔で切ってくれています。

バケット数不足のケース

では長い対象期間に対してバケット数の限界を超える細かい間隔を指定したらどうなるか？

「We can't render this query: TIMESERIES supports a maximum of 366 buckets」とエラーが出てくれます。

応用してみる

実案件で「とある処理を設計上ベストエフォートで繰り返す」という処理が存在しました。
このサービスのSLI/SLOの１つとして「10分の間に1回以上この処理が実行されている割合が99.9%以上」というものを設定しました。

こういったものもTIMESERIESを使うことで計測/可視化できます。

/* 前提条件：とある処理をしたらexmonitor_targetというメトリクス に「1」を記録しているとする */
SELECT average(ok) * 100 as percent FROM (
   SELECT (max(exmonitor_target) or 0) as ok FROM Metric TIMESERIES 10 minutes
)

「(SELECT (max(exmonitor_target) or 0)」としているのはTIMESERIESで分割した10分の間に処理が実行されたかをTrue(1)or False(0)で集計したいので、count(総回数)ではなくmax(値=記録されるのは1のみ)で集計しています。
max(exmonitor_target)は、データがない場合nullを返すのでnullが帰ってきた場合は0にするよう or 0しています。

10分の間に1回以上この処理が実行されている割合

1分の間に1回以上この処理が実行されている割合

終わりに

なんとなく使っていたTIMESERIESですが、理解することで「「10分の間に1回以上この処理が実行されている割合」という指標もクエリで可視化することができました。

TIMESERIESを理解するのとき、いつも「Line」表示しているグラフの生データを「Table」で表示してみるとイメージの助けになるかもしれません。

Line

SELECT count(`aws.lambda.Invocations`) FROM Metric TIMESERIES 5 minutes SINCE 60 minutes ago

Table

SELECT * FROM (
  SELECT count(`aws.lambda.Invocations`) FROM Metric TIMESERIES 5 minutes
) SINCE 60 minutes ago