Skip to main content
The Odigos VM Agent is available as part of Odigos Pro. For access and licensing details, contact us.
On ECS the task definition is the configuration surface. On a fresh container instance it is the only input the agent has, so the Central endpoint and any other defaults travel inside it — nothing depends on service discovery or a pre-provisioned file. Everything beyond bootstrap — sources, destinations, actions, and instrumentation rules — is managed from Odigos Central or with odictl, exactly as on any VM Agent.

​
Agent environment variables

:443 in an endpoint implies wss. The connection is outbound-only, so a public Central endpoint or one in a different AWS account works with no inbound rules on the cluster.

​
Platform naming per mode

The agent’s name depends on the topology so each mode displays naturally in the Central UI: ODIGOS_AGENT_NAME overrides both. In Agent-only mode, if the cluster cannot be determined (task metadata unavailable), the agent falls back to the hostname and logs a warning. Both modes register with platform type aws.ecs, so a cluster presents consistently in Central either way.

​
Configuration precedence and persistence

ODIGOS_DEFAULT_CONFIG is a default, not an override. Precedence, lowest to highest:
1

Built-in ECS distribution defaults

The baseline shipped in the image.
2

Discrete env vars

ODIGOS_CENTRAL_ENDPOINT, ODIGOS_AGENT_NAME, and so on.
3

ODIGOS_DEFAULT_CONFIG

The inline document from the task definition.
4

The persisted config.yaml

Whatever Central or odictl has written. This wins on every boot after the first.
The config tree persists on the container instance at /etc/odigos-ecs-agent (a host bind mount), so the agent keeps its deployment identity and configuration across task restarts and image upgrades.
Because the persisted config.yaml takes precedence, editing ODIGOS_DEFAULT_CONFIG does not change a value that has already been persisted. To change a seeded value after first boot, update it through Central or odictl — or clear the persisted config on the instance so the new default is applied again.

​
Proxy environment variables

The proxy is unprivileged — no host PID, no Docker socket, no host mounts.

​
What the proxy does with requests

The journal replays config mutations to agents that connect later, so a node that joins the cluster — or a task that migrates to a fresh instance — converges to the cluster configuration automatically. Each agent’s replay position is tracked by its stable deployment id, so a reconnecting agent replays only what it missed.

​
Membership and lifecycle events

  • Agent connects and disconnects are logged and forwarded to Central as ecs-proxy.agent-lifecycle events; departed agents keep a tombstone (id, node, last seen).
  • Coverage changes are logged and forwarded as ecs-proxy.coverage events.
  • GET /healthz on port 4321 returns the whole view: connected agents, departed tombstones, and the last coverage result. See checking the healthz endpoint.

​
What gets instrumented

The agent’s own binaries, the amazon-ecs-agent, the SSM agent, and awsvpc pause containers are excluded from instrumentation automatically.

​
How the collector runs

As in the Docker deployment, there is no systemd inside the container:
  • odigos-otelcol runs as a supervised child process of the agent, so its lifecycle follows the agent task.
  • Agent and collector share the task’s stdout, captured by the awslogs driver into the /odigos/ecs-agent log group.
  • With host networking, the collector and OpAMP server listen on the instance’s network namespace, reachable by instrumented tasks on localhost or the instance IP.
  • Collector logs are JSON-formatted on ECS; the awslogs driver ships them to CloudWatch Logs as the primary log stream.
  • systemd memory limits do not apply — cap the agent with the task definition’s cpu, memory, and memoryReservation instead.

​
Instrumentation file sync

The image bakes the Java instrumentation files into a staging directory. On startup the agent rsyncs them onto the container instance’s /var/odigos (the task definition bind mount), and seeds them into a workload’s container namespace when it attaches. Go, C++, and the OBI fallback are compiled into the agent binary and need no on-disk files. This is why /var/odigos must be a writable host mount. The full list of elevated task settings is under required permissions.