ECS Serverless Collection Agent - Install

This guide walks you through installing the sidecar container to collect metrics, traces, and logs from your ECS Serverless infrastructure.

Prerequisites Check

Before starting, verify you have:

• ECS cluster with any launch type (Fargate)
• AWS CLI configured with appropriate permissions
• SigNoz Cloud account or self-hosted SigNoz instance
• Access to AWS Parameter Store and CloudWatch Logs

Installation Steps

Step 1: Create SigNoz OtelCollector Config

The OpenTelemetry Collector configuration defines what data to collect and where to send it.

Step 2: Create Sidecar Collector Container

This step involves integrating the SigNoz collector into your ECS task definitions as a sidecar container. The sidecar collector container will run alongside your application container(s) within the same ECS task and will collect ECS container metrics and send them to SigNoz.

2a. Update Task Definition

In your ECS task definition, include a new container definition specifically for the sidecar container. This container will operate alongside your main application container(s) within the same task definition:

{
    ...
    "containerDefinitions": [
        ...,
        {
            "name": "signoz-collector",
            "image": "otel/opentelemetry-collector-contrib:0.139.0",
            "user": "root",
            "command": [
                "--config=env:SIGNOZ_CONFIG_CONTENT"
            ],
            "secrets": [
                {
                "name": "SIGNOZ_CONFIG_CONTENT",
                "valueFrom": "/ecs/signoz/otelcol-sidecar.yaml"
                }
            ],
            "memory": 1024,
            "cpu": 512,
            "essential": true,
            "portMappings": [
                {
                    "protocol": "tcp",
                    "containerPort": 4317
                },
                {
                    "protocol": "tcp",
                    "containerPort": 4318
                },
                {
                    "containerPort": 8006,
                    "protocol": "tcp"
                }
            ],
            "logConfiguration": {
                "logDriver": "awsfirelens",
                "options": {
                    "Name": "forward",
                    "Host": "127.0.0.1",
                    "Port": "8006",
                    "tls": "off"
                }
            }
        }
    ]
...
}

The sidecar container will run the SigNoz collector and includes essential components like the name ("signoz-collector"), image (e.g., "signoz/signoz-otel-collector:0.88.7"), and command for execution, alongside secrets for secure configuration. It also specifies memory and CPU resources, port mappings for network communication, a health check to ensure operational integrity, and log configuration for output management.

2b. Update ECS Task Execution Role

Your ECS Task Execution Role needs permission to read from SSM Parameter Store and write to CloudWatch Logs.

• Attach AmazonSSMReadOnlyAccess and CloudWatchLogsFullAccess managed policies, or
• Add an inline policy that allows ssm:GetParameter for your config and CloudWatch Logs actions.

2c. Update ECS Task Role

The ECS Task Role (not the execution role) should also have access to SSM Parameter Store and CloudWatch Logs if your app/sidecar needs it.

• Attach the same managed policies as above, or
• Use a minimal inline policy for just the required resources.

Step 3: Deploy the Task Definition

Deploy your updated ECS task definition as usual (update your service or run a new task). You should see SigNoz sidecar logs in CloudWatch Logs if everything is set up correctly.

Troubleshooting Installation

Common Issues

Task Not Starting:

• Check ECS cluster has available capacity
• Verify the container image can be pulled
• Review CloudWatch logs for the failed tasks

Parameter Store Access Issues:

• Ensure the IAM role has ssm:GetParameter permissions
• Verify the parameter name matches exactly: /ecs/signoz/otelcol-sidecar.yaml
• Check the parameter is in the same region as your ECS cluster

Container Health Check Failures:

• Verify the health check endpoint is accessible
• Check container logs for any startup errors
• Ensure proper port mappings are configured

Next Steps

• Configure the Sidecar Collection Agent in your ECS Cluster
• Learn more about Collection from Serverless
• Telemetry Data Requirements for Infrastructure Monitoring
• Collector Configuration Best Practices