octocovで任意のメトリクスを記録できるようにした（カスタムメトリクス）

octocov

octocovはコードカバレッジのためのツールキットです。

github.com

コードカバレッジなどのコードメトリクスを手元のターミナルで確認したり、GitHub ActionsのActionとしてPull Requestにレポートしたりできます。

計測したコードメトリクスを、さまざまなデータストアに蓄積することもできます。

octocovはコードカバレッジ、Code to Test ratio、テスト実行時間の3つのコードメトリクスを計測しますが、今回、任意のメトリクスに対応しました。

カスタムメトリクス

カスタムメトリクスの使用方法は簡単です。

計測したメトリクスを指定のフォーマットで保存する（カスタムメトリクスJSON）
octocovに環境変数経由でカスタムメトリクスJSONの保存パスを渡す

これだけです。

1. 計測したメトリクスを指定のフォーマットで保存する（カスタムメトリクスJSON）

カスタムメトリクスが対応できるのはKey-Value形式で、かつValueが数値であるメトリックです。

それを次のようなJSONフォーマットで保存します。

{
  "key": "benchmark_0",
  "name": "Benchmark-0",
  "metrics": [
    {
      "key": "N",
      "name": "Number of iterations",
      "value": 1000
    },
    {
      "key": "NsPerOp",
      "name": "Nanoseconds per iteration",
      "value": 676.5,
      "unit": " ns/op"
    }
  ]
}

JSONスキーマはこちらに定義しています。

2. octocovに環境変数経由でカスタムメトリクスJSONの保存パスを渡す

カスタムメトリクスJSONが保存しているパスを OCTOCOV_CUSTOM_METRICS_ をプレフィックスにつけた任意の環境変数でoctocovに渡します。カスタムメトリクスJSONは、OCTOCOV_CUSTOM_METRICS_1 OCTOCOV_CUSTOM_METRICS_2 のようにいくつ渡しても構いません。

例えばGitHub Actionsでoctocov-actionを使っている場合は次のように指定します。

steps:

[...]

      - name: Run octocov
        uses: k1LoW/octocov-action@v0
        env:
          OCTOCOV_CUSTOM_METRICS_BENCHMARK: custom_metrics_benchmark.json

これで設定は終わりです。

あとはoctocovがもともと対応している3つのコードメトリクスと同じようにPull Requestにレポートしたり比較したりしてくれます。

octocov-go-test-bench

1つの例として go test -bench の結果をoctocovのカスタムメトリクス形式に変換するコマンドを作成しました。

github.com

次のように go test -bench の標準出力をoctocov-go-test-benchに渡すだけでoctocovのカスタムメトリクス形式に変換して出力してくれます。

そのままJSONファイルに保存すればよいです。

同時にベンチマークの出力結果も確認したい場合は --tee オプションを付与してください。

$ go test -bench . -benchmem | octocov-go-test-bench --tree > custom_metrics_benchmark.json
goos: linux
goarch: amd64
pkg: github.com/k1LoW/rp
cpu: Intel(R) Xeon(R) Platinum 8272CL CPU @ 2.60GHz
BenchmarkNGINX-2       10000        635221 ns/op       17720 B/op        139 allocs/op
BenchmarkRP-2          10000        376138 ns/op       64199 B/op        191 allocs/op
PASS
ok      github.com/k1LoW/rp 25.807s

GitHub Actions上での具体的な設定例としては、私が別で開発しているOSSの設定を見ると良いでしょう。