メニュー
Amazon CloudWatch ログ
ユーザーガイド

CloudWatch Logs エージェントのリファレンス

CloudWatch Logs エージェントには、ログデータを Amazon EC2 インスタンスから CloudWatch Logs に送信する自動化された方法が用意されています。エージェントは次のコンポーネントで構成されています。

  • ログデータを CloudWatch Logs にプッシュする AWS CLI プラグイン。

  • CloudWatch Logs にデータを送信する CloudWatch Logs aws logs push コマンドを実行するスクリプト (デーモン)。

  • デーモンが常に実行中であることを確認する cron ジョブ。

エージェント設定ファイル

CloudWatch Logs エージェント設定ファイルは、aws ログプッシュコマンドが必要とする情報を記述します。エージェント設定ファイルの [general] セクションは、すべてログストリームに適用する一般的な設定を定義します。[logstream] セクションは、リモートなログストリームにローカルファイルを送信するために必要な情報を定義します。複数の [logstream] セクションを持つことができますが、設定ファイル内にそれぞれ [logstream1]、[logstream2] などの一意の名前を持つ必要があります。ログファイルのデータの最初の行とともにある [logstream] 値は、ログファイルの ID を定義します。

Copy
[general] state_file = value logging_config_file = value use_gzip_http_content_encoding = [true | false] [logstream1] log_group_name = value log_stream_name = value datetime_format = value time_zone = [LOCAL|UTC] file = value file_fingerprint_lines = integer | integer-integer multi_line_start_pattern = regex | {datetime_format} initial_position = [start_of_file | end_of_file] encoding = [ascii|utf_8|..] buffer_duration = integer batch_count = integer batch_size = integer [logstream2] ...
state_file

状態ファイルをどこに保存するかを指定します。

logging_config_file

(オプション) エージェントのログ config ファイルの場所を指定します。エージェントのログ config ファイルの場所を指定しない場合は、/etc/awslogs/awslogs.conf のデフォルトファイルが使用されます。このファイルは、Python の設定ファイル形式(https://docs.python.org/2/library/logging.config.html#logging-config-fileformat)です。 以下の名前のロガーはカスタマイズできます。

Copy
cwlogs.push cwlogs.push.reader cwlogs.push.publisher cwlogs.push.event cwlogs.push.batch cwlogs.push.stream cwlogs.push.watcher

以下のサンプルは、デフォルトの値が INFO であるリーダーとパブリッシャーのレベルを WARNING に変更します。

Copy
[loggers] keys=root,cwlogs,reader,publisher [handlers] keys=consoleHandler [formatters] keys=simpleFormatter [logger_root] level=INFO handlers=consoleHandler [logger_cwlogs] level=INFO handlers=consoleHandler qualname=cwlogs.push propagate=0 [logger_reader] level=WARNING handlers=consoleHandler qualname=cwlogs.push.reader propagate=0 [logger_publisher] level=WARNING handlers=consoleHandler qualname=cwlogs.push.publisher propagate=0 [handler_consoleHandler] class=logging.StreamHandler level=INFO formatter=simpleFormatter args=(sys.stderr,) [formatter_simpleFormatter] format=%(asctime)s - %(name)s - %(levelname)s - %(process)d - %(threadName)s - %(message)s
use_gzip_http_content_encoding

true (デフォルト) に設定すると、CloudWatch Logs への圧縮されたペイロードの送信に対して、gzip による HTTP コンテンツのエンコードが有効になります。 これにより、CPU の使用率が減り、NetworkOut が少なくなり、Put のレイテンシーが短くなります。この機能を無効にするには、CloudWatch Logs エージェント設定ファイルの [general] セクションに use_gzip_http_content_encoding = false を追加してから、エージェントを再起動します。

注記

この設定は awscli-cwlogs バージョン 1.3.3 以降でのみ使用できます。

log_group_name

送信先ロググループを指定します。ロググループが存在しない場合には、自動的に作成されます。 ロググループの名前は 1~512 文字で指定します。ここで使えるのは、a~z、A~Z、0~9、"_" (アンダーバー)、"-" (ハイフン)、"/" (スラッシュ) および "." (ピリオド) です。

log_stream_name

送信先ログストリームを指定します。リテラル文字列、定義済み変数({instance_id}、{hostname}、{ip_address})、またはこれらの組み合わせを使用して、ログストリーム名を定義できます。ログストリームが存在しない場合には、自動的に作成されます。

datetime_format

ログからタイムスタンプを入手する方法を指定します。タイムスタンプはログイベントを取得し、メトリクスを生成するために使用されます。現在の時刻は、[datetime_format] が提供されていない場合に各ログイベントで使用されます。提供された [datetime_format] の値がそのログメッセージに対して無効の場合は、適切に解析されたタイムスタンプを持つ最後のログイベントのタイムスタンプが使用されます。 以前のログイベントが存在しない場合は、現在の時刻が使用されます。

一般的な datetime_format コードは次のとおりです。Python がサポートする datetime_format コード(datetime.strptime())も使用できます。タイムゾーンオフセット(%z)もサポートされています。ただし、Python 3.2 までは、コロン(:)のない [+-] HHMM はサポートされていません。詳細については、「strftime() および strptime() Behavior ()」を参照してください。

[%y]: ゼロ詰め 10 進数での年(世紀なし)です。00, 01, ..., 99

%Y: 10 進数での年(世紀あり)です。1970、1988、2001、2013

%b: ロケールの省略名称での月です。Jan、Feb ... Dec(en_US);

%B: ロケールの正式名称での月です。January、February...December(en_US);

%m: ゼロ詰め 10 進数での月です。01, 02, ..., 12

%d: ゼロ詰め 10 進数での日です。01, 02, ..., 31

%H: ゼロ詰め 10 進数での時(24 時間形式の時計)です。00, 01, ..., 23

%I: ゼロ詰め 10 進数での時(12 時間形式の時計)です。01, 02, ..., 12

%p: ロケールで AM または PM に相当するものです。

%M: ゼロ詰め 10 進数での分です。00, 01, ..., 59

%S: ゼロ詰め 10 進数での秒です。00, 01, ..., 59

%f: 左ゼロ詰め 10 進数でのマイクロ秒です。000000, ..., 999999

%z: +HHMM または -HHMM 形式の UTC オフセットです。+0000, -0400, +1030

形式の例:

Syslog: '%b %d %H:%M:%S', e.g. Jan 23 20:59:29

Log4j: '%d %b %Y %H:%M:%S', e.g. 24 Jan 2014 05:00:00

ISO8601: '%Y-%m-%dT%H:%M:%S%z', e.g. 2014-02-20T05:20:20+0000

time_zone

ログイベントのタイムスタンプのタイムゾーンを指定します。サポートされる 2 つの値は UTC および LOCAL です。デフォルトは LOCAL です。タイムゾーンが [datetime_format] に基づいて推定できない場合に使用されます。

file

CloudWatch Logs にプッシュするログファイルを指定します。ファイルは、特定のファイルまたは複数のファイルを指すことができます(/var/log/system.log* のようにワイルドカードを使用)。ファイルの変更時間に基づいて、最新のファイルのみが CloudWatch Logs にプッシュされます。access_log.2014-06-01-01 と access_log.2014-06-01-02 など同じ形式の一連のファイルを指定するにはワイルドカードの使用をお勧めします。ただし、access_log_80 と access_log_443 のように種類が異なる複数のファイルには使用しないでください。種類が異なる複数のファイルを指定するには、設定ファイルに別のストリームログのエントリを追加して、各種類のログファイルが異なるロググループに行くようにします。圧縮ファイルはサポートされていません。

file_fingerprint_lines

ファイルを識別するための行範囲を指定します。有効な値は「1」「2-5」のように単一の数字またはハイフンで区切られた 2 つの数字です。デフォルト値は「1」です。最初の行を使用してフィンガープリントを計算します。指定された行がすべて存在しない限り、フィンガープリント行は CloudWatch Logs に送信されません。

multi_line_start_pattern

ログメッセージの開始を識別するパターンを指定します。ログメッセージは、パターンに一致する 1 行と、それに続くパターンに一致しない行で構成されます。 有効な値は、正規表現または {datetime_format} です。{datetime_format} を使用する場合は、datetime_format オプションを指定する必要があります。デフォルト値は「^[^\s]'」です。よって、空白文字以外の文字で始まる行で前のログメッセージを終了し、新しいログメッセージを開始します。

initial_position

データの読み出しをどこから開始するかを指定します(start_of_file または end_of_file)。デフォルトは start_of_file です。そのログストリームに保持されている状態がない場合にのみ使用されます。

encoding

ファイルを正しく読み込むことができるように、ログファイルのエンコードを指定します。デフォルトは utf_8 です。Python の codecs.decode() がサポートするエンコードを使用できます。

警告

正しくないエンコードを指定すると、デコードできない文字がそのほかの文字に置き換えられるため、データ損失が生じる可能性があります。

一般的なエンコードを次に示します。

ascii, big5, big5hkscs, cp037, cp424, cp437, cp500, cp720, cp737, cp775, cp850, cp852, cp855, cp856, cp857, cp858, cp860, cp861, cp862, cp863, cp864, cp865, cp866, cp869, cp874, cp875, cp932, cp949, cp950, cp1006, cp1026, cp1140, cp1250, cp1251, cp1252, cp1253, cp1254, cp1255, cp1256, cp1257, cp1258, euc_jp, euc_jis_2004, euc_jisx0213, euc_kr, gb2312, gbk, gb18030, hz, iso2022_jp, iso2022_jp_1, iso2022_jp_2, iso2022_jp_2004, iso2022_jp_3, iso2022_jp_ext, iso2022_kr, latin_1, iso8859_2, iso8859_3, iso8859_4, iso8859_5, iso8859_6, iso8859_7, iso8859_8, iso8859_9, iso8859_10, iso8859_13, iso8859_14, iso8859_15, iso8859_16, johab, koi8_r, koi8_u, mac_cyrillic, mac_greek, mac_iceland, mac_latin2, mac_roman, mac_turkish, ptcp154, shift_jis, shift_jis_2004, shift_jisx0213, utf_32, utf_32_be, utf_32_le, utf_16, utf_16_be, utf_16_le, utf_7, utf_8, utf_8_sig

buffer_duration

ログイベントのバッチ期間を指定します。最小値は 5000ms で、デフォルト値は 5000ms です。

batch_count

バッチのログイベントの最大値を 10000 までの値で指定します。 デフォルト値は 1000 です。

batch_size

バッチのログイベントの最大値を 1048576 バイトまでのバイト値で指定します。 デフォルト値は 32768 バイトです。 このサイズは、UTF-8 のすべてのイベントメッセージの合計に各ログイベントにつき 26 バイトを加算して計算されます。

HTTP プロキシでの CloudWatch Logs エージェントの使用

HTTP プロキシで CloudWatch Logs エージェントを使用できます。

注記

HTTP プロキシは awslogs-agent-setup.py バージョン 1.3.8 以降でサポートされています。

HTTP プロキシで CloudWatch Logs エージェントを使用するには

  1. 次のいずれかを行ってください。

    1. CloudWatch Logs エージェントを新たにインストールする場合は、以下のコマンドを実行します。

      Copy
      curl https://s3.amazonaws.com/aws-cloudwatch/downloads/latest/awslogs-agent-setup.py -O
      Copy
      sudo python awslogs-agent-setup.py --region us-east-1 --http-proxy http://your/proxy --https-proxy http://your-proxy --no-proxy 169.254.169.254

      EC2 インスタンスで Amazon EC2 メタデータサービスへのアクセスを維持するには、[--no-proxy 169.254.169.254](推奨) を使用します。 詳細については、『Linux インスタンス用 Amazon EC2 ユーザーガイド』の「インスタンスメタデータとユーザーデータ」を参照してください。

    2. CloudWatch Logs エージェントが既にインストールされている場合は、/var/awslogs/etc/proxy.conf 編集し、プロキシを追加します。

      Copy
      HTTP_PROXY= HTTPS_PROXY= NO_PROXY=
  2. エージェントを再起動して、変更を有効にします。

    Copy
    sudo service awslogs restart

CloudWatch Logs エージェント設定ファイルのコンパートメント化

awslogs-agent-setup.py バージョン 1.3.8 以降と awscli-cwlogs 1.3.3 以降を使用している場合は、/var/awslogs/etc/config/ に追加の設定ファイルを作成することで、さまざまなコンポーネントのストリーム設定をそれぞれ個別にインポートできます。CloudWatch Logs エージェントが起動すると、これらの追加の設定ファイルにストリーム設定が追加されます。[general] セクションの設定プロパティはメインの設定ファイル (/var/awslogs/etc/awslogs.conf) で定義する必要があり、/var/awslogs/etc/config/ にある追加の設定ファイルで定義しても無視されます。

エージェントを再起動して、変更を有効にします。

Copy
sudo service awslogs restart

CloudWatch Logs エージェントのよくある質問

どのようなファイルローテーションがサポートされていますか。

次のファイルローテーション機能がサポートされています。

  • 既存のファイルを数字サフィックスをつけた名前に変更し、その後、元の名前の空のログファイルを作成し直します。 たとえば、/var/log/syslog.log が /var/log/syslog.log.1 という名前に変更されます。/var/log/syslog.log.1 が前回のローテーションにより既に存在する場合は、/var/log/syslog.log.2 という名前に変更されます。

  • 元のログファイルを、コピーを作成した後切り捨てます。たとえば、/var/log/syslog.log を /var/log/syslog.log.1 にコピーし、/var/log/syslog.log を切り捨てます。この場合、データを損失する恐れがあるため、このファイルローテーション機能の使用にはご注意ください。

  • 古いファイルと共通のパターンを持つ新しいファイルを作成します。たとえば /var/log/syslog.log.2014-01-01 をそのまま残し、/var/log/syslog.log.2014-01-02 を作成します。

ファイルのフィンガープリント (ソース ID) は、ログストリームキーとファイルのコンテンツの 1 行目をハッシュして計算されます。 この動作をオーバーライドするには、[file_fingerprint_lines] オプションを使用できます。ファイルのローテーションが発生した場合、新しいファイルには新しいコンテンツがあり古いファイルにはコンテンツの追加がないと思われるため、エージェントは古いファイルの読み込みが完了した後は、新しいファイルをプッシュします。

使用しているエージェントのバージョンを確認する方法

セットアップスクリプトから CloudWatch Logs エージェントをインストールした場合、[/var/awslogs/bin/awslogs-version.sh] で使用しているエージェントのバージョンを確認することができます。 エージェントのバージョンと主要な依存関係がプリントアウトされます。 yum から CloudWatch Logs エージェントをインストールした場合には、["yum info awslogs"] と ["yum info aws-cli-plugin-cloudwatch-logs"] で CloudWatch Logs エージェントとプラグインのバージョンを確認することができます。

ログのエントリは、どのようにログイベントに変換されるのですか。

ログイベントには 2 つのプロパティが含まれます。イベント発生時のタイムスタンプおよび生のログメッセージです。デフォルトでは、空白文字以外の文字で始まる行は、前のログメッセージがある場合はこれを終了して新しいログメッセージを開始します。この動作をオーバーライドするには、[multi_line_start_pattern] を使用します。パターンに一致する行が新しいログメッセージを開始します。パターンには正規表現または「{datetime_format}」を使用できます。 たとえば、それぞれのログメッセージの 1 行目が「2014-01-02T13:13:01Z」のようなタイムスタンプを持っている場合、[multi_line_start_pattern] は「\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z」と設定できます。 設定を簡略化するために、[datetime_format] オプションが指定されている場合は「{datetime_format}」変数を使用できます。 同じ例で、[datetime_format] が「%Y-%m-%dT%H:%M:%S%z」に設定されている場合、multi_line_start_pattern は「{datetime_format}」だけにできます。

現在の時刻は、[datetime_format] が提供されていない場合に各ログイベントで使用されます。提供された [datetime_format] がそのログメッセージに対して無効の場合は、適切に解析されたタイムスタンプを持つ最後のログイベントのタイムスタンプが使用されます。 前のログイベントがない場合は、現在の時刻が使用されます。ログイベントが現在の時刻または前のログイベントの時刻にフォールバックした場合は、警告メッセージが記録されます。

タイムスタンプはログイベントを取得し、メトリクスを生成するために使用されます。誤った形式を指定した場合、ログイベントが取得できなくなり誤ったメトリクスが生成されます。

ログイベントはどのようにバッチされていますか。

次の条件のいずれかが満たされる場合、バッチがフルになり発行されます。

  1. 最初のログイベントが追加されてから、[buffer_duration] の時間が経過した。

  2. 累積されたログイベントの [batch_size] 未満ですが、新しいログイベントを追加すると [batch_size] を超過します。

  3. ログイベント数は [batch_count] に達しました。

  4. バッチのログイベントは 24 時間以上になりませんが、新しいログイベントを追加すると 24 時間の制約を超過します。

ログエントリ、ログイベント、またはバッチがスキップまたは切り捨てられるのはどのような原因がありますか。

PutLogEvents オペレーションの制約に従って、次の問題によりログイベントまたはバッチがスキップされる場合があります。

注記

データがスキップされた場合、CloudWatch Logs エージェントはログに警告を書き込みます。

  1. ログイベントのサイズが 256 KB を超過した場合、ログイベントは完全にスキップされます。

  2. ログイベントのタイムスタンプが 2 時間以上未来の場合、ログイベントはスキップされます。

  3. ログイベントのタイムスタンプが 14 日以上過去の場合、ログイベントはスキップされます。

  4. ログイベントがロググループの保持期間よりも古い場合、バッチはすべてスキップされます。

  5. 単一の PutLogEvents リクエストでログイベントのバッチが 24 時間実行されている場合、PutLogEvents オペレーションは失敗します。

エージェントを停止させた場合、データ損失や重複が発生しますか。

状態ファイルが使用可能であり、最後に実行された時からファイルのローテーションが発生していなければ、発生しません。CloudWatch Logs エージェントは停止した場所から再開してログデータのプッシュを続行できます。

同一または異なるホストの異なるログデータを同じログストリームに指定できますか。

複数のログソースから単一のログストリームにデータを送信する設定はサポートされていません。

エージェントはどの API に呼び出しを作成しますか(またはどのアクションを IAM ポリシーに含める必要がありますか)。

CloudWatch Logs エージェントには、CreateLogGroupCreateLogStreamDescribeLogStreams、および PutLogEvents オペレーションが必要です。 最新のエージェントを使用している場合には、DescribeLogStreams は必要ありません。 以下の IAM ポリシーの例を参照してください。

Copy
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents", "logs:DescribeLogStreams" ], "Resource": [ "arn:aws:logs:*:*:*" ] } ] }
CloudWatch Logs エージェントに自動的にロググループまたはログストリームを作成させたくありません。 これらの作成および削除方法と、エージェントによる再作成を禁止する方法を教えてください。

IAM ポリシーで、エージェントを次のオペレーションのみに制限できます。DescribeLogStreamsPutLogEvents

トラブルシューティング時にはどのログを調べますか。

エージェントのインストールログは [/var/log/awslogs-agent-setup.log] に、エージェントログは [/var/log/awslogs.log] にあります。