Collector Ecs

The collector runs as a sidecar container in the same task. Under awsvpc networking all containers in a task share a network namespace, so the app reaches it on localhost:4318 with no port mapping and no service discovery. This mirrors how the CloudWatch Agent sidecar works in the Application Signals guides — same shape, different image and config.

Step 1: Grant the task permissions

Two roles, two different reasons. Mixing them up is the most common failure here.

• Task role — the collector’s runtime identity, needs arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy.
• Execution role — only needs ssm:GetParameters, and only if the config comes from Parameter Store (Step 2, option B). It is used to fetch the config before the container starts, not to send telemetry.

CloudWatchAgentServerPolicy is the grant for the destination — CloudWatch’s own per-signal OTLP endpoints.

A collector that starts cleanly and then logs AccessDenied on every export is this policy on the wrong role.

Step 2: Add the sidecar container

Primary: the CloudWatch Agent sidecar

Image public.ecr.aws/cloudwatch-agent/cloudwatch-agent:<tag>, pinned to 1.300070.0b1586 or later (tags carry no v prefix and always carry a b#### build suffix — there is no v1.300070.1 tag) for the opentelemetry section. Do not float :latest, and do not assume a tag is new enough: an older agent reports configstatus: configured and status: running while starting no OTLP listener at all. Confirm from the task’s log stream that the collector logged its traces/metrics pipelines before believing it works. The whole config goes in CW_CONFIG_CONTENT, so no custom image and no SSM parameter are required:

jsonencode avoids the heredoc indentation hazard entirely — there is no YAML to mis-indent. Do not add any application_signals section; that is out of scope here.

The snippet above references a log group you must declare. Give the collector its own, so a failing collector is not invisible:

The execution role needs logs:CreateLogStream / logs:PutLogEvents on it — unless it already carries AmazonECSTaskExecutionRolePolicy, which grants both on * and is the common case for an existing ECS stack. Check before adding an inline policy. (CDK’s LogDrivers.awsLogs() adds the grant itself, which is why it shows up as an execution-role change in cdk diff.)

Also check the task-level cpu/memory: the init container and the collector are added inside the existing envelope, and a 256/512 task leaves too little for a real app. 512/1024 is the practical floor; 1024/2048 is comfortable for a small app plus init container plus collector. On Fargate the pair must remain one of the valid combinations, so a naive bump fails at deploy time.

The same sidecar in CDK TypeScript. The ECS language guides are written in CDK, so most readers need this form rather than the HCL above:

JSON.stringify is the CDK equivalent of jsonencode and sidesteps the indentation hazard the same way. Two traps in a verbatim HCL→CDK port: memoryReservation becomes memoryReservationMiB, and environment becomes an object rather than a list of name/value pairs. Also add the collector last, or at least after the app container — CDK’s defaultContainer (what a load-balancer target binds to) is the first essential container added.

Backup: upstream otelcol-contrib sidecar

Image: otel/opentelemetry-collector-contrib:<version> — the upstream contrib distribution (sigv4auth is a contrib component; the core image fails at startup without it). Pin a version from the releases page (opens in a new tab); do not float latest.

Upstream reads its config from a file or from an environment variable via --config=env:VAR, so no custom image is needed — put the YAML in a variable and point command at it.

Option A — inline config (simplest; the config is visible in the task definition):

Option B — config in SSM Parameter Store (keeps the task definition small, lets the config change without a new task revision):

essential = false matters: the collector is not the workload, and an essential container exiting kills the whole task.

Give the collector a log group of its own — without one, a failing collector is invisible.

Do not add dependsOn. The SDK retries, so the app can start first. A dependsOn with condition HEALTHY would additionally require a healthCheck on the collector container, and without one the task never starts at all.

Step 3: Point the application at the collector

On the application container, alongside the loader variable the ecs-*.md instrumentation guides add:

localhost is correct only under awsvpc. If the task uses bridge networking, the containers do not share a namespace — add a links entry from the app to the collector and address it by the collector’s container name instead — http://cloudwatch-agent:4318 on the primary path, http://otel-collector:4318 on the backup — and use that same name in links. Check network_mode before writing localhost; Fargate is always awsvpc.

OTEL_EXPORTER_OTLP_PROTOCOL is not optional — see collector.md.

Verify

The collector container — cloudwatch-agent on the primary path, otel-collector on the backup — should be RUNNING alongside the app, and the init container STOPPED with exit code 0.

Check you are reading the new revision. An apply that changes only service properties does not recycle running tasks, so confirm the task’s taskDefinitionArn is the revision you just created and the old deployment has drained before drawing conclusions from logs.

collector.md‘s curl checks on 4318 and 8888 are not reachable on Fargate — no host shell, and no route into the task’s network namespace unless you add enableExecuteCommand plus ssmmessages:* on the task role. The log stream below is the ECS substitute, and it is sufficient.

Then read its log stream: startup lines listing the traces and metrics pipelines mean the config parsed; 403, AccessDenied, or no such host mean it did not reach the destination.

Completion

Tell the user the sidecar was added to the task definition, which role got which policy and why, that the app now exports to localhost:4318, and that no application source or Dockerfile changed. Present the diff; do not deploy or update the service.