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.

​
Updating your ECS task to support Subtrace

  1. Open ECS → Task definitions, go to your task and click Create new revision with JSON. open JSON
  2. In the JSON editor, add the SYS_PTRACE Linux capability to your container linuxParameters field: 
    "linuxParameters": {
  "capabilities": {
    "add": ["SYS_PTRACE"]
  }
},
    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: 
    "environment": [
  {
    "name": "SUBTRACE_ANCIENT_KERNEL",
    "value": "1"
  },
  {
    "name": "SUBTRACE_TOKEN",
    "value": "subt_****************"
  }
]
    As an example, here’s what the task JSON should look like: highlighted task JSON diff
  3. Click Create to create a new task revision.
Subtrace recommends using a Linux kernel of 5.14 or newer, which requires the EC2 launch type for your tasks. The Fargate launch type, which is the default, is still on kernel 5.10 as of May 2025.Set the SUBTRACE_ANCIENT_KERNEL=1 environment variable in your task definition to use Subtrace if your cluster is based on the Fargate launch type by modifying your task with the web interface or by editing the task JSON:
"environment": [
  {
    "name": "SUBTRACE_ANCIENT_KERNEL",
    "value": "1"
  }
]

​
Deploying a new revision of your service

  1. Back in Clusters → Services → my-app-service, click on Update service. update service button
  2. In the dropdown, select the revision you just created (or leave blank for “latest”). choose new revision
  3. 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.
  4. Go to the Subtrace UI and see a realtime stream of all network activity in your service.