[小ネタ] WindowsのCloudWatch Agentで設定の適用に失敗したときの挙動を確認してみた

こんにちは、林です。

Windows ServerのEC2にCloudWatch Agentを入れて、設定ファイルを amazon-cloudwatch-agent-ctl.ps1 の fetch-config で適用しました。ユーザーデータやSSM Run Commandでこの作業を自動化する場合、設定の適用に失敗したことをどう検知するかを決めておく必要があります。

設定が適用されたかどうかを status の出力で判断できるのか気になったので、失敗のパターンごとに挙動を確認してみました。

検証環境

設定の適用には以下のコマンドを使います。

& 'C:\Program Files\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1' `
  -a fetch-config -m ec2 `
  -c file:'C:\ProgramData\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent.json' -s

検証パターン

設定ファイルの状態を変えて、4パターンで fetch-config を実行しました。
参考として、fetch-config を実行せずに amazon-cloudwatch-agent-ctl.ps1 -m ec2 -a start でエージェントを起動した場合も確認しています。

各パターンで確認した項目は以下の4つです。

• 終了コード（$LASTEXITCODE）
• PowerShellの例外
• status の出力
• Configs フォルダの内容

amazon-cloudwatch-agent-ctl.ps1 では、設定ファイルの検証はエージェント本体の実行ファイル（amazon-cloudwatch-agent.exe）が行い、サービスの起動はスクリプト内の処理で行われます。

設定ファイルの検証エラーは実行ファイルの終了コード（$LASTEXITCODE）に、サービスの起動失敗はPowerShellの例外として出力されます。

そのため、終了コードと例外の両方を確認項目にしています。

検証結果

結果から3つのことが分かりました。

status は適用に失敗しても正常に見える

設定ファイルなしで -a start すると、以下の出力とともに既定の設定でエージェントが起動されました。

amazon-cloudwatch-agent is not configured. Applying amazon-cloudwatch-agent default configuration.

このときの status は、正しい設定ファイルを適用したときと同じでした。

{
  "status": "running",
  "starttime": "2026-09-24T05:19:38",
  "configstatus": "configured",
  "version": "1.300073.0b1828"
}

status が running、configstatus が configured でも、配置した設定ファイルが適用されているとは限りません。

失敗の判定には終了コードと例外の両方が必要

終了コードで失敗と判定できたのは、設定ファイルなし（-1）と設定値の型エラー（1）でした。
JSON構文エラーは 0 のままでした。

例外で失敗と判定できたのは、設定ファイルなしとJSON構文エラーでした。
設定値の型エラーでは例外が出ませんでした。

スクリプトで失敗を判定するには、終了コードと例外の両方を確認する必要があります。

JSON構文エラーは fetch-config の検証を通るが、サービスは起動しない

JSON構文エラーは、fetch-config の検証でエラーになりません。

検証を行う config-translator（amazon-cloudwatch-agent.exe のサブコマンド）は、JSONを読めなかった設定ファイルを「設定ファイルなし」として扱い、既定の設定で検証を通します。

unable to scan config dir C:\ProgramData\Amazon\AmazonCloudWatchAgent\Configs with error: unable to parse json, error: invalid character '}' looking for beginning of object key string
No json config files found, use the default one
I! Valid Json input schema.
Configuration validation first phase succeeded

このため終了コードは 0 になり、エージェントが読み込む設定ファイル（amazon-cloudwatch-agent.toml）には既定の設定が書かれました。

JSONが不正なときに既定の設定が使われる挙動については、GitHubのIssueにLinuxでの報告がありました。

https://github.com/aws/amazon-cloudwatch-agent/issues/966

一方で、サービスの起動時には、サービスとして登録されている start-amazon-cloudwatch-agent.exe が Configs フォルダの設定ファイルをもう一度検証します。こちらの検証では同じJSONの不正でエラーになり、サービスは起動されませんでした。

unable to scan config dir C:\ProgramData\Amazon\AmazonCloudWatchAgent\Configs with error: unable to parse json, error: invalid character '}' looking for beginning of object key string
E! config-translator process exited with non-zero status: 99

fetch-config で例外が出たのは、この起動失敗によるものです。検証は成功として通り、その後のサービス起動で失敗します。

適用結果の判定方法

C:\ProgramData\Amazon\AmazonCloudWatchAgent\Configs フォルダのファイル名で判定します。

Get-ChildItem 'C:\ProgramData\Amazon\AmazonCloudWatchAgent\Configs'

ただし、JSON構文エラーの場合は、不正な設定ファイルがそのまま file_amazon-cloudwatch-agent.json として取り込まれるため、ファイル名では見分けられません。
このパターンでは、fetch-config の例外と、status が stopped であることで判定します。

スクリプトに組み込む場合は、例外・終了コード・Configs フォルダの3段で判定します。

$ctl = 'C:\Program Files\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1'
$cfg = 'C:\ProgramData\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent.json'

# 1. 例外（設定ファイルなし、JSON構文エラー）
try {
  & $ctl -a fetch-config -m ec2 -c "file:$cfg" -s
} catch {
  throw "fetch-config failed: $($_.Exception.Message)"
}

# 2. 終了コード（設定値の型エラー）
if ($LASTEXITCODE -ne 0) {
  throw "fetch-config failed with exit code $LASTEXITCODE"
}

# 3. Configs フォルダ（既定の設定で動いていないか）
$applied = Get-ChildItem 'C:\ProgramData\Amazon\AmazonCloudWatchAgent\Configs' -Name
if ($applied -notcontains 'file_amazon-cloudwatch-agent.json') {
  throw "config not applied. Configs: $($applied -join ', ')"
}

この判定をユーザーデータやSSM Run Commandのスクリプトに入れておくと、適用に失敗したときにスクリプトがエラーで終了するため、実行結果で失敗が分かります。

まとめ

WindowsのCloudWatch Agentで、設定の適用に失敗したときの挙動を確認しました。

• status は、既定の設定で動いていても、正しい設定ファイルを適用したときと同じ running / configured を返す
• 失敗の種類によって、終了コードは -1 / 0 / 1 と変わり、例外が出る場合と出ない場合がある
• JSON構文エラーは fetch-config の検証を通り、サービス起動時の再検証で失敗する
• Configs フォルダのファイル名で、既定の設定（default）か、配置した設定ファイル（file_amazon-cloudwatch-agent.json）かを見分けられる

status だけでは設定の適用を確認できないので、自動化するときは例外・終了コード・Configs フォルダの3段で判定する必要があります。

この記事がどなたかの参考になれば幸いです。最後までご覧いただきありがとうございました！

参考

https://docs.aws.amazon.com/ja_jp/AmazonCloudWatch/latest/monitoring/start-CloudWatch-Agent-EC2-commandline-fleet.html

https://docs.aws.amazon.com/ja_jp/AmazonCloudWatch/latest/monitoring/troubleshooting-CloudWatch-Agent.html

https://github.com/aws/amazon-cloudwatch-agent/issues/966

https://github.com/aws/amazon-cloudwatch-agent