パネルは正確で、問いのほうが違っていた

一言でいうと

パネルが間違った値を描くことは、まれです。よくあるのは、私たちが尋ねていない問いの答えを、パネルが正確に見せていることです。

なぜ必要なのか

障害が終わったあとの振り返りで、よく出てくる言葉があります。「ダッシュボードは正常でしたよ」。ところが、同じ時間の元データを測り直してみると、異常は確かにありました。クエリも合っていて、データもありました。その間で消えたのは、パネルオプションです。

数字1つを大きく表示するパネルがあるとします。人はそれを「いまの値」として読みます。ところが、そのパネルが実際に計算しているのは、画面に表示された時間範囲の平均かもしれません。6時間を見ていたなら、20分間の急増は、平均の中でほとんど消えてしまいます。パネルは正確でした。ただ、「過去6時間の平均はいくつか」という、誰も尋ねていない問いに答えていたのです。

欠けた点も同じです。収集が30分途切れると、その区間には点がありません。線をそのままつなぐと、グラフはなめらかに流れ、見る人は、その30分間もサービスが問題なく動いていたと読みます。途切れたのはデータがないという事実ですが、つないで描くという選択が、その事実を消してしまいます。

どう動くのか

Grafanaのパネルは、大きく3つの層です。クエリが時系列を取得し、フィールド設定と変換がそれを整え、可視化オプションが描き方を決めます。誤って読まれるパネルは、たいてい2つ目と3つ目の層で生まれます。そのため、クエリをいくら見つめても、原因が見えません。

オプション	何を決めるか	間違えるとどうなるか
計算値(reduceOptions.calcs)	時系列1つを数字1つに減らす方法	平均にすると、急増が埋もれます
null値の扱い(spanNulls)	欠けた点をつなぐかどうか	つなぐと、収集の中断が消えます
スタック(stacking.mode)	系列を積み重ねるかどうか	積むと、個々の値が読めません
系列数	パネル1つがいくつ表示するか	値1つの質問に、ボックスが4つ表示されます

まず、計算値です。時系列には点が複数ありますが、数字1つのパネルは、そのうちの1つを選ばなければなりません。最後の値を選べば「いま」、平均を選べば「この期間の平均」、最大値を選べば「この期間の最悪」です。3つはまったく別の問いで、パネルのタイトルは3つを区別してくれません。そのため、タイトルが「リクエストレート」なら、人は必ず「いまのリクエストレート」として読みます。その読み方とパネルの計算がずれていれば、画面は静かに間違います。

null値の扱いは、3通りです。つないで描く・切る・0で埋める、です。3つはそれぞれ、「そのあいだにも値があった」「そのあいだはわからない」「そのあいだは0だった」と主張します。カウンターの変化率のように、収集が途切れると本当にわからなくなる値は、切って描く必要があり、キューの長さのように、0が意味を持つ値は、状況によって違います。大事なのは、どちらを選んでも主張をしているという事実を知ったうえで選ぶことです。

スタックは、全体の合計が見たいときにだけ正しいです。積み上げたグラフのいちばん上の線は、どの系列の値でもなく、すべての合計ですが、人の目は、いちばん上の線を「最も大きい系列」として読みます。系列どうしを比べるのが目的なら、積まないようにし、割合が知りたいなら、100%スタックのように、割合を明示的に語る形を使います。

最後に、タイトルと説明です。Grafanaのパネルには、説明を書く場所があり(パネル編集のドキュメント)、そこに問いの文を書いておくと、2つのことが一度に解決します。読む人は、このパネルをどう読めばよいかがわかり、半年後にこのパネルを削除してよいかどうかも判断できます。その問いをまだ尋ねているかどうかだけを見ればよいからです。

現場での姿

決済サービスの状態ダッシュボードで、実際にあったことです。エラー率のパネルは1日中緑だったのに、顧客からの問い合わせは入り続けていました。パネルはstatで、計算値は平均で、既定の時間範囲は24時間でした。午前中の12分間、エラー率は30%でしたが、1日の平均では0.25%でした。計算値を最後の値に変えて、時間範囲を1時間に縮めたところ、同じ事故が翌週には3分で目に付きました。

もう1つは、スタックでした。ハンドラー別のリクエストレートのパネルがスタックで描かれていて、チームは、いちばん上の線を/api/ordersのリクエストレートとして読んで、キャパシティプランを立てました。実際の/api/ordersは、その半分でした。数字を直したのではなく、スタックをオフにしただけで、誤解が消えました。

この環境で判定できることとできないこと

このPodのGrafanaは本物として動いていますが、画像レンダラープラグインがありません。そのため、パネルが画面にどう描かれるかは検査できません。その代わり、ダッシュボードJSONモデル(計算値・null値の扱い・スタック・タイトル・説明)と、そのクエリをデータソースで実際に実行した値で判定します。色が実際にどう見えるか、線がどこで途切れるかは、結局、目で一度見る必要があります。ラボでも、Webプレビューで3000番ポートを開いて確認してみることをお勧めします。

次のラボですること

欠陥が6つ入ったダッシュボードをそのままアップロードしておいて、計算値・null値の扱い・スタック・系列数・タイトルと説明を、1つずつ直します。直すたびに、なぜその選択が間違っていたのかを、数字で確認します。固定した区間でlast・mean・maxを自分で測り、ある時刻で合計と個々の値をそれぞれ測って、スタックが何を隠していたかを見ます。最後に、同じ欠陥を次のダッシュボードでも見つける検査ツールを作り、直したダッシュボードがその検査を通ることまで確認します。