This guide describes how to deploy the OpenTelemetry Collector to **AWS ECS on EC2 with Windows** container instances. The agent runs as a **Daemon** ECS service (one task per Windows host), uses **awsvpc** network mode, mounts `C:\` and `C:\ProgramData\Amazon\ECS` for ECS metadata, and sends logs to CloudWatch via **awslogs**. This integration is **not** intended for Fargate or Linux ECS clusters.

Telemetry is sent to Coralogix via the Coralogix Exporter, with support for dynamic `application` and `subsystem` names (`application_name_attributes`, `subsystem_name_attributes`). See the [Coralogix Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/coralogixexporter) for details.

## Comparison: ECS-EC2 (Linux) vs ECS-EC2 (Windows)

| Aspect                        | ecs-ec2 (Linux)                                                     | ecs-ec2-windows                                                                 |
| ----------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| **OS / cluster**              | Amazon Linux 2 (EC2 ECS-optimized)                                  | Windows Server 2022 Core (EC2 ECS-optimized)                                    |
| **Network mode**              | `host` (agent shares instance network)                              | `awsvpc` (agent gets its own ENI)                                               |
| **Subnets / security groups** | Not required (host mode)                                            | **Required** (`SubnetIds`, `SecurityGroupIds`)                                  |
| **Agent task**                | Privileged; host mounts (`/var/lib/docker`, `/var/run/docker.sock`) | Not privileged; mounts `C:\`, `C:\ProgramData\Amazon\ECS`                       |
| **Agent image**               | Linux tags (e.g. `v0.5.0`)                                          | **Windows** tags (e.g. `v0.5.10-windowsserver-2022`)                            |
| **Service discovery**         | —                                                                   | Required Cloud Map so other tasks reach agent via DNS (`agent.otel.local:4317`) |
| **Logging**                   | `json-file` (host)                                                  | **awslogs** (CloudWatch); template/module can create log group                  |
| **Logs pipeline**             | `filelog` (Docker container logs) + `otlp`                          | **OTLP only** (no filelog; Windows containers don’t expose logs as host files)  |
| **ECS container metrics**     | `awsecscontainermetricsd` (daemon: Docker API + ECS metadata)       | `awsecscontainermetricsd` with **sidecar: true** (ECS Task Metadata only)       |
| **resourcedetection**         | `system` + `env`                                                    | **env** only (system detector not used on Windows); `host.id` from EC2 detector |
| **OpAMP**                     | Enabled (Fleet Management)                                          | **Disabled** (extension not supported on Windows)                               |
| **Health check**              | `/healthcheck` binary                                               | **CMD /C exit 0** (Windows)                                                     |

## Prerequisites

- [Coralogix account](https://signup.coralogix.com/#/)
- [AWS account](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-creating.html) with [AWS credentials configured](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-credentials.html)
- [aws-cli](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) if the deployment is done via CloudFormation
- **Existing** ECS cluster with **Windows** EC2 capacity (e.g. `WINDOWS_SERVER_2022_CORE`)
- Subnets and security groups for the Daemon service (awsvpc); outbound allowed for Coralogix and optional S3/Secrets Manager
- AWS Cloud Map (Service Discovery) with pre-configured Private DNS Namespace and Service for OTEL-Agent

Deploy the Coralogix OTEL agent using one of following methods:

- [CloudFormation (ecs-ec2-windows)](https://github.com/coralogix/cloudformation-coralogix-aws/tree/master/opentelemetry/ecs-ec2-windows)
- [Terraform module (ecs-ec2-windows)](https://github.com/coralogix/terraform-coralogix-aws/tree/master/modules/ecs-ec2-windows)
- [Telemetry-shippers (otel-ecs-ec2-windows)](https://github.com/coralogix/telemetry-shippers/tree/master/otel-ecs-ec2-windows) – extended Terraform example that provisions the Windows ECS cluster, ASG, agent, Service Discovery, and a sample workload

## Image

This implementation uses the **Coralogix OpenTelemetry Collector** image [coralogixrepo/coralogix-otel-collector](https://hub.docker.com/r/coralogixrepo/coralogix-otel-collector/tags). You **must** use a **Windows** image tag (e.g. `v0.5.10-windowsserver-2022`). Linux tags are not compatible with Windows ECS tasks.

Tags can be found [here](https://hub.docker.com/r/coralogixrepo/coralogix-otel-collector/tags). The image supports OTLP on **HTTP (4318)** and **gRPC (4317)**.

## Configuration sources

The agent can load its OpenTelemetry configuration from:

| Source                 | Description                                                                                                                                                                                                                             |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **template** (default) | Built-in Windows OTEL config in the CloudFormation template or Terraform module. Domain, application name, and subsystem come from parameters/variables; API key from env or Secrets Manager.                                           |
| **s3**                 | Load config from an S3 object at runtime. Provide `S3ConfigBucket` and `S3ConfigKey` (CloudFormation) or `s3_config_bucket` and `s3_config_key` (Terraform). The stack can create a task role with S3 read, or you can supply your own. |
| **parameter-store**    | Load config from SSM Parameter Store. Provide `CustomConfigParameterStoreName` (CloudFormation) or `custom_config_parameter_store_name` (Terraform) and a task execution role with Parameter Store read access.                         |

The built-in template config is Windows-optimized.

## Deploy OTEL agent ECS task definition & service

Deploy a task definition and ECS Daemon service so the OpenTelemetry Collector runs on every Windows EC2 instance in the cluster.

### Option 1: CloudFormation template

Deploy the [ecs-ec2-windows CloudFormation template](https://github.com/coralogix/cloudformation-coralogix-aws/tree/main/opentelemetry/ecs-ec2-windows) with the required parameters.

**Required parameters**

| Parameter                       | Description                                                                               |
| ------------------------------- | ----------------------------------------------------------------------------------------- |
| **ClusterName**                 | Name of the existing Windows ECS cluster                                                  |
| **SubnetIds**                   | Comma-separated subnet IDs for the ECS service (awsvpc)                                   |
| **SecurityGroupIds**            | Comma-separated security group IDs for the ECS service                                    |
| **ServiceDiscoveryRegistryArn** | Cloud Map service ARN so other tasks can reach agent via DNS (e.g. agent.otel.local:4317) |
| **CoralogixRegion**             | Coralogix region: EU1, EU2, AP1, AP2, AP3, US1, US2, or custom                            |
| **CoralogixApiKey**             | Send-Your-Data API key (required unless UseApiKeySecret is true)                          |

**Optional / commonly used parameters**

| Parameter                      | Description                                                                                      | Default                      |
| ------------------------------ | ------------------------------------------------------------------------------------------------ | ---------------------------- |
| ConfigSource                   | Config source: `template`, `s3`, `parameter-store`                                               | `template`                   |
| CDOTImageVersion               | OTEL Collector **Windows** image tag                                                             | `v0.5.10-windowsserver-2022` |
| Image                          | Override image repository (empty = coralogixrepo/coralogix-otel-collector)                       | `""`                         |
| CustomDomain                   | Coralogix custom domain (required when region is custom)                                         | `""`                         |
| UseApiKeySecret                | Use API key from Secrets Manager                                                                 | `false`                      |
| ApiKeySecretArn                | ARN of the secret (required if UseApiKeySecret is true)                                          | `""`                         |
| TaskExecutionRoleArn           | Task execution role (ECR, logs, Secrets/SSM). If empty, a role is created                        | `""`                         |
| TaskRoleArn                    | Task role for runtime (e.g. S3 config). If empty and ConfigSource=s3, minimal S3 role is created | `""`                         |
| S3ConfigBucket                 | S3 bucket for config (required when ConfigSource=s3)                                             | `""`                         |
| S3ConfigKey                    | S3 key for config (required when ConfigSource=s3)                                                | `""`                         |
| CustomConfigParameterStoreName | SSM Parameter Store name (required when ConfigSource=parameter-store)                            | `""`                         |
| DefaultApplicationName         | Default Coralogix application name                                                               | `otel`                       |
| DefaultSubsystemName           | Default Coralogix subsystem name                                                                 | `ecs-ec2`                    |
| Cpu                            | Task CPU units (1024 = 1 vCPU)                                                                   | `1024`                       |
| Memory                         | Task memory (MiB)                                                                                | `2048`                       |
| CloudWatchLogGroupName         | CloudWatch log group name; if empty, one is created                                              | `""`                         |
| CloudwatchLogRetentionDays     | Retention for the created log group                                                              | `7`                          |
| HealthCheckEnabled             | Enable container health check (Windows: CMD /C exit 0)                                           | `false`                      |
| EnableHeadSampler              | Enable head sampling (template config)                                                           | `true`                       |
| SamplingPercentage             | Sampling percentage 0–100 (template config)                                                      | `10`                         |
| SamplerMode                    | Sampler mode: proportional, equalizing, hash_seed                                                | `proportional`               |
| EnableSpanMetrics              | Enable span metrics (template config)                                                            | `true`                       |
| EnableTracesDB                 | Enable traces/db pipeline (template config)                                                      | `false`                      |

**Example deployment**

```bash
aws cloudformation deploy --template-file template.yaml --stack-name coralogix-otel-windows \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameter-overrides \
    ClusterName=my-windows-ecs-cluster \
    "SubnetIds=subnet-xxx,subnet-yyy" \
    "SecurityGroupIds=sg-xxx" \
    "ServiceDiscoveryRegistryArn=arn:aws:servicediscovery:eu-central-1:123456789012:service/srv-examplearn123456" \
    CoralogixRegion=EU2 \
    CoralogixApiKey=your-send-your-data-api-key
```

After deployment, verify the agent is running:

```bash
aws ecs list-tasks --cluster my-windows-ecs-cluster --service-name <service-name-from-stack>
```

### Option 2: Terraform module

The [ECS EC2 (Windows) OpenTelemetry Agent Terraform module](https://github.com/coralogix/terraform-coralogix-aws/tree/master/modules/ecs-ec2-windows) deploys the OTEL agent as an ECS Daemon service on an **existing** Windows ECS cluster.

**Key inputs**

| Name                           | Description                                                            | Required |
| ------------------------------ | ---------------------------------------------------------------------- | -------- |
| ecs_cluster_name               | Name of the existing Windows ECS cluster                               | ✓        |
| subnet_ids                     | Subnet IDs for the ECS service (awsvpc)                                | ✓        |
| security_group_ids             | Security group IDs for the ECS service                                 | ✓        |
| image_version                  | OTEL Collector **Windows** image tag (e.g. v0.5.10-windowsserver-2022) | ✓        |
| coralogix_region               | Coralogix region (EU1, EU2, AP1, AP2, AP3, US1, US2, custom)           | ✓        |
| service_discovery_registry_arn | Cloud Map service ARN for agent DNS (e.g. agent.otel.local:4317)       | ✓        |
| api_key                        | Send-Your-Data API key (required unless use_api_key_secret is true)    | \*       |
| use_api_key_secret             | Use API key from Secrets Manager                                       |          |
| api_key_secret_arn             | ARN of the secret (required if use_api_key_secret is true)             |          |
| config_source                  | template, s3, parameter-store                                          |          |
| task_execution_role_arn        | Task execution role (if null, one is created)                          |          |
| default_application_name       | Default Coralogix application name                                     |          |
| default_subsystem_name         | Default Coralogix subsystem name                                       |          |

See the [module README](https://github.com/coralogix/terraform-coralogix-aws/tree/master/modules/ecs-ec2-windows) for full inputs, outputs, and usage examples (template config, S3 config, Parameter Store, Secrets Manager).

### Option 3: Telemetry-shippers (full infrastructure)

For a **complete example** that creates the Windows ECS cluster, launch template, ASG, agent Daemon service, **Service Discovery** (private DNS `otel.local`, service `agent`), and a sample telemetrygen workload, use **[otel-ecs-ec2-windows](https://github.com/coralogix/telemetry-shippers/tree/master/otel-ecs-ec2-windows)** – Terraform in `terraform/` plus Helm/Make. The agent registers in Cloud Map so other tasks can reach it at `agent.otel.local:4317`.

This is the recommended reference for “infra from scratch” and for understanding Service Discovery with the Windows agent.

## Configure the application container to send identifying resource attributes

Instrumented applications can add attribute name/value pairs via the [`OTEL_RESOURCE_ATTRIBUTES` environment variable](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes).

For example, to include the container ID (from the ECS container metadata endpoint):

```bash
# Run within an ECS container; requires jq
containerID=$(curl -s ${ECS_CONTAINER_METADATA_URI_V4} | jq '.DockerId' -r)
export OTEL_RESOURCE_ATTRIBUTES="containerID=${containerID},$OTEL_RESOURCE_ATTRIBUTES"
```

Set `OTEL_RESOURCE_ATTRIBUTES` at container startup (e.g. in the task definition or entrypoint).

## Additional resources

| Resource                                | Link                                                                                                                                                                       |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CloudFormation (ecs-ec2-windows)        | [GitHub – cloudformation-coralogix-aws/opentelemetry/ecs-ec2-windows](https://github.com/coralogix/cloudformation-coralogix-aws/tree/master/opentelemetry/ecs-ec2-windows) |
| Terraform module (ecs-ec2-windows)      | [GitHub – terraform-coralogix-aws/modules/ecs-ec2-windows](https://github.com/coralogix/terraform-coralogix-aws/tree/master/modules/ecs-ec2-windows)                       |
| Telemetry-shippers (full infra example) | [GitHub – telemetry-shippers/otel-ecs-ec2-windows](https://github.com/coralogix/telemetry-shippers/tree/master/otel-ecs-ec2-windows)                                       |
| Coralogix APM                           | [APM onboarding](https://coralogix.com/docs/user-guides/apm/getting-started/apm-onboarding-tutorial/index.md)                                                              |
| APM using Amazon EC2                    | [APM Amazon EC2](https://coralogix.com/docs/integrations/aws/apm-amazon-ec2/index.md)                                                                                      |

## Support

**Need help?**

Our world-class customer success team is available 24/7 to walk you through your setup and answer any questions that may come up.

Contact us **via our in-app chat** or by emailing [support@coralogix.com](mailto:support@coralogix.com).