単位のない数字は、読む人が勝手に決めてしまう
一言でいうと
単位が書かれていない数字は、読む人が単位を作り出します。そして作り出された単位は、たいていその人に都合のよいほうになります。
なぜ必要なのか
障害対応会議で、誰かがダッシュボードを表示して言います。「レイテンシが0.42です」。会議室の半分は420ミリ秒と受け取り、残りの半分は0.42ミリ秒と受け取りました。2つの数字は1,000倍違い、一方は事故で、もう一方は自慢です。会話はさらに20分ほど続き、誰かがクエリを開いて見るまで終わりませんでした。
こうしたずれは、人が不注意だから生じるのではありません。画面が数字だけを見せるから生じます。Grafanaには値に単位を付ける機能がありますが、その機能は私たちが何であるかを伝えたときだけ動作します。何も伝えなければ、Grafanaは数字をそのまま描き、解釈は見る人に委ねられます。
さらに悪いのは、単位を書いたのに間違って書いた場合です。単位がなければ、人々は少なくとも疑います。単位が付いていれば、誰も疑いません。秒で出るクエリにミリ秒の単位を付けておくと、画面は「0.42 ms」と自信たっぷりに言い、それを見た人は、サービスがとても速いと信じます。
どう動くのか
Grafanaの単位は表示ルールであって、変換ルールではありません。パネルのfieldConfig.defaults.unitに識別子を書くと、Grafanaはその識別子に結び付いた書式関数で、数字を文字列に変えます。値そのものには手を加えません。そのため、秒で出る値をミリ秒で表示するには、単位だけを変えるのではなく、クエリに1000を掛ける必要があります。
識別子は、画面に表示される名前とは違います。ドロップダウンには「Percent (0.0-1.0)」と書かれていますが、JSONに入る値はpercentunitです。「bytes(IEC)」はbytesで、「bytes(SI)」はdecbytesです。前者は1024で割ってGiBに縮め、後者は1000で割ってGBに縮めます。同じ4294967296が、4 GiBにも4.29 GBにも見えます。どちらが正しいかは、その数字を作り出した側が何を数えたかによります。
割合も2種類あります。0と1のあいだで出る値にはpercentunitを、0と100のあいだで出る値にはpercentを使います。PromQLで作ったエラー率はほとんどいつも前者なのに、パネルには後者が付いていることがよくあります。すると、1.6%のエラー率が、画面では0.016%に見えます。アラートは鳴っているのにダッシュボードは穏やかに見える状態は、こうして作られます。
軸は、単位の次に来る2番目の嘘の場所です。Grafanaは既定で、データに合わせてy軸を自動的に決めます。秒あたりのリクエスト数が34から75のあいだを行き来すれば、軸も34から75に決まり、その中で線は画面の高さいっぱいに揺れ動きます。実際には2倍ほどの差なのに、画面は崖のように見えます。そのため、量を数えるパネルの最小値は0に固定するほうが誠実です。標準オプションのドキュメントのMin・Maxが、その場所です。
逆に、最大値はむやみに固定してはいけません。最大値を20に固定したリクエスト数のパネルは、トラフィックが75まで上がった日にも、20で切れた平らな天井を見せます。事故はいつもその天井の上で起きるのに、画面には残りません。変動が小さくて線が平らに見えるのが嫌なら、ハードな最大値の代わりに、時系列パネルのSoft min・Soft maxを使います。データがその範囲を超えると、軸が一緒に広がるので、切れません。
1つのパネルに、単位の異なる2つを一緒に描かなければならないこともあります。レイテンシとエラー率を重ねて、「遅くなった時刻と失敗が増えた時刻は同じか」を問うパネルがそうです。このときは、パネル全体の単位を1つにしておき、残りの系列にだけ、オーバーライドで単位と軸の位置を別に与えます。時系列パネルのドキュメントには、単位が2つ以上あると最初の単位が左の軸を、その後ろの単位が右の軸を使うと書かれています。オーバーライドなしにそのまま重ねると、2つの系列が1つの軸を共有することになり、0.004の割合は、0.3のレイテンシの隣で、底に張り付いた直線になります。
ログ軸は、大きさが大きく異なる系列を1つの画面に置くときに使います。秒あたり42件のハンドラーと6件のハンドラーを線形軸に一緒に描くと、小さいほうの変化は見えません。ログ軸では、同じ縦の距離が同じ倍数を意味するため、どちらも読めるようになります。代わりに失うものがあります。目盛りの間隔がもう量の差ではないので、面積を目で足せず、0と負の数はそもそも描けず、2倍に跳ねた出来事と10倍に跳ねた出来事が、似た高さの差に見えます。そのため、「どれだけ増えたか」を問うパネルには向きません。
このラボが判定できないものが1つあります。それは実際に描画された絵です。このPodのGrafanaには画像レンダラープラグインがないため、パネルを画像として取り出せません。そのため、採点ツールはダッシュボードJSONモデルとクエリ結果だけを見ます。単位の識別子が何か、軸の最小値がいくつか、クエリが実際にどんな値を出すかは、すべて確認できますが、その組み合わせが画面で読みやすいかどうかは確認できません。軸の名前が重なって切れたり、凡例がグラフを覆ったりする種類の問題は、Webプレビューで3000番ポートを直接開き、目で見なければなりません。モデルが正しいことと、画面が読めることは、別の話です。
現場での姿
あるチームは、メモリ使用量のパネルにSI単位を付けていました。コンテナの上限は4 GiBなのに、画面には4.29 GBと表示され、人々は「まだ余裕がある」と読みました。その夜、そのPodは上限に引っかかって落ちました。値は一度も間違っていませんでした。間違っていたのは名前だけです。
別のチームでは、エラー率のパネルが何か月ものあいだpercentで付いていました。実際のエラー率が2%まで上がった日にも、画面は0.02%を表示しました。アラートは正常に鳴りましたが、担当者はダッシュボードを見て「アラートが誤って鳴ったようだ」と判断し、無視しました。ポストモーテムで最も長く話し合われたのは、アラートルールではなく、その単位の1文字でした。
次のラボですること
本物のGrafanaを起動して、単位のないパネルを1つアップロードし、その数字が何通りに読めるかを自分で書いてみます。次に、秒・割合・バイトのパネルにGrafanaの単位識別子を入れ、クエリを投げて、値の大きさと単位が合っているかを確認し、ミリ秒で表示するには何を掛ければよいかを手で確かめます。軸の最小値を0に固定すべき場所と、最大値を固定してはいけない場所を見分け、単位の異なる2つの系列を1つのパネルにオーバーライドで載せ、ログ軸を使ったあとで何を失ったかを書きます。最後に、本番から取り出してきたダッシュボードを1つ受け取り、単位・軸の欠陥4つをすべて直して提出します。採点ツールは、直したダッシュボードをGrafanaに問い合わせ、パネルのクエリを実際に投げて、値と単位が合っているかを見ます。