https://chromium.googlesource.com/chromium/src.git/+/HEAD/tools/metrics/histograms/README.md

ガイドライン

ヒストグラムには３種類ある。

• 列挙ヒストグラム
• カウントヒストグラム（数は任意）
• 分散ヒストグラム（広い範囲での正確性が必要な場合、あるいはあらかじめ範囲がわからない場合）

ヒストグラムに名前をつける

なまえはGourp.NameまたはGroup.Subgroup.Nameの形をとる。

コード（ヒストグラムに出力）

通常はhistogram_functions.hを使う。histogram_macros.hではマクロも定義されていてそれらを使うこともできる。効率を求める場合、つまり頻繁に出力するときやクリティカルパス上のときはマクロを使うと良い。マクロはヒストグラムオブジェクトのポインタをキャッシュしする。効率性を求めないときは関数を使う。

同じヒストグラムログを複数の場所で使わないこと

これらのロギングマクロや関数は長い名前を持ちしばしば追加のパラメーターをもつ。可能ならヘルパー関数を使うこと。

ヒストグラムマクロを使うときは固定文字列を使うこと

UMA_HISTOGRAM_ENUMERATIONのようなヒストグラムマクロを使うときは、文字列を動的に生成しないこと。１つの呼び出し場所に対して同じ文字列でマクロが呼び出されなくてはならない。動的な文字列を使いたい場合は関数を使うこと。

効率

通常はヒストグラム出力にかかるコストは考えなくても良い（分散ヒストグラムは別）。通常のヒストグラムのコードは優れて最適化されている。パフォーマンスを考えなくてはならない場所でヒストグラムを記録するときはマクロを使うこと。

ヒストグラムのタイプを選ぶ

求めているものを直接測る

関数コールにかかる時間であったり、ページ転送のバイト数であったり、リスト内のアイテム個数だったりを直接測れる。他のヒストグラムから計算したデータを使用しないこと。こうしたやり方はだいたい間違っている。例えば関数呼び出しにかかった時間を考えるとき、その関数は２つの他の関数を呼び出すだけで、それらの関数呼び出しがヒストグラム出力されている場合、これらのヒストグラムからデータを取得すれば良いと考えるだろう。これは間違っている。これらの呼び出しがどのヒストグラム出力に関わっているかを知っていてそれらを合計するならいいが、ヒストグラムにはタイムスタンプがないので２つの関数を独立なものと思えばよいが、それはわからない。他のヒストグラムデータに頼らずに知りたいものを直接測ること。

列挙ヒストグラム

相互に関連したデータのリストを出力したいときは列挙ヒストグラムを使う。例えば新規タブページで行えるアクションの集合などは良い例である。

列挙ヒストグラムはイベントのカウントにも使える。 Use a simple boolean histogram. It‘s okay if you only log to one bucket (say, true). It’s usually best (though not necessary), if you have a comparison point in the same histogram. For example, if you want to count pages opened from the history page, it might be a useful comparison to have the same histogram record the number of times the history page was opened.

If only a few buckets will be emitted to, consider using a sparse histogram.