AWS Systems Manager Agent のログ設定を変更してみた

2020.08.04

園部です。

想定通りに動作しない時や障害発生時のトラブルシューティングでは、ログを確認することは有効な手立ての一つです。 AWS Systems Manager (以降 SSM )におけるトラブルシューティングでも S3やCloudWatchLogsなどに出力される実行結果とともに SSM Agent に出力されるログも有効です。

SSM エージェント は、実行、コマンド、スケジュールされたアクション、エラー、ヘルスステータスを各インスタンスのログファイルに書き込みます。

引用元: SSM エージェント ログを表示する

ただし単一なファイルに大量の情報を出力しすぎると、返ってノイズとなり必要な情報にたどり着くまでに時間を要してしまう場合があります。そのためログをレベルで分けて出力内容や出力先などをコントロールする方法があります。 今回は、SSM Agent ログで設定を変更して実施してみます。

やってみた

ログについて

設定を変更する前に SSM Agent ログについておさらいしておきます。 SSM Agent ログは通常以下に出力されます。

Linux

  • /var/log/amazon/ssm/amazon-ssm-agent.log
  • /var/log/amazon/ssm/errors.log

Windows

  • %PROGRAMDATA%\Amazon\SSM\Logs\amazon-ssm-agent.log
  • %PROGRAMDATA%\Amazon\SSM\Logs\errors.log

実際にはこのような内容が出力されます。(Linux 環境) 割と量が多く頻繁に出力されている印象をお持ちの方が多いのではないかと思います。

# tail /var/log/amazon/ssm/amazon-ssm-agent.log
2020-08-03 13:02:15 INFO [ssm-session-worker] [sonobe-017ee7428a25ba935] [DataBackend] [pluginName=Standard_Stream] Opening websocket connection to:wss://ssmmessages.ap-northeast-1.amazonaws.com/v1/data-channel/cm-sonobe.osamu-017ee7428a25ba935?role=publish_subscribe
2020-08-03 13:02:15 INFO [ssm-session-worker] [sonobe-017ee7428a25ba935] [DataBackend] [pluginName=Standard_Stream] Successfully opened websocket connection to: wss://ssmmessages.ap-northeast-1.amazonaws.com/v1/data-channel/cm-sonobe.osamu-017ee7428a25ba935?role=publish_subscribe
2020-08-03 13:02:15 INFO [ssm-session-worker] [sonobe-017ee7428a25ba935] [DataBackend] [pluginName=Standard_Stream] Skipping handshake.
2020-08-03 13:02:15 INFO [ssm-session-worker] [sonobe-017ee7428a25ba935] [DataBackend] [pluginName=Standard_Stream] Instance region is ap-northeast-1
2020-08-03 13:02:15 INFO [ssm-session-worker] [sonobe-017ee7428a25ba935] [DataBackend] [pluginName=Standard_Stream] Getting region information aboutbucket ap-northeast-1
2020-08-03 13:02:15 INFO [ssm-session-worker] [sonobe-017ee7428a25ba935] [DataBackend] [pluginName=Standard_Stream] Starting pty
2020-08-03 13:02:15 INFO [ssm-session-worker] [sonobe-017ee7428a25ba935] [DataBackend] [pluginName=Standard_Stream] Successfully created ssm-user
2020-08-03 13:02:15 INFO [ssm-session-worker] [sonobe-017ee7428a25ba935] [DataBackend] [pluginName=Standard_Stream] Successfully created file /etc/sudoers.d/ssm-agent-users
2020-08-03 13:02:15 INFO [ssm-session-worker] [sonobe-017ee7428a25ba935] [DataBackend] [pluginName=Standard_Stream] Successfully changed mode of /etc/sudoers.d/ssm-agent-users to 288
2020-08-03 13:02:15 INFO [ssm-session-worker] [sonobe-017ee7428a25ba935] [DataBackend] [pluginName=Standard_Stream] Plugin Standard_Stream started
# tail /var/log/amazon/ssm/errors.log
2020-08-03 13:01:11 ERROR [getApplicationData @ dataProvider_unix.go.268] [ssm-document-worker] [286373dd-0186-4b63-ba53-6addff0a111d.2020-08-03T13-01-11.042Z] [DataBackend] [pluginName=aws:softwareInventory] [aws:softwareInventory] Failed to execute command : dpkg-query [-W -f={"Name":"<start374a2eeb>${Package}<end03651326>","Publisher":"<start374a2eeb>${Maintainer}<end03651326>","Version":"<start374a2eeb>${Version}<end03651326>","ApplicationType":"<start374a2eeb>${Section}<end03651326>","Architecture":"<start374a2eeb>${Architecture}<end03651326>","Url":"<start374a2eeb>${Homepage}<end03651326>","Summary":"<start374a2eeb>${Description}<end03651326>","PackageId":"<start374a2eeb>${Package}_${Version}_${Architecture}.deb<end03651326>"},] with error - exec: "dpkg-query": executable file not found in $PATH
2020-08-03 13:01:11 ERROR [getFiles @ dataProvider.go.165] [ssm-document-worker] [286373dd-0186-4b63-ba53-6addff0a111d.2020-08-03T13-01-11.042Z] [DataBackend] [pluginName=aws:softwareInventory] [aws:softwareInventory] Path /root/tools does not exist!

ログ設定

では、さっそくログ設定を変更していきます。

SSM Agent ログの設定は /etc/amazon/ssm 配下にある seelog.xml.template で記述がされています。ログフォーマットや出力先、ログレベルを定義されています。

各種詳細については seelog Wiki に記載がされています。

# cat /etc/amazon/ssm/seelog.xml.template
<!--amazon-ssm-agent uses seelog logging -->
<!--Seelog has github wiki pages, which contain detailed how-tos references: https://github.com/cihub/seelog/wiki -->
<!--Seelog examples can be found here: https://github.com/cihub/seelog-examples -->
<seelog type="adaptive" mininterval="2000000" maxinterval="100000000" critmsgcount="500" minlevel="info">
    <exceptions>
        <exception filepattern="test*" minlevel="error"/>
    </exceptions>
    <outputs formatid="fmtinfo">
        <console formatid="fmtinfo"/>
        <rollingfile type="size" filename="/var/log/amazon/ssm/amazon-ssm-agent.log" maxsize="30000000" maxrolls="5"/>
        <filter levels="error,critical" formatid="fmterror">
            <rollingfile type="size" filename="/var/log/amazon/ssm/errors.log" maxsize="10000000" maxrolls="5"/>
        </filter>
    </outputs>
    <formats>
        <format id="fmterror" format="%Date %Time %LEVEL [%FuncShort @ %File.%Line] %Msg%n"/>
        <format id="fmtdebug" format="%Date %Time %LEVEL [%FuncShort @ %File.%Line] %Msg%n"/>
        <format id="fmtinfo" format="%Date %Time %LEVEL %Msg%n"/>
    </formats>
</seelog>

今回はログレベルを変更してみます。
具体的には以下の7つのレベルが利用可能です。 各種詳細については Log levels に記載がされています。

  • Trace
  • Debug
  • Info
  • Warn
  • Error
  • Critical
  • Off

上記の例(デフォルト)では Info レベルからログに出力されています。 そのため amazon-ssm-agent.log への出力量が多く感じるのかもしれません。 実際のトラブルシューティングの現場では いわゆる Debug レベルに変更し、より詳細なログを収集するケースが多いかと思います。ドキュメント内でも Debug へ設定変更する例が紹介されています。

SSM エージェント ログを表示する

Debug レベルへ変更

ログレベルを変更するには 設定ファイルを変更する必要があります。

/etc/amazon/ssm 配下にある seelog.xml.template をコピーして任意の値に修正し SSM Agent を再起動することで設定を反映されます。 変更箇所は差分で表示しています。冒頭の minlevel を変更するだけで Debug レベルへ変更となりますが、ログフォーマットも Debug 用のものを利用してみます。

# cp /etc/amazon/ssm/seelog.xml.template /etc/amazon/ssm/seelog.xml
# vi /etc/amazon/ssm/seelog.xml

# diff /etc/amazon/ssm/seelog.xml.template /etc/amazon/ssm/seelog.xml
4c4
< <seelog type="adaptive" mininterval="2000000" maxinterval="100000000" critmsgcount="500" minlevel="info">
---
> <seelog type="adaptive" mininterval="2000000" maxinterval="100000000" critmsgcount="500" minlevel="debug">
8,9c8,9
<     <outputs formatid="fmtinfo">
<         <console formatid="fmtinfo"/>
---
>     <outputs formatid="fmtdebug">
>         <console formatid="fmtdebug"/>

# amazon-ssm-agent restart

これで反映されました。では実際にログを見ていきます。 特に何も実行していないので効果がわかりづらいですが DEBUG レベルのログが出力されている点とフォーマットが変更されていることが確認できます。

# tail /var/log/amazon/ssm/amazon-ssm-agent.log
2020-08-04 02:51:38 INFO [func1 @ backend.go.179] [ssm-session-worker] [sonobe-0f30b62f1adab01f5] [DataBackend] stopping ipc worker...
2020-08-04 02:51:38 DEBUG [watch @ filechannel.go.288] [ssm-session-worker] [sonobe-0f30b62f1adab01f5] received event: "/var/lib/amazon/ssm/i-02d8d9afef378e47c/channels/sonobe-0f30b62f1adab01f5/worker-20200804025116-000": CREATE
2020-08-04 02:51:38 DEBUG [watch @ filechannel.go.288] [ssm-session-worker] [sonobe-0f30b62f1adab01f5] received event: "/var/lib/amazon/ssm/i-02d8d9afef378e47c/channels/sonobe-0f30b62f1adab01f5/worker-20200804025116-001": CREATE
2020-08-04 02:51:38 INFO [Messaging @ messaging.go.108] [ssm-session-worker] [sonobe-0f30b62f1adab01f5] requested shutdown, prepare to stop messaging
2020-08-04 02:51:38 INFO [Close @ filechannel.go.166] [ssm-session-worker] [sonobe-0f30b62f1adab01f5] channel /var/lib/amazon/ssm/i-02d8d9afef378e47c/channels/sonobe-0f30b62f1adab01f5 requested close
2020-08-04 02:51:38 DEBUG [consumeAll @ filechannel.go.203] [ssm-session-worker] [sonobe-0f30b62f1adab01f5] consuming all the messages under: /var/lib/amazon/ssm/i-02d8d9afef378e47c/channels/sonobe-0f30b62f1adab01f5
2020-08-04 02:51:38 WARN [consumeAll @ filechannel.go.210] [ssm-session-worker] [sonobe-0f30b62f1adab01f5] IPC file not readable: tmp
2020-08-04 02:51:38 INFO [Messaging @ messaging.go.140] [ssm-session-worker] [sonobe-0f30b62f1adab01f5] ipc channel closed, stop messaging worker
2020-08-04 02:51:38 INFO [main @ main.go.89] [ssm-session-worker] [sonobe-0f30b62f1adab01f5] Session worker closed
2020-08-04 02:51:53 DEBUG [ssm-session-worker] [sonobe-0d976144e557c1b1a] [DataBackend] [pluginName=Standard_Stream] Payload length will be adjusted: %!(EXTRA uint32=0)

おまけに

今回、ログ設定の変更で修正したファイル(seelog.xml)と同じディレクトリにある amazon-ssm-agent.json.template を利用することで SSM Agent の設定を変更することが可能です。 ご興味のある方は、詳細が以下の Github で公開されているので、ご一読ください。

Runtime Configuration

さいごに

SSM Agent のログレベルやフォーマットが修正出来るということを頭の片隅にしまっておけば、いざという時の手札が増えるのではないでしょうか。また今回は実施していませんが、出力先やローテーション条件を変更することで自社のポリシーに揃えるといったことが必要な時に有益ではないかと思います。