MackerelのAPIを使って性能データをCSV形式で出力してみた

どうも、SCSKの谷です。

私の部署では監視サービスを提供しているのですが、実際に監視しているメトリックデータの数値を見たいというお客様が一定数います。
そのようなお客様に対してMackerelを利用した監視サービスを提供する場合、Mackerelではグラフを参照することはできますが、
実際に監視で得られた数値を参照することはできないので、お客様の要望に応えられません。

そこで、MackerelはAPIを公開しているので、APIを利用して監視対象のメトリックの数値データを取得してこれるのではと考え、実装してみることにしました。

部署の後輩である嶋谷君が書いた最近の記事について以下にまとめてますので、ご覧になっていない方は是非ご覧ください！

■投稿記事
・Mackerel でマイクロサービスを監視してみた – TechHarmony
・CloudWatchのアラート通知をMackerelに移行してみた – TechHarmony

性能データCSVダウンロードスクリプト
1. スクリプト詳細
2. 使用方法
性能データCSVダウンロード結果
スクリプト所感
補足） MoniPro Mに実装しました
1. 性能データCSVダウンロード機能
2. 所感
まとめ

性能データCSVダウンロードスクリプト

概要
今回は、PowerShellを用いて性能データをCSVでダウンロードするスクリプトを作成しました。
大まかに以下の2手順で性能データをCSVでダウンロードしていきます。
1.　APIを用いて、Mackerel上の監視対象ホストの指定したメトリクスの時系列データを取得し、JSON形式で保存
2.　取得したJSONデータをCSV形式に変換
機能要件
・CSV形式で性能データを出力できること
・APIで取得する性能データの取得期間を指定できること
・指定したメトリクスのデータを取得できること
実行環境
今回の実行環境はWindows11です。
（PowerShellの実行環境とインターネットへの接続環境があれば、利用できる想定です)

スクリプト詳細

作成したスクリプトは以下の構成からなります。

getcsv.ps1	親スクリプト	必要情報の入力と子スクリプトの呼び出し
getjson.ps1	子スクリプト	APIを用いて対象ホストのデータを取得しJSON形式で保存
writejsontocsv.ps1	子スクリプト	JSON形式のファイルをCSV形式に変換し保存

getcsv.ps1（必要情報の入力と子スクリプトの呼び出し）

以下、getcsv.ps1のスクリプトとなります。

#getcsv.ps1

param(
    [string]$dateTime,
    [string]$apiKey,
    [string]$hostId,
    [string]$metricName,
    [string]$startDateTime,
    [string]$endDateTime,
    [string]$jsonFilePath,
    [string]$csvFilePath
)

#現在日時取得
$dateTime = (Get-Date).ToString("yyyyMMddHHmmss")

#出力先設定
$jsonFilePath = "jsonの出力先パス\response.json"
$csvFilePath = "csvの出力先パス\output_$dateTime.csv"

#各パラメータ入力
$apiKey = Read-Host "APIキーを入力してください"
$hostId = Read-Host "ホストIDを入力してください"
$metricName = Read-Host "取得するメトリクス名を入力してください"
$startDateTime = Read-Host "開始日時を入力してください(yyyymmdd hhmmss)"
$endDateTime = Read-Host "終了日時を入力してください(yyyymmdd hhmmss)"

#JSONデータ取得バッチ実行
.\getjson.ps1 -apiKey $apiKey -hostId $hostId -metricName $metricName -startDateTime $startDateTime -endDateTime $endDateTime

Write-Output "取得したJSONデータをCSVに変換します"

#CSV変換バッチ実行
.\writejsontocsv.ps1 -jsonFilePath $jsonFilePath -csvFilePath $csvFilePath

(1) 必要パラメータの入力
パラメータの詳細につきましては、スクリプトの実行手順で説明しています。

(2) JSONデータ取得バッチ実行
getjson.ps1に必要なパラメータを渡して、実行します。

(3) CSV変換バッチ実行
writejsontocsv.ps1に必要なパラメータを渡して、実行します。

getjson.ps1（APIを用いて対象ホストのデータを取得しJSON形式で保存する処理）

以下、getjson.ps1のスクリプトとなります。

#getjson.ps1

param (
[string]$apiKey,
[string]$hostId,
[string]$metricName,
[string]$startDateTime,
[string]$endDateTime
)      

# UNIXタイムスタンプに変換
$wkstartDateTime=[DateTime]::ParseExact($startDateTime, "yyyyMMdd HHmmss", $null).ToUniversalTime()
$fromUnixTime = [int][double]::Parse($wkstartDateTime.Subtract([datetime]'1970-01-01').TotalSeconds)

$wkendDateTime=[DateTime]::ParseExact($endDateTime, "yyyyMMdd HHmmss", $null).ToUniversalTime()
$toUnixTime = [int][double]::Parse($wkendDateTime.Subtract([datetime]'1970-01-01').TotalSeconds)

# APIリクエストURLの作成
$apiUrl = "https://api.mackerelio.com/api/v0/hosts/$hostId/metrics?name=$metricName&from=$fromUnixTime&to=$toUnixTime"

# APIリクエストの実行
$response = Invoke-RestMethod -Uri $apiUrl -Headers @{ "X-Api-Key" = $apiKey } -Method Get

# JSONデータをテキストファイルに保存
$response | ConvertTo-Json | Out-File -FilePath "response.json"

Write-Output "APIリクエストが完了し、データがresponse.jsonに保存されました。"

(1) 入力した日時をUNIXタイムスタンプに変換
APIリクエストURLではUNIXタイムスタンプである必要があるため、最初に「yyyyMMdd HHmmss」で指定した開始日時と終了日時を
UNIXタイムスタンプに変換しています。

(2) APIリクエストURLの作成
入力した値を組み合わせて、ホストのメトリックの値取得用のAPIリクエストURLを作成します。
メトリクス名及び取得開始日時、取得終了日時はクエリパラメータで指定してます。
・name = メトリック名
・from = 取得開始日時
・to = 取得終了日時
APIリクエストURLについては、以下のMackerel公式ドキュメントを参考にしています。
Mackerel API ドキュメント（v0） – Mackerel API ドキュメント (v0)

(3) APIリクエストの実行
作成したAPIリクエストURLを実行し、メトリックのデータを取得します。
Invoke-RestMethodを使用してAPIリクエストを実行しています。

(4) 取得したデータをJSON形式で保存
取得したデータをConvertTo-JsonでJSON形式で保存します。
ファイルの保存先として、実行しているフォルダ上にそのまま保存してます。

writejsontocsv.ps1（JSON形式のファイルをCSV形式に変換し保存）

以下、writejsontocsv.ps1のスクリプトとなります。

#writejsontocsv.ps1
param(
[string]$jsonFilePath,
[string]$csvFilePath
)        

# JSONファイルを読み込み
$jsonContent = Get-Content -Path $jsonFilePath -Raw | ConvertFrom-Json

# 出力用のCSVデータを格納するための配列を初期化
$csvData = @()

# 各メトリクスを処理
foreach ($metric in $jsonContent.metrics) {
# UNIXタイムをJSTの "YYYYMMDD HHMMSS" 形式に変換
$timeJST = [System.TimeZoneInfo]::ConvertTimeBySystemTimeZoneId(
[System.DateTimeOffset]::FromUnixTimeSeconds($metric.time), "Tokyo Standard Time"
).ToString("yyyy/MM/dd HH:mm:ss")

# CSVの行を作成
$csvData += [PSCustomObject]@{
Time = $timeJST
Value = $metric.value
}
}

# CSVファイルとして出力
$csvData | Export-Csv -Path $csvFilePath -NoTypeInformation -Delimiter ','

Write-Host "JSONファイルからCSVファイルへの変換が完了しました。出力ファイル: $csvFilePath"

(1) JSONファイルの読込
getjson.ps1で出力したメトリックデータのJSONファイルを読み込みます。

(2) 各メトリクスの処理
JSONファイル内のパラメータは「Time（日時）」と「Value（メトリックの値）」となっているので、
上記を1ペアとして配列に繰り返し格納していきます。

(3) CSVファイルの出力
配列内に格納したデータをExport-Csvを用いてCSVファイルとして出力します。

使用方法

作成した性能データ出力スクリプトの使用方法を説明していきます。

事前準備

Powershellのバッチ実行設定で実行可になっていない場合、以下作業を実施してバッチ実行可に変更する必要があります。

(1) Windows PowerShellを管理者として実行する

(2)「Get-ExecutionPolicy」と入力し、「Restricted」の場合は以下を実行(「RemoteSigned」の場合は実行不要です。)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
実行ポリシーの変更に「Y」

対象ホストのメトリック名の確認

コマンドプロンプトで取得対象のメトリック名を確認します。

(1) コマンドプロンプトを開く

(2) 以下のコマンドを入力する
curl -k -X GET -H “X-Api-Key:【APIキー】” “https://api.mackerelio.com/api/v0/hosts/【ホストID】/metric-names”
(3)出力したいデータのメトリック名を確認する

スクリプト実行

スクリプトを実行して、性能データをCSV形式で出力します。

(1) 以下のスクリプトファイルを任意の場所に設置する
・getcsv.ps1
・getjson.ps1
・writejsontocsv.ps1

(2) PowerShellを開く

(3) スクリプトの設置場所にカレントディレクトリを移動する

(4) getcsv.ps1を実行する

(5) 必要なパラメータを入力する
データの取得のために必要なパラメータを入力していきます。
パラメータについては以下の通りです。

変数名	パラメータ	概要
apiKey	APIキー	MackerelへAPIリクエストするために必要なAPIキー
hostId	ホストID	Mackerel上に登録されているホストを識別するための一意のID、取得したいホストのIDを指定
metricName	メトリック名	Mackerelで監視しているホストのメトリックの中で取得したいメトリック名を指定
startDateTime	取得開始日時	メトリックデータを取得したい期間の開始日時
endDateTime	取得終了日時	メトリックデータを取得したい期間の終了日時

APIキーについては、以下から確認できます。オーガニゼーション詳細ページ > APIキータブ > APIキー　
ホストIDについては、以下から確認できます。
(6) パラメータ入力後、処理が実行されCSVファイルが出力されたこと確認する

指定した取得期間によりデータの時間幅（ピッチ）が変わる

Mackerel側の仕様で、指定した取得期間の長さによって、APIで取得したデータの時間幅が変わりますのでご注意ください。
参考として、以下に取得期間による時間幅をまとめております。

取得期間	時間幅（ピッチ）	例
1時間単位	1分	2025/5/1 15:00 ~ 2025/5/1 18:00
1日単位	5分	2025/5/1 15:00 ~ 2025/5/4 15:00
1週間単位	10分	2025/5/1 15:00 ~ 2025/5/14 15:00
1月単位	1時間	2025/5/1 15:00 ~ 2025/7/15 15:00

性能データCSVダウンロード結果

本スクリプトを用いて、以下のメトリックのデータを取得してみました。

取得データ	メトリック名	備考
CPU使用率	cpu.steal.percentage
メモリ使用率	memory.used、memory.total	(memory.used/memory.total)*100で算出
ディスク使用量	filesystem.xvda1.used

取得対象のホストは以下の通りです。
AWS EC2
・CPU　t2.micro
・RAM　0.93 GiB
・OS　　Linux/UNIX
・ストレージ　8GiB

取得期間は「2025年5月21日 7時19分」から「2025年5月21日 13時19分」の6時間となります。

CPU使用率

CSVデータをもとにEXCELで作成したグラフです。
Mackerelの管理画面でのグラフです。

メモリ使用率

CSVデータをもとにEXCELで作成したグラフです。
メモリ使用率につきましては、直接APIで取得できないので、メモリ使用量とメモリサイズのメトリックデータを取得し、計算しています。

Mackerelの管理画面でのグラフです。
Mackerelにはメモリ使用率のメトリックがないため、メモリ使用量のグラフとなっております。

ディスク使用量

CSVデータをもとにEXCELで作成したグラフです。
ディスク使用量とディスクサイズのメトリックデータを組み合わせています。

Mackerelの管理画面でのグラフです。
同様に、ディスク使用量とディスクサイズのグラフとなっております。

スクリプト所感

今回でスクリプトを作成したことによりメトリックデータをCSV形式ダウンロードできるようになったので、データを成形したり複数のデータを組み合わせることができるようになりました。また、Mackerel上のグラフでは、時間ごとの細かいメトリックの数値を把握することが難しかったので、可視化しやすくなったと感じました。スクリプト自体も単純な対話形式のものにしたので、誰でも利用できるようにできたかなと思います。

実際に使ってみて、コマンドでメトリック名一覧を出力後に、出力したいメトリックデータのメトリック名を探し出すのは大変だと感じました。また、毎回APIキーやメトリック名を入力しなけらばならないので、そこは結構手間だと感じました。

CSV形式でダウンロードできるようにすることが今回の大きな目標だったのでひとまず達成することができました。
しかし、利便性の面ではまだまだ改善の余地があると感じています。

■改善点の例
・ファイル出力先を指定できない
・複数のメトリックデータを一度に取得できない
・複数ホストメトリックデータを一度に取得できない
など

補足） MoniPro Mに実装しました

実は、今回のスクリプトをもとに開発担当の方に内容を改善いただき、弊社のサービスであるMoniPro Mでも監視データをcsvダウンロードできるようにしていただきました。

MoniPro Mにつきましては、下記の公式サイトを参照ください。
MoniPro M｜SCSK株式会社

性能データCSVダウンロード機能

性能データCSVダウンロード機能はSCSK の統合監視プラットフォーム「FusionCORE」のうちのお客様向けポータルである
HEARTIL Contact Portal(HCP)内の機能になります。

取得したいホストとメトリックを選択し、ダウンロードボタンを選択することで性能データをCSV形式でダウンロード可能です。
選択したそれぞれのCSVファイルがアーカイブされZipファイル形式でダウンロードされます。
メトリックについては取得可能なメトリックのみ選択できるようになっています。

■特徴
・Mackerelの管理単位である、サービス、ロールで対象ホスト絞りこむことが可能
（「サービス」「ロール」とは – Mackerel ヘルプ）
・取得開始時間と取得終了時間を指定可能
・複数のホストとメトリックの性能データCSVを同時にダウンロードが可能
・Zipファイル形式にアーカイブされた状態でダウンロード

所感

今回の機能追加にあたり、サービスの機能として利用できるよう開発担当の方に本スクリプトを修正・改善をしてもらってHCPに実装していただきました。

HCPへの実装後に実際に利用してみて、自身が作成したときのスクリプトよりも非常に利用しやすくなっており感動しました。
以下に利用しやすくなったと感じた点をまとめております。
・ダウンロードしたいメトリックのチェックボックスを選択するという直感的な操作で簡単に性能データCSVをダウンロード可能
・ホスト名の左側にあるチェックボックスを選択することで選択可能なメトリックをまとめて選択できる
・検索条件でサービスやロールから対象ホストを絞りこむことができるので、Mackerel上のホストが多くても対象ホストの性能データを
簡単にダウンロード可能
・複数ホストと複数メトリックをまとめてダウンロードできるので、一つずつダウンロードする手間がかからず便利