Task metadata endpoint version 4 for tasks on Fargate
Important
If you are using Amazon ECS tasks hosted on Amazon EC2 instances, see Amazon ECS task metadata endpoint in the Amazon Elastic Container Service Developer Guide.
Beginning with Fargate platform version 1.4.0
, an environment variable
named ECS_CONTAINER_METADATA_URI_V4
is injected into each container in a
task. When you query the task metadata endpoint version 4, various task metadata and
Docker stats
The task metadata endpoint version 4 functions like the version 3 endpoint but
provides additional network metadata for your containers and tasks. Additional network
metrics are available when querying the /stats
endpoints as well.
Note
To avoid the need to create new task metadata endpoint versions in the future, additional metadata may be added to the version 4 output. We will not remove any existing metadata or change the metadata field names.
Enabling task metadata endpoint
The task metadata endpoint is on by default for all Amazon ECS tasks run on
Amazon Fargate that use platform version 1.4.0
or later.
Fargate task metadata endpoint version 4 paths
The following task metadata endpoints are available to containers:
${ECS_CONTAINER_METADATA_URI_V4}
-
This path returns metadata for the container.
${ECS_CONTAINER_METADATA_URI_V4}/task
-
This path returns metadata for the task, including a list of the container IDs and names for all of the containers associated with the task. For more information about the response for this endpoint, see Task metadata JSON response for tasks on Fargate.
${ECS_CONTAINER_METADATA_URI_V4}/stats
-
This path returns Docker stats for the Docker container. For more information about each of the returned stats, see ContainerStats
in the Docker API documentation. Note
Amazon ECS tasks on Amazon Fargate require that the container run for ~1 second prior to returning the container stats.
${ECS_CONTAINER_METADATA_URI_V4}/task/stats
-
This path returns Docker stats for all of the containers associated with the task. For more information about each of the returned stats, see ContainerStats
in the Docker API documentation. Note
Amazon ECS tasks on Amazon Fargate require that the container run for ~1 second prior to returning the container stats.
Task metadata JSON response for tasks on Fargate
The following metadata is returned in the task metadata endpoint
(${ECS_CONTAINER_METADATA_URI_V4}/task
) JSON response.
Cluster
-
The Amazon Resource Name (ARN) or short name of the Amazon ECS cluster to which the task belongs.
VPCID
-
The VPC ID of the Amazon EC2 container instance. This field only appears for Amazon EC2 instances.
Note
The
VPCID
metadata is only included when using Amazon ECS container agent version1.63.1
or later. TaskARN
-
The full Amazon Resource Name (ARN) of the task to which the container belongs.
Family
-
The family of the Amazon ECS task definition for the task.
Revision
-
The revision of the Amazon ECS task definition for the task.
DesiredStatus
-
The desired status for the task from Amazon ECS.
KnownStatus
-
The known status for the task from Amazon ECS.
Limits
-
The resource limits specified at the task levels such as CPU (expressed in vCPUs) and memory. This parameter is omitted if no resource limits are defined.
PullStartedAt
-
The timestamp for when the first container image pull began.
PullStoppedAt
-
The timestamp for when the last container image pull finished.
AvailabilityZone
-
The Availability Zone the task is in.
Note
The Availability Zone metadata is only available for Fargate tasks using platform version 1.4 or later (Linux) or 1.0.0 (Windows).
LaunchType
-
The launch type the task is using. When using cluster capacity providers, this indicates whether the task is using Fargate or EC2 infrastructure.
Note
This
LaunchType
metadata is only included when using Amazon ECS Linux container agent version1.45.0
or later (Linux) or 1.0.0 or later (Windows). EphemeralStorageMetrics
-
The reserved size and current usage of the ephemeral storage of this task.
Note
Fargate reserves space on disk. It is only used by Fargate. You aren't billed for it. It isn't shown in these metrics. However, you can see this additional storage in other tools such as
df
.Utilized
-
The current ephemeral storage usage (in MiB) of this task.
Reserved
-
The reserved ephemeral storage (in MiB) of this task. The size of the ephemeral storage can't be changed in a running task. You can specify the
ephermalStorage
object in your task definition to change the amount of ephemeral storage. TheephermalStorage
is specified in GiB, not MiB. TheephermalStorage
and theEphemeralStorageMetrics
are only available on Fargate Linux platform version 1.4.0 or later.
Containers
-
A list of container metadata for each container associated with the task.
DockerId
-
The Docker ID for the container.
When you use Fargate, the id is a 32-digit hex followed by a 10 digit number.
Name
-
The name of the container as specified in the task definition.
DockerName
-
The name of the container supplied to Docker. The Amazon ECS container agent generates a unique name for the container to avoid name collisions when multiple copies of the same task definition are run on a single instance.
Image
-
The image for the container.
ImageID
-
The SHA-256 digest for the image.
Ports
-
Any ports exposed for the container. This parameter is omitted if there are no exposed ports.
Labels
-
Any labels applied to the container. This parameter is omitted if there are no labels applied.
DesiredStatus
-
The desired status for the container from Amazon ECS.
KnownStatus
-
The known status for the container from Amazon ECS.
ExitCode
-
The exit code for the container. This parameter is omitted if the container has not exited.
Limits
-
The resource limits specified at the container level such as CPU (expressed in CPU units) and memory. This parameter is omitted if no resource limits are defined.
CreatedAt
-
The time stamp for when the container was created. This parameter is omitted if the container has not been created yet.
StartedAt
-
The time stamp for when the container started. This parameter is omitted if the container has not started yet.
FinishedAt
-
The time stamp for when the container stopped. This parameter is omitted if the container has not stopped yet.
Type
-
The type of the container. Containers that are specified in your task definition are of type
NORMAL
. You can ignore other container types, which are used for internal task resource provisioning by the Amazon ECS container agent. LogDriver
-
The log driver the container is using.
Note
This
LogDriver
metadata is only included when using Amazon ECS Linux container agent version1.45.0
or later. LogOptions
-
The log driver options defined for the container.
Note
This
LogOptions
metadata is only included when using Amazon ECS Linux container agent version1.45.0
or later. ContainerARN
-
The full Amazon Resource Name (ARN) of the container.
Note
This
ContainerARN
metadata is only included when using Amazon ECS Linux container agent version1.45.0
or later. Networks
-
The network information for the container, such as the network mode and IP address. This parameter is omitted if no network information is defined.
Snapshotter
-
The snapshotter that was used by containerd to download this container image. Valid values are
overlayfs
, which is the default, andsoci
, used when lazy loading with a SOCI index. This parameter is only available for tasks that run on Linux platform version1.4.0
.
ClockDrift
-
The information about the difference between the reference time and the system time.
ReferenceTime
-
The basis of clock accuracy. Amazon ECS uses the Coordinated Universal Time (UTC) global standard through NTP, for example
2021-09-07T16:57:44Z
. ClockErrorBound
-
The measure of clock error, defined as the offset to UTC. This error is the difference in milliseconds between the reference time and the system time.
ClockSynchronizationStatus
-
Indicates whether the most recent synchronization attempt between the system time and the reference time was successful.
The valid values are
SYNCHRONIZED
andNOT_SYNCHRONIZED
.
ExecutionStoppedAt
-
The time stamp for when the tasks
DesiredStatus
moved toSTOPPED
. This occurs when an essential container moves toSTOPPED
.
Examples for tasks on Fargate
The following examples show sample outputs from the task metadata endpoints for Amazon ECS tasks run on Amazon Fargate.
From the container, you can use curl followed by the task meta data endpoint to
query the endpoint for example curl
${ECS_CONTAINER_METADATA_URI_V4}/task
.
Example container metadata response
When querying the ${ECS_CONTAINER_METADATA_URI_V4}
endpoint you
are returned only metadata about the container itself. The following is an
example output.
{
"DockerId": "cd189a933e5849daa93386466019ab50-2495160603",
"Name": "curl",
"DockerName": "curl",
"Image": "111122223333.dkr.ecr.us-west-2.amazonaws.com/curltest:latest",
"ImageID": "sha256:25f3695bedfb454a50f12d127839a68ad3caf91e451c1da073db34c542c4d2cb",
"Labels": {
"com.amazonaws.ecs.cluster": "arn:aws:ecs:us-west-2:111122223333:cluster/default",
"com.amazonaws.ecs.container-name": "curl",
"com.amazonaws.ecs.task-arn": "arn:aws:ecs:us-west-2:111122223333:task/default/cd189a933e5849daa93386466019ab50",
"com.amazonaws.ecs.task-definition-family": "curltest",
"com.amazonaws.ecs.task-definition-version": "2"
},
"DesiredStatus": "RUNNING",
"KnownStatus": "RUNNING",
"Limits": {
"CPU": 10,
"Memory": 128
},
"CreatedAt": "2020-10-08T20:09:11.44527186Z",
"StartedAt": "2020-10-08T20:09:11.44527186Z",
"Type": "NORMAL",
"Networks": [
{
"NetworkMode": "awsvpc",
"IPv4Addresses": [
"192.0.2.3"
],
"AttachmentIndex": 0,
"MACAddress": "0a:de:f6:10:51:e5",
"IPv4SubnetCIDRBlock": "192.0.2.0/24",
"DomainNameServers": [
"192.0.2.2"
],
"DomainNameSearchList": [
"us-west-2.compute.internal"
],
"PrivateDNSName": "ip-10-0-0-222.us-west-2.compute.internal",
"SubnetGatewayIpv4Address": "192.0.2.0/24"
}
],
"ContainerARN": "arn:aws:ecs:us-west-2:111122223333:container/05966557-f16c-49cb-9352-24b3a0dcd0e1",
"LogOptions": {
"awslogs-create-group": "true",
"awslogs-group": "/ecs/containerlogs",
"awslogs-region": "us-west-2",
"awslogs-stream": "ecs/curl/cd189a933e5849daa93386466019ab50"
},
"LogDriver": "awslogs",
"Snapshotter": "overlayfs"
}
Example Fargate task metadata response
When querying the ${ECS_CONTAINER_METADATA_URI_V4}/task
endpoint
you are returned metadata about the task the container is part of. The following
is an example output.
{
"Cluster": "arn:aws:ecs:us-east-1:123456789012:cluster/clusterName",
"TaskARN": "arn:aws:ecs:us-east-1:123456789012:task/MyEmptyCluster/bfa2636268144d039771334145e490c5",
"Family": "sample-fargate",
"Revision": "5",
"DesiredStatus": "RUNNING",
"KnownStatus": "RUNNING",
"Limits": {
"CPU": 0.25,
"Memory": 512
},
"PullStartedAt": "2023-07-21T15:45:33.532811081Z",
"PullStoppedAt": "2023-07-21T15:45:38.541068435Z",
"AvailabilityZone": "us-east-1d",
"Containers": [
{
"DockerId": "bfa2636268144d039771334145e490c5-1117626119",
"Name": "curl-image",
"DockerName": "curl-image",
"Image": "curlimages/curl",
"ImageID": "sha256:daf3f46a2639c1613b25e85c9ee4193af8a1d538f92483d67f9a3d7f21721827",
"Labels": {
"com.amazonaws.ecs.cluster": "arn:aws:ecs:us-east-1:123456789012:cluster/MyEmptyCluster",
"com.amazonaws.ecs.container-name": "curl-image",
"com.amazonaws.ecs.task-arn": "arn:aws:ecs:us-east-1:123456789012:task/MyEmptyCluster/bfa2636268144d039771334145e490c5",
"com.amazonaws.ecs.task-definition-family": "sample-fargate",
"com.amazonaws.ecs.task-definition-version": "5"
},
"DesiredStatus": "RUNNING",
"KnownStatus": "RUNNING",
"Limits": { "CPU": 128 },
"CreatedAt": "2023-07-21T15:45:44.91368314Z",
"StartedAt": "2023-07-21T15:45:44.91368314Z",
"Type": "NORMAL",
"Networks": [
{
"NetworkMode": "awsvpc",
"IPv4Addresses": ["172.31.42.189"],
"AttachmentIndex": 0,
"MACAddress": "0e:98:9f:33:76:d3",
"IPv4SubnetCIDRBlock": "172.31.32.0/20",
"DomainNameServers": ["172.31.0.2"],
"DomainNameSearchList": ["ec2.internal"],
"PrivateDNSName": "ip-172-31-42-189.ec2.internal",
"SubnetGatewayIpv4Address": "172.31.32.1/20"
}
],
"ContainerARN": "arn:aws:ecs:us-east-1:123456789012:container/MyEmptyCluster/bfa2636268144d039771334145e490c5/da6cccf7-1178-400c-afdf-7536173ee209",
"Snapshotter": "overlayfs"
},
{
"DockerId": "bfa2636268144d039771334145e490c5-3681984407",
"Name": "fargate-app",
"DockerName": "fargate-app",
"Image": "public.ecr.aws/docker/library/httpd:latest",
"ImageID": "sha256:8059bdd0058510c03ae4c808de8c4fd2c1f3c1b6d9ea75487f1e5caa5ececa02",
"Labels": {
"com.amazonaws.ecs.cluster": "arn:aws:ecs:us-east-1:123456789012:cluster/MyEmptyCluster",
"com.amazonaws.ecs.container-name": "fargate-app",
"com.amazonaws.ecs.task-arn": "arn:aws:ecs:us-east-1:123456789012:task/MyEmptyCluster/bfa2636268144d039771334145e490c5",
"com.amazonaws.ecs.task-definition-family": "sample-fargate",
"com.amazonaws.ecs.task-definition-version": "5"
},
"DesiredStatus": "RUNNING",
"KnownStatus": "RUNNING",
"Limits": { "CPU": 2 },
"CreatedAt": "2023-07-21T15:45:44.954460255Z",
"StartedAt": "2023-07-21T15:45:44.954460255Z",
"Type": "NORMAL",
"Networks": [
{
"NetworkMode": "awsvpc",
"IPv4Addresses": ["172.31.42.189"],
"AttachmentIndex": 0,
"MACAddress": "0e:98:9f:33:76:d3",
"IPv4SubnetCIDRBlock": "172.31.32.0/20",
"DomainNameServers": ["172.31.0.2"],
"DomainNameSearchList": ["ec2.internal"],
"PrivateDNSName": "ip-172-31-42-189.ec2.internal",
"SubnetGatewayIpv4Address": "172.31.32.1/20"
}
],
"ContainerARN": "arn:aws:ecs:us-east-1:123456789012:container/MyEmptyCluster/bfa2636268144d039771334145e490c5/f65b461d-aa09-4acb-a579-9785c0530cbc",
"Snapshotter": "overlayfs"
}
],
"LaunchType": "FARGATE",
"ClockDrift": {
"ClockErrorBound": 0.446931,
"ReferenceTimestamp": "2023-07-21T16:09:17Z",
"ClockSynchronizationStatus": "SYNCHRONIZED"
},
"EphemeralStorageMetrics": {
"Utilized": 261,
"Reserved": 20496
}
}
Example task stats response
When querying the ${ECS_CONTAINER_METADATA_URI_V4}/task/stats
endpoint you are returned network metrics about the task the container is part
of. The following is an example output.
{
"3d1f891cded94dc795608466cce8ddcf-464223573": {
"read": "2020-10-08T21:24:44.938937019Z",
"preread": "2020-10-08T21:24:34.938633969Z",
"pids_stats": {},
"blkio_stats": {
"io_service_bytes_recursive": [
{
"major": 202,
"minor": 26368,
"op": "Read",
"value": 638976
},
{
"major": 202,
"minor": 26368,
"op": "Write",
"value": 0
},
{
"major": 202,
"minor": 26368,
"op": "Sync",
"value": 638976
},
{
"major": 202,
"minor": 26368,
"op": "Async",
"value": 0
},
{
"major": 202,
"minor": 26368,
"op": "Total",
"value": 638976
}
],
"io_serviced_recursive": [
{
"major": 202,
"minor": 26368,
"op": "Read",
"value": 12
},
{
"major": 202,
"minor": 26368,
"op": "Write",
"value": 0
},
{
"major": 202,
"minor": 26368,
"op": "Sync",
"value": 12
},
{
"major": 202,
"minor": 26368,
"op": "Async",
"value": 0
},
{
"major": 202,
"minor": 26368,
"op": "Total",
"value": 12
}
],
"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": 1137691504,
"percpu_usage": [
696479228,
441212276,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
],
"usage_in_kernelmode": 80000000,
"usage_in_usermode": 810000000
},
"system_cpu_usage": 9393210000000,
"online_cpus": 2,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
},
"precpu_stats": {
"cpu_usage": {
"total_usage": 1136624601,
"percpu_usage": [
695639662,
440984939,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
],
"usage_in_kernelmode": 80000000,
"usage_in_usermode": 810000000
},
"system_cpu_usage": 9373330000000,
"online_cpus": 2,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
},
"memory_stats": {
"usage": 6504448,
"max_usage": 8458240,
"stats": {
"active_anon": 1675264,
"active_file": 557056,
"cache": 651264,
"dirty": 0,
"hierarchical_memory_limit": 536870912,
"hierarchical_memsw_limit": 9223372036854772000,
"inactive_anon": 0,
"inactive_file": 3088384,
"mapped_file": 430080,
"pgfault": 11034,
"pgmajfault": 5,
"pgpgin": 8436,
"pgpgout": 7137,
"rss": 4669440,
"rss_huge": 0,
"total_active_anon": 1675264,
"total_active_file": 557056,
"total_cache": 651264,
"total_dirty": 0,
"total_inactive_anon": 0,
"total_inactive_file": 3088384,
"total_mapped_file": 430080,
"total_pgfault": 11034,
"total_pgmajfault": 5,
"total_pgpgin": 8436,
"total_pgpgout": 7137,
"total_rss": 4669440,
"total_rss_huge": 0,
"total_unevictable": 0,
"total_writeback": 0,
"unevictable": 0,
"writeback": 0
},
"limit": 9223372036854772000
},
"name": "curltest",
"id": "3d1f891cded94dc795608466cce8ddcf-464223573",
"networks": {
"eth1": {
"rx_bytes": 2398415937,
"rx_packets": 1898631,
"rx_errors": 0,
"rx_dropped": 0,
"tx_bytes": 1259037719,
"tx_packets": 428002,
"tx_errors": 0,
"tx_dropped": 0
}
},
"network_rate_stats": {
"rx_bytes_per_sec": 43.298687872232854,
"tx_bytes_per_sec": 215.39347269466413
}
}
}