observalibity の柱である MELT の "E" : Mackerel のグラフアノテーションを活用する

この記事はMackerel Advent Calendar 2025の12/12 (金)分である。

observability の三本柱と event

observability とは system の狀態を何らかの telemetry によって表現し、telemetry から system の狀態を推測しようとする一連の枠組みである。telemetry のよく知られた種類に、metric・log・trace がある。例へば一分每の HTTP response time や CPU load average を記錄して樣子を伺ふのは metric だ。HTTP request log や code に埋め込んだ debug log から處理を知るのは log だ。HTTP request を受けてから response を返すまでの一連なりの處理で起こった出來事を追跡し分析するのが trace だ。

metric・log・trace の他にも telemetry はある。その一つが event だ。event は、system に起こった重要な出來事を記錄したもので、application の deploy・設定の變更・instance の增減等を見る。形は log に同じだが、system に大きな變化を齎す出來事のみに絞る點が異なる。event は metric・log・trace と合はせてしばしば "MELT" と略される。

※他にも telemetry はある

他によく活用されるのは例外 (exception)・profile 等である。

※しばしば "MELT" と略される

metric・event・log・trace を、metric を中心に置いて圖に描くと以下の樣になる。

metric・event・log・traceの關係を表してゐる

metric : 特定の期閒の system の狀態を幾つかの數値に表現し測定したもの。latency・request 數・error 率・disk IO 量等。
event : system に加へたあるいは加はった變更を記錄したもの。deploy・設定の變更・user による特定の操作等。
log : system で處理を行ふたびにその處理內容を主に text 形式で記錄したもの。debug log 等。
trace : 處理を開始してから完了するまでの處理を追跡したもの。分散した system に亙る處理を分析するのにも有用。

Mackerel のグラフアノテーションに event を記錄する

metric を眺めてゐると system 傾向が大きく變はってゐる樣を見つける事がある。傾向の變はる原因の大半は deploy や batch 處理の開始等の event だ。metric を見てゐる最中に event と直ぐに對照できればすぐに原因を知れ便利である。この爲にグラフアノテーションがある。

Mackerelのloadavg5のグラフで、途切れてゐる期閒に「メンテンナンス」とアノテーションを附してある

グラフが途切れてゐるのを見附け、原因を調べるとその期閒で maintenance に入れてゐた事を思ひ出したとする。再び思ひ出さずによい樣に、アノテーションを附してしまへばいい。

cf. グラフを利用する - Mackerel ヘルプ#グラフにアノテーションを作る

頻繁に起こる event ならば、event が發生する際に自動でアノテーションを投稿するといい。deploy の開始と完了をアノテーションとして投稿する事を考へるとしよう。CD server に mkr を install しておく。deploy 開始時刻と完了時刻を變數に入れておき、

mkr annotations create \
  --service 'YOUR-SERVICE' \
  --from "${start_timestamp}" \
  --to "${end_timestamp}" \
  --title 'deploy した revision と成否などを書くといいでせう' \
  --description 'deploy の log への link などを書くといいでせう'