新機能ではないけど，Mackerel の「グラフアノテーション機能」は便利でよく使っている．メトリクスの推移を分析するときに，同じタイミングで発生したイベント情報（デプロイ／キャンペーン開始／テレビ放送など）と紐付けることができる．実際にアノテーションを登録するときに「個人的によく使うパターン」がいくつかある．今回はパターンごとに「アノテーションを登録するスニペット」を整理しておく．

コンソールを使う

アドホックにアノテーションを登録する場合は，1番簡単な「コンソール」を使う．とは言え，以下の画像のように「グラフの時刻部分をドラッグする」のは気付くにくく，Mackerel 初学者には使ってもらえなさそう．

f:id:kakku22:20200225115147p:plain

`mkr` コマンドを使う

シェルからアノテーションを登録する場合は，mkr コマンドを使う．mkr annotations を使うと簡単に登録できる．--from と --to に指定するタイムスタンプは「UNIX 時間（エポック秒）」にする．

$ mkr annotations create --title 'アノテーション (Title) from mkr' \
  --description 'アノテーション (Description) from mkr' \
  --from $(date +%s) \
  --to $(date +%s) \
  --service 'xxxxx'

github.com

f:id:kakku22:20200225113343p:plain

Mackerel Client を使う

Ruby と Go で実装したアプリケーションからアノテーションを登録する場合は「Mackerel Client」を使う．例えば，mackerel-client-ruby と mackerel-client-go はグラフアノテーションをサポートしている（他の Client も使えると思う）．以下は mackerel-client-ruby で post_graph_annotation() を使っている．

require 'mackerel-client'
require 'time'

client = Mackerel::Client.new(mackerel_api_key: ENV['MACKEREL_API_KEY'])

client.post_graph_annotation(
  {
    title: 'アノテーション (Title) from Ruby Client',
    description: 'アノテーション (Description) from Ruby Client',
    from: Time.now.to_i,
    to: Time.now.to_i,
    service: 'xxxxx'
  }
)

github.com

f:id:kakku22:20200225113404p:plain

Mackerel API を使う

Python で実装したアプリケーションからアノテーションを登録する場合は「Mackerel API」を直接 requests で実行して使う．

import json
import os
import requests
import time

params = {
    'title': 'アノテーション (Title) from API',
    'description': 'アノテーション (Description) from API',
    'from': int(time.time()),
    'to': int(time.time()),
    'service': 'xxxxx'
}

requests.post(
    'https://api.mackerelio.com/api/v0/graph-annotations',
    json.dumps(params),
    headers={'Content-Type': 'application/json', 'X-Api-Key': os.environ['MACKEREL_API_KEY']}
)