自前版のSlack通知

自前版ではsystemd timerを使い、問い合わせAPIとは別のプロセスで異常を検出する。Slack Incoming Webhookへ通知し、既存の監視基盤は必要としない。通知に本文・氏名・メールアドレス・IP・トークン・ログの原文を含めない。ここに記載する設定はサーバーへ手動で反映する。リポジトリの変更だけでは通知は有効にならない。

通知条件

毎分、直近5分の記録と現在のサービス状態を確認する。

対象 初期条件
全体送信上限超過 1件以上
IP別送信上限超過 10件以上
503・依存先障害 1件以上
メール送信失敗・結果不明 1件以上
起動・サーバー・DBの期限切れ削除の失敗 1件以上
サービス停止 ActiveStateがactive以外
NGINXの429 10件以上
NGINXの5xx 1件以上
ログ取得・サービス状態の照会失敗 失敗を検出したとき

同じ種類の異常は通知成功後15分間抑制する。複数の異常は1回の投稿へまとめる。継続中のサービス停止は15分ごとに再通知する。復旧通知は送らない。件数は5分の集計窓ごとに計算し、窓が重なる実行の件数を加算しない。閾値と抑制時間はbackend/contact-form/src/monitor.mjsで定義する。

Slack送信失敗時は未送信の異常をローカルへ保存し、次回以降に再試行する。待ち時間は1分から最大15分まで増加し、Slackの429ではRetry-Afterも考慮する。送信待ち中に異常が解消しても、JSTの検出時刻を付けて後から通知する。Webhookのタイムアウトや送信成功直後のプロセス停止では、再試行により重複通知する可能性がある。

配置するサーバー

構成 MONITOR_MODE 配置先・確認対象
APIとNGINXが別ホスト API側はapp APIのjournalとtectas-contact.service
APIとNGINXが別ホスト NGINX側はproxy 専用アクセスログとnginx.service
APIとNGINXが同じホスト both 上記の両方

別ホストの場合は、それぞれに以下の設定を行う。ラベルをproduction-app、production-proxyのように分ければ、同じSlackチャンネルで通知元を識別できる。ラベルには英数字・_・-を40文字以内で指定し、個人情報を記入しない。NGINX側にもNode.js 24系とsystemdが必要になる。Ubuntu 24.04を対象とする。

プロキシにNode.jsがない場合

/usr/bin/node --versionで「そのようなファイルやディレクトリはありません」と出る場合は、監視を配置する前にNode.js 24系を用意する。静的サイトのビルドはCI/CDで行うが、今回のログ監視はNGINXサーバー上でNode.jsを使って実行する。API本体、SQLite、SMTP設定の配置やnpm ciは不要である。

Ubuntu 24.04では、NodeSourceの配布手順に従って次を実行する。外部のAPTリポジトリを追加する作業となる。既存アプリへの影響を確認するため、実インストール前に候補とシミュレーション結果を確認する。

sudo apt update
sudo apt install ca-certificates curl
curl -fsSL https://deb.nodesource.com/setup_24.x -o /tmp/tectas-monitor-nodesource-24.sh
sudo bash /tmp/tectas-monitor-nodesource-24.sh
apt-cache policy nodejs
sudo apt install --simulate nodejs

候補が24系で、既存アプリに必要なパッケージの削除等がないことを確認してからインストールする。

sudo apt install nodejs
/usr/bin/node --version

v24.x.xと表示されたら、監視用ユーザー・プログラム・設定の配置へ進む。serviceのExecStartは/usr/bin/nodeを参照するため、対話シェルのnvm等で別パスにだけNode.jsを入れる方法はこの手順では使わない。既存のNGINX設定やサイトのCI/CD配置方法は変更しない。

1. SlackのWebhookを用意する

Slackの公式手順に従い、管理者がSlackアプリのIncoming Webhooksを有効にし、通知先チャンネルへのWebhookを作成する。ワークスペースのポリシーに応じてアプリの承認が必要になる。

Webhook URLはチャンネルへ投稿するための秘密情報として扱う。Git、フロントの環境変数、チケット、チャットへ貼り付けない。実装はhttps://hooks.slack.com/services/...形式だけを許可し、リダイレクトには追従しない。外向きにSlackへのHTTPS 443番と名前解決を許可する。

2. プログラムと秘密情報を配置する

次は各サーバー上の対象コミットのリポジトリ直下で実行する。プログラムはAPIとは別ディレクトリへ置くため、NGINX側へのAPI・SMTP設定の配置は不要である。監視プログラムはNode.js標準機能だけを使用し、npm ciは不要。

最初に、固定の監視用システムユーザー・グループを確認する。-s filesで、一時的なDynamicUserではなくローカルの永続アカウントを確認する。両方が存在しない場合だけuseraddを実行する。既存の場合は専用の監視用途かを確認し、別用途のアカウントを流用しない。

getent -s files passwd tectas-contact-monitor
getent -s files group tectas-contact-monitor
sudo useradd --system --user-group --no-create-home \
  --shell /usr/sbin/nologin tectas-contact-monitor
/usr/bin/node --version
getent group systemd-journal
getent group adm
sudo install -d -o root -g root -m 755 /opt/tectas-contact-monitor
sudo install -o root -g root -m 644 backend/contact-form/src/monitor.mjs /opt/tectas-contact-monitor/monitor.mjs
sudo install -o root -g root -m 644 backend/contact-form/src/monitor-run.mjs /opt/tectas-contact-monitor/monitor-run.mjs
sudo install -d -o root -g root -m 700 /etc/tectas-contact-monitor
sudo touch /etc/tectas-contact-monitor/slack-webhook
sudo chmod 600 /etc/tectas-contact-monitor/slack-webhook
sudoedit /etc/tectas-contact-monitor/slack-webhook

エディターでWebhook URLだけを1行で記入する。実URLをコマンド引数やシェル履歴へ残さない。既存のWebhookファイルがある場合は、通知先を確認して必要な場合だけ編集する。

初回は環境設定例をコピーし、対象サーバーに合わせて編集する。既存のmonitor.envがある場合はコピーを省略し、必要な項目だけ変更する。

sudo install -o root -g root -m 600 infra/contact-form/self-hosted/monitor.env.example /etc/tectas-contact-monitor/monitor.env
sudoedit /etc/tectas-contact-monitor/monitor.env

例:API側はMONITOR_MODE=app・MONITOR_LABEL=production-app、NGINX側はMONITOR_MODE=proxy・MONITOR_LABEL=production-proxyとする。Webhook URLはmonitor.envへ入れない。systemdのLoadCredentialで実行時だけ読み込む。

監視は事前作成した固定ユーザーtectas-contact-monitorで実行する。User・Groupを指定し、DynamicUser=yesの保護・状態ディレクトリの管理は維持する。同名の固定アカウントが存在すれば動的UIDは割り当てられない。動的UIDだけの構成では、一部のD-Bus環境でsystemctlの照会が拒否されるためである。systemd公式仕様

journalとNGINXログを読むためにsystemd-journal・admグループを付与する。これらのグループには他サービスのログの読み取り権限もある。プログラムは問い合わせAPIのjournalと指定の専用アクセスログだけを取得し、生の記録をSlackや監視ログへ出力しない。

3. NGINX側のログを用意する

proxy・bothではnginx設定例のcontact_safe形式を使用する。既存の汎用アクセスログを指定しない。ログファイルはNGINXが書き込め、admグループが読み取れる所有者・権限にする。Ubuntuの既存のNGINXログローテーション設定を確認し、専用ログも対象に含める。

NGINX_ACCESS_LOGは現行ファイルの絶対パスを指定する。監視は現行ファイルと、存在する場合は未圧縮の.1を読む。ローテーションはdelaycompressを使い、NGINXのログ再オープンと新規ファイルのグループ読み取りを確認する。ログ保持は30日を運用方針とし、既存のlogrotate設定に組み込む。各ファイルの末尾最大4 MiBを取得するため、大量アクセス時の件数は下限値となる場合がある。

4. 定期実行を有効にする

sudo install -o root -g root -m 644 infra/contact-form/self-hosted/tectas-contact-monitor.service /etc/systemd/system/tectas-contact-monitor.service
sudo install -o root -g root -m 644 infra/contact-form/self-hosted/tectas-contact-monitor.timer /etc/systemd/system/tectas-contact-monitor.timer
sudo systemd-analyze verify /etc/systemd/system/tectas-contact-monitor.service /etc/systemd/system/tectas-contact-monitor.timer
sudo systemctl daemon-reload
sudo systemctl enable --now tectas-contact-monitor.timer
sudo systemctl start tectas-contact-monitor.service
sudo systemctl list-timers tectas-contact-monitor.timer --all
sudo journalctl -u tectas-contact-monitor.service -n 20 --no-pager

monitor_idleは通知対象なし、または抑制・再試行待ち、monitor_sentは通知成功、monitor_failedは通知失敗または監視自体の異常を示す。失敗時にもログへ例外・Webhook URL・Slackの応答本文を出さない。systemctl status tectas-contact-monitor.serviceの終了状態も確認する。

未送信の異常と通知抑制の状態は/var/lib/tectas-contact-monitor/state.jsonへ保存する。systemdがディレクトリを管理し、ファイルは非公開とする。平常時に手動で状態ファイルを削除すると通知の抑制と再試行が失われる。通常実行はsystemctl startで行い、同じ状態ファイルへ複数の監視プロセスを直接起動しない。

5. 接続テストと受入確認

次のコマンドはSlackへテスト通知を1回送る。実行前に通知先チャンネルを確認する。APIへの投稿やSMTP送信は行わず、通常監視の状態も更新しない。

sudo systemd-run --wait --collect --unit=tectas-contact-monitor-test \
  -p DynamicUser=yes \
  -p User=tectas-contact-monitor \
  -p Group=tectas-contact-monitor \
  -p EnvironmentFile=/etc/tectas-contact-monitor/monitor.env \
  -p LoadCredential=slack-webhook:/etc/tectas-contact-monitor/slack-webhook \
  /usr/bin/node /opt/tectas-contact-monitor/monitor-run.mjs --test

テスト通知を受信できた後、検証環境で次を確認する。本番APIの停止や送信上限の消費を伴う試験は、メンテナンス中に行う。

  • API側:APIを停止し、次回実行で停止通知が届く。再起動後は正常に監視を継続する。
  • API側:全体上限超過と503を検出し、15分以内の繰り返しでは同じ種類の通知が増えない。
  • NGINX側:429が5分間に10件以上になると通知され、5xxも検出される。
  • Slackへ接続できない間も問い合わせ処理が動き、監視ログに失敗だけが記録される。接続回復後に未送信の通知が届く。
  • Slack・監視ログ・状態ファイルに、問い合わせの入力値や生のIPが含まれない。

ソースの自動テストは次で実行できる。Slackの応答とログを代替し、実際のSlack投稿やSMTP送信は行わない。

npm test --prefix backend/contact-form

更新・停止と制約

更新時はtimerを停止し、実行中の監視serviceの終了を確認してから2つのプログラムを同じコミットの内容へ更新する。設定・Webhook・状態ディレクトリは維持し、timerを再開する。Webhook変更後は次回のservice起動で新しい値を読み込む。

sudo systemctl stop tectas-contact-monitor.timer
sudo systemctl stop tectas-contact-monitor.service
# 同じコミットのmonitor.mjsとmonitor-run.mjsを前述のinstallで配置する
sudo systemctl start tectas-contact-monitor.timer

計画停止中も監視を続けるとAPI停止が通知される。必要ならメンテナンス中だけtimerを停止し、作業終了後に再開する。監視を廃止する場合はsystemctl disable --now tectas-contact-monitor.timerで停止する。

同じホストの監視では、サーバー停止・ネットワーク全断・timer自体の停止をSlackへ通知できない。5分を超える監視停止中に発生して解消した異常も拾えない。ホスト外からの死活監視は別途必要になる。APIのactive状態だけではHTTP・SMTPの正常動作を保証せず、負荷をかけない外部疎通確認も今後の検討対象とする。

サービス状態を取得できない場合

Slackの「サービス状態を取得できません」は、APIの停止を確定した通知ではなく、監視からsystemctl showを実行できなかった通知である。2026年11月16日の反映作業では、rootの照会はactiveだった一方、DynamicUserだけの照会で「通信端点が接続されていません」が再現した。動的ユーザーとdbus-daemonの組み合わせにはsystemd上流の同様の報告がある。

旧設定からは次の順で更新する。API自体を停止する必要はない。

  1. sudo systemctl stop tectas-contact-monitor.timer、続けてsudo systemctl stop tectas-contact-monitor.serviceで監視だけを止める。
  2. 本書第2節のgetent -s filesで永続ユーザー・グループを確認し、両方がなければ専用アカウントを作成する。
  3. 次のコマンドで固定ユーザーからの照会を確認する。正常稼働中のAPIならactiveになる。proxy側では対象をnginx.serviceへ置き換える。
sudo systemd-run --wait --pipe --collect \
  -p DynamicUser=yes \
  -p User=tectas-contact-monitor \
  -p Group=tectas-contact-monitor \
  -p 'SupplementaryGroups=systemd-journal adm' \
  -p NoNewPrivileges=yes \
  -p ProtectSystem=strict \
  -p ProtectHome=yes \
  /usr/bin/systemctl show tectas-contact.service --property=ActiveState --value
  1. /etc/systemd/system/tectas-contact-monitor.serviceの[Service]内にUser=tectas-contact-monitorとGroup=tectas-contact-monitorを追加する。DynamicUser=yes、StateDirectory、LoadCredential、既存の保護設定は維持する。更新済みリポジトリのunitを再配置する方法でもよい。
  2. sudo systemd-analyze verify /etc/systemd/system/tectas-contact-monitor.serviceの成功後にsudo systemctl daemon-reloadし、sudo systemctl start tectas-contact-monitor.serviceで1回実行する。ログと終了状態を確認してからtimerを再開する。
sudo systemctl show tectas-contact-monitor.service -p Result -p ExecMainStatus
sudo journalctl -u tectas-contact-monitor.service --since '2 minutes ago' --no-pager
sudo systemctl start tectas-contact-monitor.timer

正常終了はResult=success・ExecMainStatus=0である。monitor_idleだけでは通知抑制中の異常を見逃すため、固定ユーザーからの照会成功と両方を確認する。Webhook・監視状態ファイルは維持し、手動で削除・作り直しをしない。状態ディレクトリの所有者はsystemdが管理する。送信待ちの過去の照会失敗が残っている場合は、修正後にも古い検出時刻の通知が届くことがある。