NextcloudのジョブをGrafanaで監視できるようにする

こんにちは、id:taiseiueです。この記事は、はてなエンジニア Advent Calendar 2025 - Hatena Developer Blogの45日目の記事です。

昨日の記事は、id:tunacookさんによるNaninovelのシナリオ文字カウントをするVSCode拡張を作った - ツナサンド定食でした。

今日の記事では、Nextcloudのジョブの状態を監視できるようにしてみます。

Nextcloudのジョブが実行されない問題

1年前くらいから、知人とDJスタジオを運営しており、その一環でDJプレイ中の録画を保管しておくためのNextcloudをRaspberry Pi 5で稼動しています。

普段の使用(アクティブユーザー>5くらい)までであれば問題なく動作するんですが、アクセスが集中したり、大容量の録画のプレビューを生成したりすると、上手くバックグラウンドジョブが実行されずに通知が送信されなかったり、管理画面で警告が表示されたりします。

そこで、今回はNextcloudのジョブの状態をGrafanaで監視できるようにすることをゴールにします。

Nextcloudのジョブはどう管理されているか

Nextcloudでジョブはoc_jobsテーブルで管理されています。 Nextcloud Version 32.0.3でのテーブルの構造はこんな感じでした。

MariaDB [nextcloud]> DESCRIBE `oc_jobs`;
+--------------------+---------------------+------+-----+---------+----------------+
| Field              | Type                | Null | Key | Default | Extra          |
+--------------------+---------------------+------+-----+---------+----------------+
| id                 | bigint(20) unsigned | NO   | PRI | NULL    | auto_increment |
| class              | varchar(255)        | NO   | MUL |         |                |
| argument           | varchar(4000)       | NO   |     |         |                |
| last_run           | int(11)             | YES  |     | 0       |                |
| last_checked       | int(11)             | YES  | MUL | 0       |                |
| reserved_at        | int(11)             | YES  |     | 0       |                |
| execution_duration | int(11)             | YES  |     | 0       |                |
| argument_hash      | varchar(64)         | YES  |     | NULL    |                |
| time_sensitive     | smallint(6)         | NO   | MUL | 1       |                |
+--------------------+---------------------+------+-----+---------+----------------+

last_runはそのジョブが最後に実行された Unix timestamp、execution_durationは直近実行時の処理時間が入っています。この中のlast_runなどをメトリクスとしてPrometheusに送信できればいいわけですね。

ジョブの状態をPrometheusに送信する

作戦として、今回はexporterを自作するのではなく、cronで定期的にデータベースにジョブの状態を見に行ってテキストファイルに出力し、それをnode_exporterでPrometheusに送信するという素朴な方法を選んでみました。

cronでジョブの状態を見に行く

こんな感じのスクリプトを書いて、データベースにジョブの状態を引きに行ってprom形式で出力してあげます。

gist.github.com

あとはcronにスクリプトを毎分実行するように登録しておきます。

* * * * * /usr/local/bin/nc-jobs-textfile.sh 2>&1

これでしばらくたつと/var/lib/node_exporter/textfile/nextcloud_jobs.promにメトリクスが出力されてきます。

Prometheusに送る

sudo systemctl edit prometheus-node-exporterで/var/lib/node_exporter/textfileを収集するようにします。

[Service]
ExecStart=
ExecStart=/usr/bin/prometheus-node-exporter \
  --collector.textfile.directory=/var/lib/node_exporter/textfile

上手くいけばPrometheusにnextcloud_job_execution_duration_secondsなどのメトリクスが送られているはずです。

Grafanaで眺める

Grafanaで、最後のジョブからの経過時間を可視化できるようにしてみました。 Nextcloudのジョブは基本的に5分おきに走るので、最後のジョブからの経過時間が5分を越えると遅れ気味だというわけです。 min(time() - nextcloud_job_last_run_timestamp_seconds)というPromQLで取得しています。

ついでにいつ、どのジョブが走っているかも見れるようにしています。