AWS ECS-EC2 (Windows) using OpenTelemetry

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 for details.

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

Prerequisites

• Coralogix account
• AWS account with AWS credentials configured
• aws-cli 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)
• Terraform module (ecs-ec2-windows)
• Telemetry-shippers (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. 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. 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 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

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:

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 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 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 – 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.

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

# 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

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 [email protected].