Monitor all network requests in your AWS ECS cluster using Subtrace.
If you deploy your application on AWS Elastic Container Service (ECS), Subtrace is the easiest way to monitor the network activity in your cluster in realtime.
Subtrace requires a Linux kernel of 5.14 or newer, so you’ll have to use the EC2 launch type for your ECS tasks. The Fargate launch type is still on kernel 5.10 as of May 2025 and is not compatible with Subtrace.
How do I create an ECS cluster with EC2 launch type?
Open ECS → Clusters → Create cluster
Give the cluster a name. Anything alphanumeric + hyphens works.
In the Infrastructure panel, uncheck Fargate and check Amazon EC2 instances.
Leave Create new ASG selected. ECS will automatically spin up an auto-scaling group so your tasks run on instances that register themselves with the cluster.
Choose Amazon Linux 2023 as the AMI. It ships with Linux kernel version 6.1, which comfortably satisfies Subtrace’s 5.14+ requirement.
Pick any instance type and a minimum/maximum instance limit for the auto-scaling group. You can change this later.
Scroll to the bottom and click Create. ECS will provision the ASG, launch EC2 instances, install the ECs agent, auto‑register them with the new cluster and give you a cluster that’s compatible with EC2 launch type tasks.
Open ECS → Task definitions, go to your task and click Create new revision with JSON.
In the JSON editor, add the SYS_PTRACE
Linux capability to your container linuxParameters
field:
The SYS_PTRACE
capability is required because it’s what allows Subtrace
to automatically monitor network activity without any code changes or root
privileges. The ECS UI does not expose this field, hence the JSON-based
update to the task definition.
Set the API token that you created in the Subtrace dashboard as an environment variable:
As an example, here’s what the task JSON should look like:
Click Create to create a new task revision.
Back in Clusters → Services → my-app-service
, click on Update service.
In the dropdown, select the revision you just created (or leave blank for “latest”).
Click Update at the bottom. ECS will spin up a new task with the new definition; when it’s healthy, the old one will be stopped.
Go to the Subtrace UI and see a realtime stream of all network activity in your service.