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.

otelcol-sidecar parameter in AWS Parameter Store — *OTel Collector config in AWS Parameter Store*

Navigate to AWS Parameter Store and create a new parameter named /ecs/signoz/otelcol-sidecar.yaml.

Copy the following configuration and paste it into the value field of the /ecs/signoz/otelcol-sidecar.yaml parameter:

extensions:
  health_check:

receivers:
  awsecscontainermetrics:
    collection_interval: 30s
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
  fluentforward:
    endpoint: 0.0.0.0:8006

processors:
  batch:
    timeout: 10s
  filter:
    metrics:
      include:
        match_type: strict
        metric_names:
          - ecs.task.memory.reserved
          - ecs.task.memory.utilized
          - ecs.task.cpu.reserved
          - ecs.task.cpu.utilized
          - ecs.task.network.rate.rx
          - ecs.task.network.rate.tx
          - ecs.task.storage.read_bytes
          - ecs.task.storage.write_bytes
          - container.duration

exporters:
  otlp:
    endpoint: "ingest.{region}.signoz.cloud:443"
    headers:
      "signoz-ingestion-key": "SIGNOZ_INGESTION_KEY"

service:
  extensions: [health_check]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]
    metrics/aws:
      receivers: [awsecscontainermetrics]
      processors: [filter]
      exporters: [otlp]
    logs:
      receivers: [otlp, fluentforward]
      processors: [batch]
      exporters: [otlp]

Update the following placeholders in the YAML configuration:
- Replace SIGNOZ_INGESTION_KEY with your SigNoz Cloud ingestion key
- Replace {region} with your SigNoz Cloud region

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.109.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"
                }
            ],
            "healthCheck": {
                "command": [
                    "CMD-SHELL",
                    "wget -qO- http://localhost:13133/ || exit 1"
                ],
                "interval": 5,
                "timeout": 6,
                "retries": 5,
                "startPeriod": 1
            },
            "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.