ECS Fargate Instrumentation

This guide explains how to enable OTEL auto-instrumentation for Python applications running on Amazon ECS Fargate so traces are exported to the Motadata Collector.

Amazon ECS Fargate does not use a Kubernetes control plane, so instrumentation for ECS Fargate happens inside the ECS Task Definition instead of through the Motadata Operator. The application container installs the OTEL Python packages at startup and exports traces to the Motadata Server over OTLP HTTP on port 4318. Only Python applications are currently supported for ECS Fargate.

Prerequisites

AWS Requirements

The ECS task must have network connectivity to the Motadata Server.
Port 4318 must be reachable from the ECS task to the Motadata Server.

Application Requirements

The application must be a Python application.
The application container must have pip available.
The container must have access to the Python package repository required to install OTEL packages.

Configuration Steps

Step 1: Identify the Existing Application Startup Command

Before modifying the ECS Task Definition, identify how the Python application is currently started. The startup command is defined in the ECS Task Definition or in the Dockerfile as ENTRYPOINT or CMD.

For example, an existing application may be started using:

python app.py

or:

gunicorn app:app

or:

uvicorn app:app --host 0.0.0.0 --port 5000

Preserve the existing startup command when adding OTEL instrumentation.

Step 2: Modify the ECS Task Definition

Open the ECS Task Definition and modify the application container's entryPoint and command.

Set the entry point to:

"entryPoint": ["sh", "-c"]

Set the command to:

"command": [
  "pip install --no-cache-dir opentelemetry-distro opentelemetry-exporter-otlp && opentelemetry-bootstrap -a install && opentelemetry-instrument python app.py"
]

The command performs three operations.

Install OTEL packages

pip install --no-cache-dir \
    opentelemetry-distro \
    opentelemetry-exporter-otlp

Installs the OTEL distribution and OTLP exporter.

Install instrumentation packages

opentelemetry-bootstrap -a install

Detects the Python packages installed in the application environment and installs the corresponding OTEL instrumentation packages. For example, if the application uses Flask, Django, Requests, or SQLAlchemy, the appropriate instrumentation packages install automatically when supported.

Start the application with OTEL

opentelemetry-instrument python app.py

Starts the application with OTEL auto-instrumentation enabled.

Step 3: Configure OTEL Environment Variables

Add the following environment variables to the application container.

Environment Variable	Purpose	Example Value
`OTEL_SERVICE_NAME`	The service name that appears in Motadata APM.	`payment-service`
`OTEL_TRACES_EXPORTER`	Enables the OTLP trace exporter.	`otlp`
`OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`	Sends traces using OTLP over HTTP with Protobuf.	`http/protobuf`
`OTEL_EXPORTER_OTLP_ENDPOINT`	The Motadata Collector endpoint. Replace `<MOTADATA-SERVER-IP>` with the Motadata Server IP.	`http://<MOTADATA-SERVER-IP>:4318`
`OTEL_LOGS_EXPORTER`	Disables the log exporter when only traces are required.	`none`
`OTEL_METRICS_EXPORTER`	Disables the metric exporter when only traces are required.	`none`

Step 4: Example ECS Container Configuration

The resulting container configuration looks similar to the following:

{
    "family": "motadata-python-app",
    "containerDefinitions": [
        {
            "name": "Main",
            "image": "<PYTHON_APPLICATION_IMAGE>",
            "cpu": 0,
            "portMappings": [
                {
                    "containerPort": 5000,
                    "hostPort": 5000,
                    "protocol": "tcp",
                    "name": "python-app-port",
                    "appProtocol": "http"
                }
            ],
            "essential": true,
            "entryPoint": [
                "sh",
                "-c"
            ],
            "command": [
                "pip install --no-cache-dir opentelemetry-distro opentelemetry-exporter-otlp && opentelemetry-bootstrap -a install && opentelemetry-instrument python app.py"
            ],
            "environment": [
                {
                    "name": "OTEL_SERVICE_NAME",
                    "value": "client-python-app"
                },
                {
                    "name": "OTEL_LOGS_EXPORTER",
                    "value": "none"
                },
                {
                    "name": "OTEL_METRICS_EXPORTER",
                    "value": "none"
                },
                {
                    "name": "OTEL_EXPORTER_OTLP_TRACES_PROTOCOL",
                    "value": "http/protobuf"
                },
                {
                    "name": "OTEL_TRACES_EXPORTER",
                    "value": "otlp"
                },
                {
                    "name": "OTEL_EXPORTER_OTLP_ENDPOINT",
                    "value": "http://<MOTADATA-SERVER-IP>:4318"
                }
            ],
            "mountPoints": [],
            "volumesFrom": [],
            "logConfiguration": {
                "logDriver": "awslogs",
                "options": {
                    "awslogs-group": "/ecs/ashish-python-app",
                    "awslogs-create-group": "true",
                    "awslogs-region": "ap-south-1",
                    "awslogs-stream-prefix": "ecs"
                }
            },
            "systemControls": []
        }
    ],
    "executionRoleArn": "arn:aws:iam::590183921937:role/ecsTaskExecutionRole",
    "networkMode": "awsvpc",
    "volumes": [],
    "placementConstraints": [],
    "requiresCompatibilities": [
        "FARGATE"
    ],
    "cpu": "1024",
    "memory": "3072",
    "runtimePlatform": {
        "cpuArchitecture": "X86_64",
        "operatingSystemFamily": "LINUX"
    },
    "enableFaultInjection": false
}

info

Replace python app.py in the command block with the application's original startup command from Step 1.

If the original command is gunicorn -w 4 app:app, use opentelemetry-instrument gunicorn -w 4 app:app.

If the original command is uvicorn app:app --host 0.0.0.0 --port 5000, use opentelemetry-instrument uvicorn app:app --host 0.0.0.0 --port 5000.

Step 5: Register a New Task Definition Revision

Register the modified Task Definition as a new revision so the updated container settings are available to the ECS service.

Step 6: Update the ECS Service

Update the ECS service to use the new Task Definition revision. The service replaces the existing tasks with tasks that run the OTEL-instrumented container.

Step 7: Generate Application Traffic

Send requests to the application so the instrumented code path runs and traces are exported to the Motadata Collector. The traces appear in the APM Explorer screen once collection begins.

Prerequisites​

Configuration Steps​

Prerequisites

Configuration Steps