• 01 Dec 2021
  • 4 Minutes to read


The topic covers installation and configuration of traceable-agent using a custom docker-compose.yml file. You also need to configure a few parameters in the ecs-params.yml file.


Read the following prerequisites before starting with installation:

  • ECS CLI - For an ECS environment, the installation requires the use of ecs-cli. Make sure that ecs-cli is installed. For more information on ecs-cli, see Installing the Amazon ECS CLI.
  • VPC, subnets, and security groups - Make a note of VPC, subnets, and security groups that will be used as part of the instrumentation process.
  • DNS hostnames and resolutions - Make sure to turn on DNS hostnames and resolutions for the VPC that is used by the ECS cluster. If these are not turned on, then DNS resolution will not work when the Traceable proxy or sidecar tries to connect to the Traceable agent.
  • Traceable Token - You need a valid Traceable token to complete the installation. Complete the following steps to generate a token:

    To generate the , login to Traceable and click on  Administration()> Access Token.

Traceable access token

Set up your ECS environment

Setting up your ECS environment consists of the following:

  • Creating a cluster
  • Fetch VPC, subnet, and security groups

Create Cluster

Create a cluster using the ecs-cli. Follow the steps outlined in the AWS Docs. Step 3.1 from the AWS Docs will output the VPC and subnets. Save these because they will need to be reused in this tutorial. 

ecs-cli up --cluster-config <CLUSTER_CONFIG> --ecs-profile <CLUSTER_PROFILE>

Fetch VPC, SUBNET, and Security Groups

VPC and Subnet information is returned when you initially created the cluster with step 3.1 in the AWS Docs. The command returns something similar to:

VPC created: vpc-xxxx
Subnet created: subnet-xxxx
Subnet created: subnet-xxxx


Enter the following command to fetch the security group:

aws ec2 describe-security-groups --filters Name=vpc-id,Values=<VPC_ID> --region <REGION>

Create cluster config and ECS CLI profile

Enter the following commands to create cluster-config and ecs-profile:

  1. Configure an ECS cluster with a launch type, for example, ECS or FARGATE. Enter the following command:
ecs-cli configure --cluster <CLUSTER_NAME> --region <REGION> --default-launch-type <FARGATE|EC2> --config-name <CLUSTER_CONFIG_NAME>

For example, if your compute engine for ECS is FARGATE, then the value for default-launch-type would be FARGATE.

  1. Configure an ECS CLI profile with your AWS access and secret key. Enter the following command:
ecs-cli configure profile --access-key <AWS_ACCESS_KEY_ID> --secret-key <AWS_SECRET_ACCESS_KEY> --profile-name <CLUSTER_PROFILE>

Install Traceable platform agent and side-car

Installing Traceable platform agent consists of the following:

  • Configuring the ecs-params.yml file
  • Configuring the docker-compose.yml file

Configure ecs-params.yml file

Based on your ECS environment, configure the ecs-params.yml file. Following is a sample ecs-params.yml file for installing the Traceable platform agent.

version: 1
  ecs_network_mode: awsvpc # update if needed

  task_execution_role: ecsTaskExecutionRole # update to the relevant task execution role
    mem_limit: 4096 # update if needed
    cpu_limit: 2048 # update if needed
        - "<Update>" # update
        - "<Update>" # update
      assign_public_ip: ENABLED
      name: traceableai
      vpc: "<Update>" # update if needed

Include public subnets in the $SUBNETS section of the ecs-params.yml file.

Configure docker-compose.yml file

The docker-compose.yml file installs the traceable-agent service. The docker-compose file always fetches the latest version of the traceable-agent from Traceable’s docker hub repository. Following is a sample docker-compose.yml file:

version: '3'
    image: traceableai/traceable-agent:latest
      - "/traceable-agent"
      - "--config=/conf/agent/agentconfig.yaml"
      - "--pluginspath"
      - "/plugins"
      - "5441:5441" # GRPC
      - "5442:5442" # HTTP
      - "8181:8181" # OPA
      - "4317:4317" # OTEL
      - "9411:9411" # Zipkin HTTP
      driver: awslogs
        awslogs-region: <update> # Update
        awslogs-group: <update> #Update
        awslogs-stream-prefix: traceable-platform # Update if needed 
      - TA_REFRESH_TOKEN=<update> # Update
      - TA_ENVIRONMENT=<update> # Update

The following table explains the various parameters of the docker-compose.yml file:



Configure the following port numbers for traceable-agent:

  • 5441
  • 5442
  • 4317
  • 9411
  • 8181

The ports for traceable-agent are for:

  • traceable-agent GRPC
  • traceable-agent REST
  • OpenTelemetry (OTLP)
  • Zipkin HTTP
  • Open Policy Agent (OPA)
TA_REFRESH_TOKENUse the token generated in the Prerequisite section.
TA_ENVIRONMENTUsed to segregate environments in the Traceable dashboard, for example, development, QA, and so on.

Run the following command after ecs-params.yml and docker-compose.yml files are configured:

ecs-cli compose --project-name <PROJECT_NAME> service up --cluster-config <CLUSTER_CONFIG> --ecs-profile $CLUSTER_PROFILE --enable-service-discovery

For more information about the various parameters of the command, see ecs-cli compose.

Shut down the service

If you want to shut down the service, enter the following command:

ecs-cli compose --project-name traceable-agent service down


If you are managing your cluster with Terraform, here is an example task definition resource:

variable "log" {
    description = "A log group to stream log data to"
    type        = string
    default     = "traceable-ecs"

resource "aws_cloudwatch_log_group" "traceable-log-group" {
    name = var.log

    tags = {
        Environment = "${env}"
        Application = "traceableai"

resource "aws_ecs_task_definition" "traceable-agent" {
    family                = "traceable-agent"
    container_definitions = <<DEFINITION
    "name": "traceable-agent",
    "image": "traceableai/traceable-agent:latest",
    "essential": true,
    "logConfiguration": {
      "logDriver": "awslogs",
      "options": {
        "awslogs-group": "${var.log}",
        "awslogs-region": "${var.aws_region}",
        "awslogs-stream-prefix": "ecs"
    "command": ["/traceable-agent", "--config=/conf/agent/agentconfig.yaml", "--pluginspath", "/plugins"],
    "portMappings": [
        "hostPort": 5441,
        "protocol": "tcp",
        "containerPort": 5441
        "hostPort": 5442,
        "protocol": "tcp",
        "containerPort": 5442
        "hostPort": 4317,
        "protocol": "tcp",
        "containerPort": 4317
        "hostPort": 9411,
        "protocol": "tcp",
        "containerPort": 9411
        "hostPort": 8181,
        "protocol": "tcp",
        "containerPort": 8181
    "environment": [
        "name": "TA_REFRESH_TOKEN",
        "value": "${var.token}"
        "name": "TA_ENVIRONMENT",
        "value": "${var.environment}"
        "name": "GOGC",
        "value": "80"
        "name": "GODEBUG",
        "value": "madvdontneed=1"
    "memory": 100,
    "cpu": 1 

Next Steps

Was this article helpful?

What's Next