タスクメタデータエンドポイントバージョン 4 - Amazon Elastic Container Service

タスクメタデータエンドポイントバージョン 4

Amazon ECS コンテナエージェントは、各コンテナに環境変数を注入します。これは、タスクメタデータエンドポイントと呼ばれ、コンテナにさまざまなタスクメタデータと Docker 統計を提供します。

タスクメタデータとネットワークレートの統計は CloudWatch Container Insights に送信され、AWS マネジメントコンソール で表示できます。詳細については、「Amazon ECS CloudWatch Container Insights」を参照してください。

重要

Amazon ECS は、以前のバージョンのタスクメタデータエンドポイントを提供していました。新しいタスクメタデータエンドポイントバージョンを将来作成する必要がないように、追加のメタデータをバージョン 4 の出力に追加できます。既存のメタデータが削除されたり、メタデータのフィールド名が変更されたりすることはありません。

タスクメタデータエンドポイントの有効化

環境変数は、デフォルトで、プラットフォームバージョン 1.4.0 以降を使用する Fargate の Amazon ECS タスクと、Amazon ECS コンテナエージェントのバージョン 1.39.0 以降を実行している Amazon EC2 の Amazon ECS タスクに注入されます。詳細については、「Amazon ECS コンテナエージェントバージョン」を参照してください。

エージェントを最新バージョンに更新することで、古いバージョンの Amazon ECS コンテナエージェントを使用する Amazon EC2 インスタンスでこの機能のサポートを追加できます。詳細については、「Amazon ECS コンテナエージェントの更新」を参照してください。

タスクメタデータエンドポイントバージョン 4 のパス

次のタスクメタデータエンドポイントパスをコンテナで使用できます。

${ECS_CONTAINER_METADATA_URI_V4}

このパスはコンテナのメタデータを返します。

${ECS_CONTAINER_METADATA_URI_V4}/task

このパスはタスクのメタデータを返します。これには、タスクに関連付けられたすべてのコンテナのコンテナ ID および名前のリストが含まれています。このエンドポイントのレスポンスの詳細については、「タスクメタデータ JSON レスポンス」を参照してください。

${ECS_CONTAINER_METADATA_URI_V4}/stats

このパスは特定のコンテナの Docker 統計を返します。返される各統計の詳細については、Docker API ドキュメントの「ContainerStats」を参照してください。

注記

AWS Fargate の Amazon ECS タスクは、コンテナの統計を返す前にコンテナを最長 1 秒間実行する必要があります。

コンテナエージェントのバージョン 1.43.0 以上を実行している Amazon EC2 インスタンスでホストされる awsvpc または bridge ネットワークモードを使用する Amazon ECS タスクの場合、レスポンスには追加のネットワークレート統計が含まれます。他のすべてのタスクでは、レスポンスには累積ネットワーク統計のみが含まれます。

${ECS_CONTAINER_METADATA_URI_V4}/task/stats

このパスはタスクに関連付けられたすべてのコンテナの Docker 統計を返します。これをサイドカーコンテナで使用し、ネットワークメトリクスを抽出できます。返される各統計の詳細については、Docker API ドキュメントの「ContainerStats」を参照してください。

注記

AWS Fargate の Amazon ECS タスクは、タスクの統計を返す前にコンテナを最長 1 秒間実行する必要があります。

コンテナエージェントのバージョン 1.43.0 以上を実行している Amazon EC2 インスタンスでホストされる awsvpc または bridge ネットワークモードを使用する Amazon ECS タスクの場合、レスポンスには追加のネットワークレート統計が含まれます。他のすべてのタスクでは、レスポンスには累積ネットワーク統計のみが含まれます。

タスクメタデータ JSON レスポンス

次の情報が、タスクメタデータエンドポイント (${ECS_CONTAINER_METADATA_URI_V4}/task) JSON レスポンスから返されます。

Cluster

コンテナが属している Amazon ECS クラスターの Amazon リソースネーム (ARN) または短縮名。

TaskARN

コンテナが属しているタスクの完全な Amazon リソースネーム (ARN)。

Family

タスクの Amazon ECS タスク定義のファミリー。

Revision

タスクの Amazon ECS タスク定義のリビジョン。

DesiredStatus

Amazon ECS からのタスクの目的のステータス。

KnownStatus

Amazon ECS からのタスクの既知のステータス。

Limits

タスクレベルで指定されたリソースの制限 (CPU やメモリなど)。リソースの制限が定義されていない場合はこのパラメータは省略されます。

PullStartedAt

最初のコンテナイメージのプル開始時のタイムスタンプ。

PullStoppedAt

最後のコンテナイメージのプル終了時のタイムスタンプ。

AvailabilityZone

タスクがあるアベイラビリティーゾーン。

注記

アベイラビリティーゾーンのメタデータは、プラットフォームバージョン 1.4 以降を使用する Fargate タスクでのみ使用できます。

Containers

タスクに関連付けられている各コンテナのコンテナメタデータのリスト。

DockerId

コンテナの Docker ID。

Name

タスク定義で指定されたコンテナの名前。

DockerName

Docker に提供されたコンテナの名前。Amazon ECS コンテナエージェントはコンテナに一意の名前を生成し、同じタスク定義の複数のコピーが単一のインスタンスで実行されている場合に競合を回避します。

Image

コンテナのイメージ。

ImageID

イメージの SHA-256 ダイジェスト。

Ports

コンテナに対して公開されている任意のポート。公開ポートがない場合はこのパラメータは省略されます。

Labels

コンテナに適用された任意のラベル。ラベルが適用されていない場合はこのパラメータは省略されます。

DesiredStatus

Amazon ECS からのコンテナの目的のステータス。

KnownStatus

Amazon ECS からのコンテナの既知のステータス。

ExitCode

コンテナの終了コード。このパラメータは、コンテナが終了していない場合は省略されます。

Limits

コンテナレベルで指定されたリソースの制限 (CPU やメモリなど)。リソースの制限が定義されていない場合はこのパラメータは省略されます。

CreatedAt

コンテナ作成時のタイムスタンプ。このパラメータは、コンテナがまだ作成されていない場合は省略されます。

StartedAt

コンテナ起動時のタイムスタンプ。このパラメータは、コンテナがまだ起動していない場合は省略されます。

FinishedAt

コンテナ停止時のタイムスタンプ。このパラメータは、コンテナがまだ停止していない場合は省略されます。

Type

コンテナのタイプ。タスク定義で指定されているコンテナのタイプは NORMAL です。他のコンテナタイプは無視してかまいません。これらは コンテナエージェントによってプロビジョニングされた内部タスクリソースで使用されます。

Networks

ネットワークモードや IP アドレスなど、コンテナのネットワーク情報。ネットワーク情報が定義されていない場合はこのパラメータは省略されます。

ExecutionStoppedAt

タスクの DesiredStatusSTOPPED に移行した時のタイムスタンプ。これは、必須コンテナが STOPPED に移行したときに発生します。

以下の例は、タスクメタデータエンドポイントそれぞれからの出力例を示しています。

コンテナメタデータレスポンスの例

${ECS_CONTAINER_METADATA_URI_V4} エンドポイントにクエリを実行すると、コンテナ自体に関するメタデータのみが返されます。以下に出力例を示します。

{ "DockerId": "c7a6b9b237934e9999f319ea3ccc9da4query-metadata", "Name": "query-metadata", "DockerName": "query-metadata", "Image": "mreferre/eksutils", "ImageID": "sha256:1b146e73f801617610dcb00441c6423e7c85a7583dd4a65ed1be03cb0e123311", "Labels": { "com.amazonaws.ecs.cluster": "arn:aws:ecs:us-west-2:111122223333:cluster/default", "com.amazonaws.ecs.container-name": "query-metadata", "com.amazonaws.ecs.task-arn": "arn:aws:ecs:us-west-2:111122223333:task/default/c7a6b9b237934e9999f319ea3ccc9da4", "com.amazonaws.ecs.task-definition-family": "query-metadata", "com.amazonaws.ecs.task-definition-version": "3" }, "DesiredStatus": "RUNNING", "KnownStatus": "RUNNING", "Limits": { "CPU": 2 }, "CreatedAt": "2020-03-26T22:11:23.62831313Z", "StartedAt": "2020-03-26T22:11:23.62831313Z", "Type": "NORMAL", "Networks": [ { "NetworkMode": "awsvpc", "IPv4Addresses": [ "10.0.0.61" ], "AttachmentIndex": 0, "IPv4SubnetCIDRBlock": "10.0.0.0/24", "MACAddress": "0a:d2:d0:80:b6:b4", "DomainNameServers": [ "10.0.0.2" ], "DomainNameSearchList": [ "us-west-2.compute.internal" ], "PrivateDNSName": "ip-10-0-0-61.us-west-2.compute.internal", "SubnetGatewayIpv4Address": "" } ] }

タスクメタデータレスポンスの例

${ECS_CONTAINER_METADATA_URI_V4}/task エンドポイントにクエリを実行すると、コンテナが属しているタスクに関するメタデータが返されます。以下に出力例を示します。

{ "Cluster": "arn:aws:ecs:us-west-2:111122223333:cluster/default", "TaskARN": "arn:aws:ecs:us-west-2:111122223333:task/default/febee046097849aba589d4435207c04a", "Family": "query-metadata", "Revision": "7", "DesiredStatus": "RUNNING", "KnownStatus": "RUNNING", "Limits": { "CPU": 0.25, "Memory": 512 }, "PullStartedAt": "2020-03-26T22:25:40.420726088Z", "PullStoppedAt": "2020-03-26T22:26:22.235177616Z", "AvailabilityZone": "us-west-2c", "Containers": [ { "DockerId": "febee046097849aba589d4435207c04aquery-metadata", "Name": "query-metadata", "DockerName": "query-metadata", "Image": "mreferre/eksutils", "ImageID": "sha256:1b146e73f801617610dcb00441c6423e7c85a7583dd4a65ed1be03cb0e123311", "Labels": { "com.amazonaws.ecs.cluster": "arn:aws:ecs:us-west-2:111122223333:cluster/default", "com.amazonaws.ecs.container-name": "query-metadata", "com.amazonaws.ecs.task-arn": "arn:aws:ecs:us-west-2:111122223333:task/default/febee046097849aba589d4435207c04a", "com.amazonaws.ecs.task-definition-family": "query-metadata", "com.amazonaws.ecs.task-definition-version": "7" }, "DesiredStatus": "RUNNING", "KnownStatus": "RUNNING", "Limits": { "CPU": 2 }, "CreatedAt": "2020-03-26T22:26:24.534553758Z", "StartedAt": "2020-03-26T22:26:24.534553758Z", "Type": "NORMAL", "Networks": [ { "NetworkMode": "awsvpc", "IPv4Addresses": [ "10.0.0.108" ], "AttachmentIndex": 0, "IPv4SubnetCIDRBlock": "10.0.0.0/24", "MACAddress": "0a:62:17:7a:36:68", "DomainNameServers": [ "10.0.0.2" ], "DomainNameSearchList": [ "us-west-2.compute.internal" ], "PrivateDNSName": "ip-10-0-0-108.us-west-2.compute.internal", "SubnetGatewayIpv4Address": "" } ] } ] }

統計レスポンス例

${ECS_CONTAINER_METADATA_URI_V4}/stats エンドポイントにクエリを実行すると、コンテナのネットワークメトリクスが返されます。コンテナエージェントのバージョン 1.43.0 以上を実行している Amazon EC2 インスタンスでホストされる awsvpc または bridge ネットワークモードを使用する Amazon ECS タスクの場合、レスポンスには追加のネットワークレート統計が含まれます。他のすべてのタスクでは、レスポンスには累積ネットワーク統計のみが含まれます。

次に、bridge ネットワークモードを使用する Amazon EC2 の Amazon ECS タスクからの出力例を示します。

{ "read": "2020-08-06T22:45:31.349948898Z", "preread": "2020-08-06T22:45:30.347408046Z", "pids_stats": { "current": 2 }, "blkio_stats": { "io_service_bytes_recursive": [ ], "io_serviced_recursive": [ ], "io_queue_recursive": [ ], "io_service_time_recursive": [ ], "io_wait_time_recursive": [ ], "io_merged_recursive": [ ], "io_time_recursive": [ ], "sectors_recursive": [ ] }, "num_procs": 0, "storage_stats": { }, "cpu_stats": { "cpu_usage": { "total_usage": 412520458, "percpu_usage": [ 203701476, 208818982, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ], "usage_in_kernelmode": 10000000, "usage_in_usermode": 350000000 }, "system_cpu_usage": 2243010000000, "online_cpus": 2, "throttling_data": { "periods": 0, "throttled_periods": 0, "throttled_time": 0 } }, "precpu_stats": { "cpu_usage": { "total_usage": 412420561, "percpu_usage": [ 203701476, 208719085, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ], "usage_in_kernelmode": 10000000, "usage_in_usermode": 350000000 }, "system_cpu_usage": 2241010000000, "online_cpus": 2, "throttling_data": { "periods": 0, "throttled_periods": 0, "throttled_time": 0 } }, "memory_stats": { "usage": 1896448, "max_usage": 6324224, "stats": { "active_anon": 495616, "active_file": 0, "cache": 0, "dirty": 0, "hierarchical_memory_limit": 134217728, "hierarchical_memsw_limit": 268435456, "inactive_anon": 0, "inactive_file": 0, "mapped_file": 0, "pgfault": 4025, "pgmajfault": 0, "pgpgin": 2908, "pgpgout": 2785, "rss": 503808, "rss_huge": 0, "total_active_anon": 495616, "total_active_file": 0, "total_cache": 0, "total_dirty": 0, "total_inactive_anon": 0, "total_inactive_file": 0, "total_mapped_file": 0, "total_pgfault": 4025, "total_pgmajfault": 0, "total_pgpgin": 2908, "total_pgpgout": 2785, "total_rss": 503808, "total_rss_huge": 0, "total_unevictable": 0, "total_writeback": 0, "unevictable": 0, "writeback": 0 }, "limit": 134217728 }, "name": "query-metadata", "id": "1823e1f6-7248-43c3-bed6-eea1fa7501a5query-metadata", "networks": { "eth0": { "rx_bytes": 1802, "rx_packets": 19, "rx_errors": 0, "rx_dropped": 0, "tx_bytes": 567, "tx_packets": 7, "tx_errors": 0, "tx_dropped": 0 } }, "network_rate_stats": { "rx_bytes_per_sec": 0, "tx_bytes_per_sec": 0 } }

タスク統計情報のレスポンス例

${ECS_CONTAINER_METADATA_URI_V4}/task/stats エンドポイントにクエリを実行すると、コンテナが属しているタスクに関するネットワークメトリクスが返されます。Fargate タスクからの出力例を次に示します。

{ "1823e1f6-7248-43c3-bed6-eea1fa7501a5query-metadata": { "read": "2020-04-06T16:12:01.090148907Z", "preread": "2020-04-06T16:11:56.083890951Z", "pids_stats": { }, "blkio_stats": { "io_service_bytes_recursive": [ { "major": 202, "minor": 26368, "op": "Read", "value": 3452928 }, { "major": 202, "minor": 26368, "op": "Write", "value": 0 }, { "major": 202, "minor": 26368, "op": "Sync", "value": 3452928 }, { "major": 202, "minor": 26368, "op": "Async", "value": 0 }, { "major": 202, "minor": 26368, "op": "Total", "value": 3452928 } ], "io_serviced_recursive": [ { "major": 202, "minor": 26368, "op": "Read", "value": 118 }, { "major": 202, "minor": 26368, "op": "Write", "value": 0 }, { "major": 202, "minor": 26368, "op": "Sync", "value": 118 }, { "major": 202, "minor": 26368, "op": "Async", "value": 0 }, { "major": 202, "minor": 26368, "op": "Total", "value": 118 } ], "io_queue_recursive": [ ], "io_service_time_recursive": [ ], "io_wait_time_recursive": [ ], "io_merged_recursive": [ ], "io_time_recursive": [ ], "sectors_recursive": [ ] }, "num_procs": 0, "storage_stats": { }, "cpu_stats": { "cpu_usage": { "total_usage": 410557100, "percpu_usage": [ 410557100, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ], "usage_in_kernelmode": 10000000, "usage_in_usermode": 250000000 }, "throttling_data": { "periods": 0, "throttled_periods": 0, "throttled_time": 0 } }, "precpu_stats": { "cpu_usage": { "total_usage": 0, "usage_in_kernelmode": 0, "usage_in_usermode": 0 }, "throttling_data": { "periods": 0, "throttled_periods": 0, "throttled_time": 0 } }, "memory_stats": { "usage": 4390912, "max_usage": 6488064, "stats": { "active_anon": 278528, "active_file": 344064, "cache": 3452928, "dirty": 0, "hierarchical_memory_limit": 536870912, "hierarchical_memsw_limit": 9223372036854772000, "inactive_anon": 0, "inactive_file": 3108864, "mapped_file": 2412544, "pgfault": 2800, "pgmajfault": 28, "pgpgin": 3144, "pgpgout": 2233, "rss": 278528, "rss_huge": 0, "total_active_anon": 278528, "total_active_file": 344064, "total_cache": 3452928, "total_dirty": 0, "total_inactive_anon": 0, "total_inactive_file": 3108864, "total_mapped_file": 2412544, "total_pgfault": 2800, "total_pgmajfault": 28, "total_pgpgin": 3144, "total_pgpgout": 2233, "total_rss": 278528, "total_rss_huge": 0, "total_unevictable": 0, "total_writeback": 0, "unevictable": 0, "writeback": 0 }, "limit": 9223372036854772000 }, "name": "query-metadata", "id": "1823e1f6-7248-43c3-bed6-eea1fa7501a5query-metadata", "networks": { "eth1": { "rx_bytes": 564655295, "rx_packets": 384960, "rx_errors": 0, "rx_dropped": 0, "tx_bytes": 3043269, "tx_packets": 54355, "tx_errors": 0, "tx_dropped": 0 } } } }