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

CloudWatch Logs サブスクリプションフィルタの使用

Kinesis、Lambda、または Kinesis Firehose では、サブスクリプションフィルタを使用できます。

例 1: Kinesis のサブスクリプションフィルタ

次の例では、サブスクリプションフィルタを、AWS CloudTrail イベントを含むロググループと関連付け、"Root" AWS 認証情報により実行されたすべてのログアクティビティが "RootAccess" と呼ばれる Kinesis ストリームに配信されます。AWS CloudTrail イベントを CloudWatch Logs に送信する方法の詳細については、『AWS CloudTrail User Guide』の「CloudTrail イベントの CloudWatch Logs への送信」を参照してください。

Kinesis のサブスクリプションフィルタを作成するには

  1. 次のコマンドを使用して送信先 Kinesis ストリームを作成します。

    Copy
    $ C:\> aws kinesis create-stream --stream-name "RootAccess" --shard-count 1
  2. Kinesis ストリームが [Active] になるまで待ちます (これには 1 ~ 2 分かかる可能性があります)。次の Kinesis aws kinesis describe-stream コマンドを使用して、StreamDescription.StreamStatus プロパティをチェックできます。さらに、後のステップで必要になるため StreamDescription.StreamARN 値を書き留めます。

    Copy
    aws kinesis describe-stream --stream-name "RootAccess"

    出力例を次に示します。

    Copy
    { "StreamDescription": { "StreamStatus": "ACTIVE", "StreamName": "RootAccess", "StreamARN": "arn:aws:kinesis:us-east-1:123456789012:stream/RootAccess", "Shards": [ { "ShardId": "shardId-000000000000", "HashKeyRange": { "EndingHashKey": "340282366920938463463374607431768211455", "StartingHashKey": "0" }, "SequenceNumberRange": { "StartingSequenceNumber": "49551135218688818456679503831981458784591352702181572610" } } ] } }
  3. Kinesis ストリームにデータを置く権限を CloudWatch Logs に付与する IAM ロールを作成します。まず、ファイル (~/TrustPolicyForCWL.json など) で信頼ポリシーを作成する必要があります。

    Copy
    { "Statement": { "Effect": "Allow", "Principal": { "Service": "logs.us-east-1.amazonaws.com" }, "Action": "sts:AssumeRole" } }
  4. create-role コマンドを使用し、信頼ポリシーファイルを指定して IAM ロールを作成します。後のステップで必要になるため、返された Role.Arn 値も書き留めます。

    Copy
    aws iam create-role --role-name CWLtoKinesisRole --assume-role-policy-document file://~/TrustPolicyForCWL.json
    Copy
    { "Role": { "AssumeRolePolicyDocument": { "Statement": { "Action": "sts:AssumeRole", "Effect": "Allow", "Principal": { "Service": "logs.us-east-1.amazonaws.com" } } }, "RoleId": "AAOIIAH450GAB4HC5F431", "CreateDate": "2015-05-29T13:46:29.431Z", "RoleName": "CWLtoKinesisRole", "Path": "/", "Arn": "arn:aws:iam::123456789012:role/CWLtoKinesisRole" } }
  5. 権限ポリシーを作成し、CloudWatch Logs がアカウントで実行できるアクションを定義します。まず、ファイル (~/PermissionsForCWL.json など) で権限ポリシーを作成します。

    Copy
    { "Statement": [ { "Effect": "Allow", "Action": "kinesis:PutRecord", "Resource": "arn:aws:kinesis:us-east-1:123456789012:stream/RootAccess" }, { "Effect": "Allow", "Action": "iam:PassRole", "Resource": "arn:aws:iam::123456789012:role/CWLtoKinesisRole" } ] }
  6. 次の put-role-policy コマンドを使用して、アクセス許可ポリシーをロールに関連付けます。

    Copy
    aws iam put-role-policy --role-name CWLtoKinesisRole --policy-name Permissions-Policy-For-CWL --policy-document file://~/PermissionsForCWL.json
  7. Kinesis ストリームが [Active] 状態になり、IAM ロールを作成したら、CloudWatch Logs サブスクリプションフィルタを作成できます。サブスクリプションフィルタにより、選択されたロググループから Kinesis ストリームへのリアルタイムログデータの流れがすぐに開始されます。

    Copy
    aws logs put-subscription-filter \ --log-group-name "CloudTrail" \ --filter-name "RootAccess" \ --filter-pattern "{$.userIdentity.type = Root}" \ --destination-arn "arn:aws:kinesis:us-east-1:123456789012:stream/RootAccess" \ --role-arn "arn:aws:iam::123456789012:role/CWLtoKinesisRole"
  8. サブスクリプションフィルタを設定したら、CloudWatch Logs によりフィルタパターンに一致するすべての受信ログイベントが Kinesis ストリームに転送されます。これが起きていることは、Kinesis シャードイテレータを取得し、Kinesis get-records コマンドを使用していくつかの Kinesis レコードを取得することで確認できます。

    Copy
    aws kinesis get-shard-iterator --stream-name RootAccess --shard-id shardId-000000000000 --shard-iterator-type TRIM_HORIZON
    Copy
    { "ShardIterator": "AAAAAAAAAAFGU/kLvNggvndHq2UIFOw5PZc6F01s3e3afsSscRM70JSbjIefg2ub07nk1y6CDxYR1UoGHJNP4m4NFUetzfL+wev+e2P4djJg4L9wmXKvQYoE+rMUiFq+p4Cn3IgvqOb5dRA0yybNdRcdzvnC35KQANoHzzahKdRGb9v4scv+3vaq+f+OIK8zM5My8ID+g6rMo7UKWeI4+IWiK2OSh0uP" }
    Copy
    aws kinesis get-records --limit 10 --shard-iterator "AAAAAAAAAAFGU/kLvNggvndHq2UIFOw5PZc6F01s3e3afsSscRM70JSbjIefg2ub07nk1y6CDxYR1UoGHJNP4m4NFUetzfL+wev+e2P4djJg4L9wmXKvQYoE+rMUiFq+p4Cn3IgvqOb5dRA0yybNdRcdzvnC35KQANoHzzahKdRGb9v4scv+3vaq+f+OIK8zM5My8ID+g6rMo7UKWeI4+IWiK2OSh0uP"

    Kinesis がデータを返し始めるまで、この呼び出しを数回行う必要があるかもしれない点に注意してください。

    レコードの配列を含むレスポンスが表示されます。Kinesis レコードの Data 属性は、Base64 でエンコードされており、gzip 形式で圧縮されています。raw データは、コマンドラインから次の UNIX コマンドを使用して調べることができます。

    Copy
    echo -n "<Content of Data>" | base64 -d | zcat

    Base64 でデコードおよび圧縮されたデータは、次の構造を使用して JSON としてフォーマットされます。

    Copy
    { "owner": "123456789012", "logGroup": "CloudTrail", "logStream": "123456789012_CloudTrail_us-east-1", "subscriptionFilters": [ "RootAccess" ], "messageType": "DATA_MESSAGE", "logEvents": [ { "id": "31953106606966983378809025079804211143289615424298221568", "timestamp": 1432826855000, "message": "{\"eventVersion\":\"1.03\",\"userIdentity\":{\"type\":\"Root\"}" }, { "id": "31953106606966983378809025079804211143289615424298221569", "timestamp": 1432826855000, "message": "{\"eventVersion\":\"1.03\",\"userIdentity\":{\"type\":\"Root\"}" }, { "id": "31953106606966983378809025079804211143289615424298221570", "timestamp": 1432826855000, "message": "{\"eventVersion\":\"1.03\",\"userIdentity\":{\"type\":\"Root\"}" } ] }

    上のデータ構造の主な要素は次のとおりです。

    owner

    発行元ログデータの AWS アカウント ID。

    logGroup

    発行元ログデータのロググループ名。

    logStream

    発行元ログデータのログストリーム名。

    subscriptionFilters

    発行元ログデータと一致したサブスクリプションフィルタ名のリスト。

    messageType

    データメッセージは、"DATA_MESSAGE" 型を使用します。CloudWatch Logs は、主に送信先が到達可能であるかどうかをチェックするために、"CONTROL_MESSAGE" 型の Kinesis レコードを発行することがあります。

    logEvents

    ログイベントレコードの配列として表される実際のログデータ。"id" プロパティは、各ログイベントの一意識別子です。

例 2: AWS Lambda のサブスクリプションフィルタ

この例では、CloudWatch Logs サブスクリプションのフィルタを作成して、ログデータを AWS Lambda 関数に送信します。

Lambda のサブスクリプションフィルタを作成するには

  1. AWS Lambda 関数を作成します。

    Lambda 実行ロールをセットアップ済みであることを確認します。詳細については、AWS Lambda Developer Guide の「2.2: Create an IAM Role (execution role)」を参照してください。

  2. テキストエディターを開き、以下の内容で helloWorld.js という名前のファイルを作成します。

    Copy
    var zlib = require('zlib'); exports.handler = function(input, context) { var payload = new Buffer(input.awslogs.data, 'base64'); zlib.gunzip(payload, function(e, result) { if (e) { context.fail(e); } else { result = JSON.parse(result.toString('ascii')); console.log("Event Data:", JSON.stringify(result, null, 2)); context.succeed(); } }); };
  3. helloWorld.js ファイルを圧縮して helloWorld.zip という名前で保存します。

  4. 次のコマンドを使用します。ロールは、最初のステップで設定した Lambda 実行ロールです。

    Copy
    aws lambda create-function \ --function-name helloworld \ --zip-file file://file-path/helloWorld.zip \ --role lambda-execution-role-arn \ --handler helloWorld.handler \ --runtime nodejs4.3
  5. CloudWatch Logs に、関数を実行するためのアクセス権限を付与します。次のコマンドを使用します。プレースホルダーは自身のアカウントに置き換え、プレースホルダーロググループは処理するロググループに置き換えます。

    Copy
    aws lambda add-permission \ --function-name "helloworld" \ --statement-id "helloworld" \ --principal "logs.us-east-1.amazonaws.com" \ --action "lambda:InvokeFunction" \ --source-arn "arn:aws:logs:us-east-1:123456789123:log-group:TestLambda:*" \ --source-account "123456789012"
  6. 次のコマンドを使用してサブスクリプションフィルタを作成します。プレースホルダーアカウントは自身のアカウントに置き換え、プレースホルダーロググループは処理するロググループに置き換えます。

    Copy
    aws logs put-subscription-filter \ --log-group-name myLogGroup \ --filter-name demo \ --filter-pattern "" \ --destination-arn arn:aws:lambda:us-east-1:123456789123:function:helloworld
  7. (オプション) サンプルのログイベントを使用してテストします。コマンドプロンプトで、次のコマンドを実行します。これにより、サブスクライブしたストリームに単純なログメッセージを送信されます。

    Lambda 関数の出力を確認するには、Lambda 関数に移動して、/aws/lambda/helloworld にある出力を参照します。

    Copy
    aws logs put-log-events --log-group-name myLogGroup --log-stream-name stream1 --log-events "[{\"timestamp\":<CURRENT TIMESTAMP MILLIS> , \"message\": \"Simple Lambda Test\"}]"

    Lambda の配列を含むレスポンスが表示されます。Lambda レコードの [Data] 属性は、Base64 でエンコードされており、gzip 形式で圧縮されています。Lambda が受け取る実際のペイロードは、{ "awslogs": {"data": "BASE64ENCODED_GZIP_COMPRESSED_DATA"} } の形式になります。raw データは、コマンドラインから次の UNIX コマンドを使用して調べることができます。

    Copy
    echo -n "<BASE64ENCODED_GZIP_COMPRESSED_DATA>" | base64 -d | zcat

    Base64 でデコードおよび圧縮されたデータは、次の構造を使用して JSON としてフォーマットされます。

    Copy
    { "owner": "123456789012", "logGroup": "CloudTrail", "logStream": "123456789012_CloudTrail_us-east-1", "subscriptionFilters": [ "RootAccess" ], "messageType": "DATA_MESSAGE", "logEvents": [ { "id": "31953106606966983378809025079804211143289615424298221568", "timestamp": 1432826855000, "message": "{\"eventVersion\":\"1.03\",\"userIdentity\":{\"type\":\"Root\"}" }, { "id": "31953106606966983378809025079804211143289615424298221569", "timestamp": 1432826855000, "message": "{\"eventVersion\":\"1.03\",\"userIdentity\":{\"type\":\"Root\"}" }, { "id": "31953106606966983378809025079804211143289615424298221570", "timestamp": 1432826855000, "message": "{\"eventVersion\":\"1.03\",\"userIdentity\":{\"type\":\"Root\"}" } ] }

    上のデータ構造の主な要素は次のとおりです。

    owner

    発行元ログデータの AWS アカウント ID。

    logGroup

    発行元ログデータのロググループ名。

    logStream

    発行元ログデータのログストリーム名。

    subscriptionFilters

    発行元ログデータと一致したサブスクリプションフィルタ名のリスト。

    messageType

    データメッセージは、"DATA_MESSAGE" 型を使用します。CloudWatch Logs は、主に送信先が到達可能であるかどうかをチェックするために、"CONTROL_MESSAGE" 型の Lambda レコードを発行することがあります。

    logEvents

    ログイベントレコードの配列として表される実際のログデータ。"id" プロパティは、各ログイベントの一意識別子です。

例 3: Amazon Kinesis Firehose のサブスクリプションフィルタ

この例では、CloudWatch Logs サブスクリプションを作成して、Amazon Kinesis Firehose 送信システムに定義されたフィルタに一致する受信ログイベントを送信します。CloudWatch Logs から Amazon Kinesis Firehose に送信されたデータは、すでに gzip レベル 6 圧縮で圧縮されているため、Kinesis Firehose 送信ストリーム内で圧縮を使用する必要はありません。

Kinesis Firehose のサブスクリプションフィルタを作成するには

  1. Amazon Simple Storage Service (Amazon S3) バケットの作成。CloudWatch Logs 専用に作成したバケットを使用することをお勧めします。ただし、既存のバケットを使用する場合は、ステップ 2 に進みます。

    次のコマンドを実行します。プレースホルダーリージョンは、使用するリージョンに置き換えます。

    Copy
    aws s3api create-bucket --bucket my-bucket --create-bucket-configuration LocationConstraint=us-east-1

    出力例を次に示します。

    Copy
    { "Location": "/my-bucket" }
  2. IAM ロールを作成して、Amazon Kinesis Firehose に Amazon S3 バケットにデータを置く権限を付与します。

    詳細については、「Amazon Kinesis Firehose を使用したユーザーアクセスの制御」(『Amazon Kinesis Firehose 開発者ガイド』)を参照してください。

    まず、次のようにファイル ~/TrustPolicyForFirehose.json で信頼ポリシーを作成します。account-id は、AWS アカウント ID で置き換えます。

    Copy
    { "Statement": { "Effect": "Allow", "Principal": { "Service": "firehose.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId":"account-id" } } } }
  3. create-role コマンドを使用し、信頼ポリシーファイルを指定して IAM ロールを作成します。後のステップで必要になるため、返された Role.Arn 値を書き留めます。

    Copy
    aws iam create-role \ --role-name FirehosetoS3Role \ --assume-role-policy-document file://~/TrustPolicyForFirehose.json { "Role": { "AssumeRolePolicyDocument": { "Statement": { "Action": "sts:AssumeRole", "Effect": "Allow", "Principal": { "Service": "logs.us-east-1.amazonaws.com" } } }, "RoleId": "AAOIIAH450GAB4HC5F431", "CreateDate": "2015-05-29T13:46:29.431Z", "RoleName": "FirehosetoS3Role", "Path": "/", "Arn": "arn:aws:iam::123456789012:role/FirehosetoS3Role" } }
  4. 権限ポリシーを作成し、Kinesis Firehose がアカウントで実行できるアクションを定義します。最初に、ファイル ~/PermissionsForFirehose.json で権限ポリシーを作成します。

    Copy
    { "Statement": [ { "Effect": "Allow", "Action": [ "s3:AbortMultipartUpload", "s3:GetBucketLocation", "s3:GetObject", "s3:ListBucket", "s3:ListBucketMultipartUploads", "s3:PutObject" ], "Resource": [ "arn:aws:s3:::my-bucket", "arn:aws:s3:::my-bucket/*" ] } ] }
  5. 次の put-role-policy コマンドを使用して、アクセス許可ポリシーをロールに関連付けます。

    Copy
    aws iam put-role-policy --role-name FirehosetoS3Role --policy-name Permissions-Policy-For-Firehose --policy-document file://~/PermissionsForFirehose.json
  6. 次のように、送信先 Kinesis Firehose 配信ストリームを作成します。RoleARNBucketARN のプレースホルダー値を、作成したロールおよびバケット ARN に置き換えます。

    Copy
    aws firehose create-delivery-stream \ --delivery-stream-name 'my-delivery-stream' \ --s3-destination-configuration \ RoleARN='arn:aws:iam::123456789012:role/FirehosetoS3Role',BucketARN='arn:aws:s3:::my-bucket'

    Kinesis Firehose は、Amazon S3 オブジェクトに提供された YYYY/MM/DD/HH UTC 時間形式をプレフィックスで自動的に使用する点に注意してください。時間形式プレフィックスの前に、追加のプレフィックスを指定できます。プレフィックスの最後がフォワードスラッシュ (/) の場合は、Amazon S3 バケット内のフォルダとして表示されます。

  7. ストリームがアクティブになるまで待ちます (これには数分かかる可能性があります)。Kinesis Firehose describe-delivery-stream コマンドを使用して、DeliveryStreamDescription.DeliveryStreamStatus プロパティをチェックできます。さらに、後のステップで必要になるため、DeliveryStreamDescription.DeliveryStreamARN 値を書き留めます。

    Copy
    aws firehose describe-delivery-stream --delivery-stream-name "my-delivery-stream" { "DeliveryStreamDescription": { "HasMoreDestinations": false, "VersionId": "1", "CreateTimestamp": 1446075815.822, "DeliveryStreamARN": "arn:aws:firehose:us-east-1:123456789012:deliverystream/my-delivery-stream", "DeliveryStreamStatus": "ACTIVE", "DeliveryStreamName": "my-delivery-stream", "Destinations": [ { "DestinationId": "destinationId-000000000001", "S3DestinationDescription": { "CompressionFormat": "UNCOMPRESSED", "EncryptionConfiguration": { "NoEncryptionConfig": "NoEncryption" }, "RoleARN": "delivery-stream-role", "BucketARN": "arn:aws:s3:::my-bucket", "BufferingHints": { "IntervalInSeconds": 300, "SizeInMBs": 5 } } } ] } }
  8. IAM ロールを作成して、CloudWatch Logs に Kinesis Firehose 送信ストリームにデータを置く権限を付与します。まず、ファイル ~/TrustPolicyForCWL.json で信頼ポリシーを作成します。

    Copy
    { "Statement": { "Effect": "Allow", "Principal": { "Service": "logs.us-east-1.amazonaws.com" }, "Action": "sts:AssumeRole" } }
  9. create-role コマンドを使用し、信頼ポリシーファイルを指定して IAM ロールを作成します。後のステップで必要になるため、返された Role.Arn 値を書き留めます。

    Copy
    aws iam create-role \ --role-name CWLtoKinesisFirehoseRole \ --assume-role-policy-document file://~/TrustPolicyForCWL.json { "Role": { "AssumeRolePolicyDocument": { "Statement": { "Action": "sts:AssumeRole", "Effect": "Allow", "Principal": { "Service": "logs.us-east-1.amazonaws.com" } } }, "RoleId": "AAOIIAH450GAB4HC5F431", "CreateDate": "2015-05-29T13:46:29.431Z", "RoleName": "CWLtoKinesisFirehoseRole", "Path": "/", "Arn": "arn:aws:iam::123456789012:role/CWLtoKinesisFirehoseRole" } }
  10. 権限ポリシーを作成し、CloudWatch Logs がアカウントで実行できるアクションを定義します。まず、権限ポリシーファイル (~/PermissionsForCWL.json など) を作成します。

    Copy
    { "Statement":[ { "Effect":"Allow", "Action":["firehose:*"], "Resource":["arn:aws:firehose:us-east-1:123456789012:*"] }, { "Effect":"Allow", "Action":["iam:PassRole"], "Resource":["arn:aws:iam::123456789012:role/CWLtoKinesisFirehoseRole"] } ] }
  11. put-role-policy コマンドを使用して、権限ポリシーをロールに関連付けます。

    Copy
    aws iam put-role-policy --role-name CWLtoKinesisFirehoseRole --policy-name Permissions-Policy-For-CWL --policy-document file://~/PermissionsForCWL.json
  12. Amazon Kinesis Firehose ストリームが Active 状態になり、IAM ロールを作成したら、CloudWatch Logs サブスクリプションフィルタを作成できます。サブスクリプションフィルタにより、選択されたロググループから Amazon Kinesis Firehose 送信ストリームへのリアルタイムログデータの流れがすぐに開始されます。

    Copy
    aws logs put-subscription-filter \ --log-group-name "CloudTrail" \ --filter-name "RootAccess" \ --filter-pattern "{$.userIdentity.type = Root}" \ --destination-arn "arn:aws:firehose:us-east-1:123456789012:deliverystream/my-delivery-stream" \ --role-arn "arn:aws:iam::123456789012:role/CWLtoKinesisFirehoseRole"
  13. サブスクリプションフィルタを設定したら、CloudWatch Logs によりフィルタパターンに一致するすべての受信ログイベントが Amazon Kinesis Firehose 送信ストリームに転送されます。データは、Amazon Kinesis Firehose 送信ストリームに設定された時間の間隔に基づいて、Amazon S3 に表示されます。十分な時間が経過すると、Amazon S3 バケットをチェックしてデータを確認できます。

    Copy
    aws s3api list-objects --bucket 'my-bucket' --prefix 'firehose/' { "Contents": [ { "LastModified": "2015-10-29T00:01:25.000Z", "ETag": "\"a14589f8897f4089d3264d9e2d1f1610\"", "StorageClass": "STANDARD", "Key": "firehose/2015/10/29/00/my-delivery-stream-2015-10-29-00-01-21-a188030a-62d2-49e6-b7c2-b11f1a7ba250", "Owner": { "DisplayName": "cloudwatch-logs", "ID": "1ec9cf700ef6be062b19584e0b7d84ecc19237f87b5" }, "Size": 593 }, { "LastModified": "2015-10-29T00:35:41.000Z", "ETag": "\"a7035b65872bb2161388ffb63dd1aec5\"", "StorageClass": "STANDARD", "Key": "firehose/2015/10/29/00/my-delivery-stream-2015-10-29-00-35-40-7cc92023-7e66-49bc-9fd4-fc9819cc8ed3", "Owner": { "DisplayName": "cloudwatch-logs", "ID": "1ec9cf700ef6be062b19584e0b7d84ecc19237f87b6" }, "Size": 5752 } ] }
    Copy
    aws s3api get-object --bucket 'my-bucket' --key 'firehose/2015/10/29/00/my-delivery-stream-2015-10-29-00-01-21-a188030a-62d2-49e6-b7c2-b11f1a7ba250' testfile.gz { "AcceptRanges": "bytes", "ContentType": "application/octet-stream", "LastModified": "Thu, 29 Oct 2015 00:07:06 GMT", "ContentLength": 593, "Metadata": {} }

    Amazon S3 オブジェクトのデータは、gzip 形式で圧縮されます。raw データは、コマンドラインから次の UNIX コマンドを使用して調べることができます。

    Copy
    zcat testfile.gz