telegraf から Mackerel にメトリックを投稿する
まとめ
telegraf の Input プラグインが集めたメトリックを Mackerel にホストメトリック / サービスメトリックとして投稿できる
telegraf とは
telegraf はさまざまなメトリックを収集・送信するエージェントです
telegraf には拡張性の高いプラグインシステムがあり、幅広いメトリックを扱うことができます
例えば Input プラグインはメトリックの収集を担当します
ビルドインのものだけでも無数にあります
一方で Output プラグインはメトリックの送信を担います
今回は Mackerel にメトリックを送信したいので、Output プラグインを作ってみます
telegraf のプラグイン開発
原則 Go 言語で書きます
公式のガイドはこの辺りにあります
要は telegraf.Output インターフェイスを実装すればいいわけです
code:sample.go
//go:embed sample.conf
var sampleConfig string
type Simple struct {
Ok bool toml:"ok"
Log telegraf.Logger toml:"-"
}
// デフォルトの設定ファイルを返す
func (*Simple) SampleConfig() string {
return sampleConfig
}
// コネクション貼ったりが必要な場合はここで呼ぶ
func (s *Simple) Connect() error {
return nil
}
// リソースのクローズ用
func (s *Simple) Close() error {
return nil
}
// メトリックを外部に書き込む処理を実装する
func (s *Simple) Write(metrics []telegraf.Metric) error {
return nil
}
func init() {
outputs.Add("sample", func() telegraf.Output { return &Simple{} })
}
Mackerel にメトリックを送信するようにしたのが telegraf-output-mackerel です
telegraf-output-mackerel の使い方
大体 README に書いてある通りです
1. telegraf 本体の設定ファイル telegraf.conf に以下の設定を追記します
code:telegraf.conf
outputs.exec
timeout = "10s"
--config で渡すのは telegraf-output-mackerel の設定ファイルです
後述しますが、設定ファイルを別に用意する必要がある事情があります
2. telegraf-output-mackerel が参照する設定ファイル telegraf-output-mackerel.conf を作成します
一方で設定ファイルを用意しなくても、環境変数で渡すこともできます (ファイルはなくても良いです)
code:telegraf-output-mackerel.conf
outputs.mackerel
# 必須
# Mackerel のダッシュボードで発行できる API キーです
# 当然スコープに書き込み権限を付与する必要があります
# 環境変数 $MACKEREL_API_KEY で設定可能です
api_key = ""
# どちらか指定、メトリックの送信先を指定します
# 特定のホストに紐つく「ホストメトリック」にしたい場合は host_id にホスト ID を
# 特定のサービスに紐つく「サービスメトリック」にしたい場合は service_name にサービス名を指定します
# 環境変数 $MACKEREL_HOST_ID か $MACKEREL_SERVICE_NAME でも設定可能です
host_id = ""
service_name = ""
# 任意
# メトリック名のプレフィックスを指定します、ほかと衝突しないプレフィックスにすることをお勧めします
# デフォルトは telegraf です
# 環境変数 $MACKEREL_METRIC_PREFIX でも設定可能です
metric_prefix = "telegram"
telegraf-output-mackerel の仕様
telegraf が想定するメトリックと Mackerel が受け入れるメトリックには仕様の差が存在します
telegraf のメトリック
<metric_name>[,<tag_key>=<tag_value>...] [<field_key>=<field_value>...] + タイムスタンプ
Mackerel のメトリック
<metric_name>.<field_key> <field_value> + タイムスタンプ
<metric_name> に使用できる文字種は ^[a-zA-Z0-9._-]$
両者を比較すると決定的な差は Mackerel には tag を表す手段が存在しないことです
そのため、メトリックを送信する際に以下のルールで変換します
1. custom.<prefix>.<metric_name>.<tags>.<field_key> をメトリック名とする
<tags> は以下のように連結する
<tags> = <tag1_key>-<tag1-value>_<tag2_key>-<tag2-value>_...
キーと値を - で連結する
タグ間は _ で結合する
2. <metric_name> を変換する
使用できない文字種が見つかったら _ に置換する
メトリック例
custom.telegraf.sensors.chip-coretemp-isa-0000_feature-core_0_host-lily.*
https://scrapbox.io/files/640aec5afbdc95001bf436b7.png
本来 telegraf では
<metric_name> = sensors
<tag1_key> = chip
<tag1_value> = coretemp-isa-0000
<tag2_key> = feature
<tag2_value> = core_0
<tag3_key> = host
<tag3_value> = lily
<field1_key> = temp_input
<field1_value> = CPU 温度
というデータ構造になっている
が、Mackerel に投稿するとタグがくっついて判別不能になることもあります