2
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@1Kano(鹿野 市郎)

IT運用の手作業を廃止。空いた時間はレジリエンス強化に注力（Datadog Private Action Runner）

2
Posted at

図解で、Private Action Runner !

Datadog Private Action Runner の導入ガイドとして記録する。

はじめに

従来型ITインフラ監視では、「アラートを検知したら、定型作業手順書に従って復旧を試みる」などという作業を定義する場合があります。例えば、サーバーが応答しなくなったことを目視で確認したら、クラウド管理コンソールでサーバーを再起動したり、OSにログインして手順書の通りコマンドを実行して結果を報告したりしています。

しかし、この「手順書どおりに手作業を実行する」というスタイルには限界があります。

  • 夜間／土日でもアラート発生するリスク
  • 同時に、複数の異なるアラートが発生するリスク
  • アラートを検知してから作業に着手するまでの時間ロス
  • 作業手順の読み間違え。うっかり操作ミス
  • バージョンアップに伴う手順書の更新漏れ
  • 次々増えていく作業手順の種類／数量

image.png

究極のレジリエンス強化で目指す方向性は、この手作業そのものを自動化すること。削減した余力をアラートが発生しない恒久対策など「レジリエンスを根本から強化すること」システム設計の見直し、オブザーバビリティ拡大、ポストモーテムなどに振り向けることです。そして更なる余力は新しい仕事に取り掛かりたい。

Datadog の Workflow Automation と Private Action Runner (PAR) を組み合わせると、「アラート検知をトリガーにして、サーバーのスクリプトやCLIコマンドを自動実行できるようにワークフローを構築することで定型作業を無人実行する」という仕組みが作れます。本記事は、自動実行させた検証を記録します。
題材として、よくある「CPU使用率アラートを検知したら top コマンドでスナップショットを取得する」という定型作業手順を自動化してみます。

補足: Private Action Runner の公式ドキュメントは Dockerスタンドアロン版の記載が中心で、既存の Datadog Agent に組み込む具体的な手順はあまり整理されていません。本記事は実際に検証した結果を手順化したものです（2026年8月時点）

参考: Private Actions Overview

Private Action Runner とは

Datadog の Workflow / App は基本的に Datadogのクラウド側で動きますが、それだけでは以下のようなことができません。

  • プライベートネットワーク内のサーバーにあるコマンドやスクリプトを実行する
  • インターネットに公開していない社内システムの API を叩く

Private Action Runner は、こうした「Datadog から直接手が届かない場所のサーバー」に配置するエージェント的な仕組みです。対象サーバーに Runner を置いておくと、Datadog の Workflow からその Runner 経由で処理を実行できるようになります。

Runner は Datadog に対してアウトバウンドでポーリングしにいく方式のため、対象サーバー側でインターネットからのインバウンドのポートを開ける必要がありません。これも社内サーバーに導入しやすいポイントです。

全体の流れを図解で把握する

本書の例では、アラート検知したらサーバー内部でPythonを実行して結果をメールで報告します。

  1. 監視モニタリングが異常を検知してアラート発報
  2. アラートをトリガーにしてワークフローが起動
  3. ワークフローの事前定義したスクリプト［Run Predefined Script］が実行
  4. Datadog Agent が Remote Config をポーリングしタスクをひろう
  5. Datadog Agent が Private Action Runner でタスクを実行
  6. サーバー内部で python などのスクリプトが呼ばれる
  7. タスク実行結果をワークフローに送信
  8. ワークフローの続きが実行される。本書ではメールで結果報告

image.png

前提

  • 対象サーバーに Datadog Agent が導入済み
  • Agentのバージョンが v7.77.0 以上であること（Private Action Runner の必須条件)

ざっくり作業手順

  1. （必須条件｜必要ならば実行）Datadog Agent バージョンアップ　「7.77.0 以上」
  2. キー発行：Datadog ダッシュボードで Application key を作成
  3. Agent設定：datadog.yaml に、［private_action_runner］パラメータを追加
  4. 実行権限：OSユーザー［dd-agent］がスクリプトを実行、結果を書き込みできる権限を付与
  5. ワークフロー：Datadog ダッシュボード で Workflow Automation に［New Connection］を追加
  6. スクリプト指定：Connection に自動実行する Script を設定

今回自動化する定型作業

「CPU使用率アラートが出たら、作業担当者がサーバーにログインして top で状況を確認する」という定型作業を題材にします。これを、

  • Monitor: CPU使用率が30分平均で90%を超えたら発報
  • Workflow: Private Action Runner 経由でサーバー上の top を実行し、結果をメールで送る

という形で自動化します。

導入手順

1. OSで自動実行する Python スクリプトを作る

Datadog 側の設定を進める前に、まず対象サーバー上で単体で動く Python スクリプトを用意しておきます。先にローカルで動作確認しておくと、Datadog 側の設定に問題があるのか、スクリプト自体に問題があるのかを切り分けやすくなります。ディレクトリとファイル名は任意で定義し、あとで Agent に設定ファイルで教えます。

~/scripts/private_action/check_top.py

#!/usr/bin/env python3
"""Datadog Private Action: capture a `top` snapshot and append it to top-listed.json."""
import json
import subprocess
import sys
from datetime import datetime, timezone
from pathlib import Path

OUTPUT_PATH = Path(__file__).resolve().parent / "top-listed.json"
LINE_COUNT = 15
MAX_ENTRIES = 52


def capture_top() -> list[str]:
    result = subprocess.run(
        ["top", "-b", "-n", "1"],
        capture_output=True,
        text=True,
        check=True,
    )
    return result.stdout.splitlines()[:LINE_COUNT]


def append_entry(entry: dict) -> None:
    if OUTPUT_PATH.exists():
        entries = json.loads(OUTPUT_PATH.read_text(encoding="utf-8"))
    else:
        entries = []
    entries.append(entry)
    entries = entries[-MAX_ENTRIES:]
    OUTPUT_PATH.write_text(
        json.dumps(entries, ensure_ascii=False, indent=2) + "\n",
        encoding="utf-8",
    )


def main() -> None:
    lines = capture_top()
    entry = {
        "timestamp": datetime.now(timezone.utc).isoformat(),
        "lines": lines,
    }
    append_entry(entry)
    print("\n".join(lines))
    print(f"Appended top snapshot to {OUTPUT_PATH}", file=sys.stderr)


if __name__ == "__main__":
    main()

ポイントは 実行結果を stdout に出力していることです。後述する Workflow の「Run Predefined Script」ステップは、スクリプトの stdout をそのまま次工程（メール送信など）に渡せます。メールで結果を送りたい場合は、このように本文に使いたい内容を stdout に、ログ・デバッグ用のメッセージは stderr に分けておくと扱いやすくなります。

ローカルで動作確認しておきます。pythonコードを実行します。

cd ~/scripts/private_action
python3 check_top.py

jsonファイルを確認します

cat top-listed.json

[
  {
    "timestamp": "2026-08-15T00:04:30.265000+00:00",
    "lines": [
      "top - 09:04:30 up 124 days, 22:16,  9 users,  load average: 0.08, 0.13, 0.18",
      "Tasks: 242 total,   1 running, 241 sleeping,   0 stopped,   0 zombie",
      "%Cpu(s):  2.3 us,  0.0 sy,  0.0 ni, 97.7 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st ",
      "MiB Mem :   3909.7 total,    141.5 free,   2577.0 used,   1496.3 buff/cache     ",
      "MiB Swap:   2888.0 total,   1444.4 free,   1443.6 used.   1332.7 avail Mem ",
      "",
      "    PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND",
      "4003200 root      20   0 1955852  36672  13324 S   9.1   0.9  10:24.72 system-+",
      "4003206 dd-agent  20   0 2674044 152856  35616 S   9.1   3.8 276:06.26 agent",
      "      1 root      20   0   23216  10952   7256 S   0.0   0.3  44:36.14 systemd",
   中略
}]

アラートが発生したら、この stdout 出力をメールで送信できるようにします。

2. Application Key を作成する

Application Keys で新規作成し、スコープに on_prem_runner_write を付与します。

3. datadog.yaml に Private Action Runner の設定を追加する

/etc/datadog-agent/datadog.yaml に以下を追記します。

  • 「self_enroll」は、Datadog Agent で動かすときに有効化。Datadog Agent の中に Action Runner が組み込まれている。AgentがDatadogクラウド側に１回だけ登録する
  • 「actions_allowlist」は、Private Action Runnerが実行できる操作をホワイトリスト方式で制御するもの。「com.datadoghq.script.runPredefinedScript」は、Agentに登録済みのスクリプトだけ実行する許可
app_key: <手順2で作成した Application Key>
private_action_runner:
  enabled: true
  self_enroll: true
  actions_allowlist:
    - "com.datadoghq.script.runPredefinedScript"

4. Agent を再起動する

sudo systemctl restart datadog-agent

5. Runner が起動したか確認する

sudo tail -f /var/log/datadog/private-action-runner.log

Private action runner starting に続いて pollLoop の update successful が繰り返し出ていれば正常にポーリングされている。下記ログでは５秒毎にポーリングされている。

2026-08-29 22:53:49 JST | PRIV-ACTION | DEBUG | (pkg/config/remote/client/client.go:476 in pollLoop) | update successful: successful_first_run:true, consecutive failures:0
2026-08-29 22:53:54 JST | PRIV-ACTION | DEBUG | (pkg/config/remote/client/client.go:476 in pollLoop) | update successful: successful_first_run:true, consecutive failures:0
2026-08-29 22:53:59 JST | PRIV-ACTION | DEBUG | (pkg/config/remote/client/client.go:476 in pollLoop) | update successful: successful_first_run:true, consecutive failures:0

Datadog UI 側でも Actions > Action Catalog > Private Action Runners で対象の Runner が Active になっていることを確認します。

image.png

6. dd-agent に実行・書き込み権限を用意する

Private Action Runner は dd-agent ユーザーで動作します。そのため、スクリプトが出力ファイルへ書き込めるように、対象ディレクトリへの書き込み権限を dd-agent に与える必要があります。

対象ユーザーの既存グループ(ここでは kano)にそのまま dd-agent を追加する方法は、ホームディレクトリの権限設定次第でかえって権限が狭まることがあるため避けてください。代わりに、対象ディレクトリ専用のグループを作って権限を絞るのが安全です。

sudo groupadd ddrunner
sudo usermod -aG ddrunner dd-agent
sudo chgrp ddrunner ~/scripts/private_action
sudo chmod g+w ~/scripts/private_action
sudo chmod g+s ~/scripts/private_action   # 以後の新規ファイルもddrunner groupを継承させる

設定後は、dd-agent のユーザー権限で直接実行して権限が正しいことを確認しておきます。

sudo -u dd-agent python3 ~/scripts/private_action/check_top.py

7. スクリプトを Runner に登録する

Agent ベース版では、以下のパスに認証情報ファイルが自動生成されます。

/etc/datadog-agent/private-action-runner/script-config.yaml

中身はスタンドアロン版と同じ schemaId: script-credentials-v1 / runPredefinedScript: 形式で、サンプルに 任意の名称(例:check-top):で command: のように実行したいOSコマンドを追記します。

/etc/datadog-agent/private-action-runner/script-config.yaml
schemaId: script-credentials-v1
runPredefinedScript:
  check-top:
    command:
      - python3
      - /home/kano/scripts/private_action/check_top.py

所有者は dd-agent:dd-agent、パーミッションは 400 に設定したあと、Datadog agent を再起動します。

sudo chown dd-agent:dd-agent /etc/datadog-agent/private-action-runner/script-config.yaml
sudo chmod 400 /etc/datadog-agent/private-action-runner/script-config.yaml
sudo systemctl restart datadog-agent

Docker を使わない構成なので、command にはコンテナ内パスへの読み替えは不要で、ホスト上の実パスをそのまま書けます。これ以降、無人実行したい作業を増やしたい場合は、このファイルにコマンドを追記していくだけです。

8. Datadog 側で Connection を作成する

Actions > Action Catalog > Connections から作成します。

  1. [New Connection]
  2. インテグレーションで Script を選択
  3. Connection Name / Description を入力
  4. Private Action Runner ドロップダウンで対象の Runner を選択
  5. Path to file に /etc/datadog-agent/private-action-runner/script-config.yaml を指定
  6. Save & Test

［New Connection］で選択できるインテグレーション一覧の画面
image.png

［Script］インテグレーションを選ぶ
image.png

テストに成功すると、script-config.yaml に登録したスクリプト一覧(例：任意の名前[check-top]を含む)が読み込まれ、configurationValid: true と表示されます。

image.png

Connections に登録されます
[Automation] > [Action catalog] > [Connections]
image.png

9. Workflow を作成する

  1. Workflow Automation で新規 Workflow を作成
  2. トリガーに Schedule を追加(動作確認用。後で Monitor トリガーに差し替える)
  3. 次のステップとして Run Predefined Script アクションを追加
    • Connection: 手順8で作成した Connection
    • Script name: check-top
  4. 保存して Workflow を有効化する

［Workflow のステップ構成画面(Schedule → Run Predefined Script)］
下図は検証用途としてスケジュール起動にしています（土日11:00にスクリプトが自動実行される）
image.png

Schedule どおりの間隔で top-listed.json が更新されることを確認できたら、スクリプトと Runner 経由の無人実行が正しく動いている証拠です。

cat ~/scripts/private_action/top-listed.json

10. Monitor をトリガーにして、実行結果をメール通知する

動作確認ができたので、スケジュール起動ではなく、本来の目的である Monitor(アラート)トリガーに差し替えます。

Monitor を作成する

Monitors > [New Monitor] > Metric で、CPU使用率が30分連続で90%を超えたらアラートになるよう設定します。

avg(last_30m):100 - avg:system.cpu.idle{*} by {host} > 90

Notify メッセージ欄に、通知先メールへの @ メンションと、Add Workflow ボタンから手順9で作成した Workflow を追加します。Add Workflow を使うと、アラート発報時に Monitor 自身のメール通知と同時に Workflow が起動します。

CPU使用率が90%を超えました(30分平均)。Workflow を起動します。
@<通知先メールアドレス>

［Monitor の Notify 設定画面(Add Workflow ボタン周辺)］
メール本文の中に[add workflow]で @workflow-**** を追加しています
image.png

Workflow に Send Email ステップを追加する

Run Predefined Script(check-top)ステップの後ろに Send Email アクションを追加し、本文に check-top ステップの stdout 出力を差し込みます。

  • To: @<通知先メールアドレス>
  • Subject: [自動実行]TOPコマンド情報通知
  • Body: {{ Steps.Run_Predefined_Script.stdout }} (ステップ名はピッカーで表示される実際の名前を選びます)

［Send Email ステップを追加した設定画面］
image.png

11. 実行結果

CPU使用率アラートの発報をきっかけに、以下の2通のメールが届くことを確認しました。

  1. Monitor 自身の通知メール(アラート発生の第一報)
  2. Workflow の [Send Email] ステップによる詳細レポートメール(top の実行結果入り)

image.png

人が一切ログインすることなく、「CPU使用率アラート検知 → オンプレサーバーでの無人調査 → 結果のメール通知」という一連の定型作業が自動化できました。

まとめ

  • 「アラートを検知した定型手順書どおりに人が復旧作業をする」というスタイルから、「定型作業は自動化し、運用の力はレジリエンス強化に振り向ける」という方向に向かうための仕組みとして、Datadog の ［Private Action Runner］+［Workflow Automation］ が使える
  • Datadog Agentが動いているサーバーでは、Agent に組み込む形で Private Action Runner を有効化できる。そしてOSコマンド、Pythonスクリプトを実行できる
  • Private Action Runner はアウトバウンドポーリングのため、インバウンド許可は不要
  • script-config.yaml にコマンドを追加するだけで、無人実行したい定型作業を増やしていける
  • スクリプトの実行結果を stdout に出しておけば、Workflow の後続ステップ(メール送信など)にそのまま渡せる

参考リンク

2
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
2
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?