Step 1: Enable Application Signals
in your account
If you haven't enabled Application Signals in this account yet, you must grant Application Signals the permissions it needs to discover your services. To do so, do the following. You need to do this only once for your account.
To enable Application Signals for your applications
Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/
. In the navigation pane, choose Services.
Choose Start discovering your Services.
Select the check box and choose Start discovering Services.
Completing this step for the first time in your account creates the AWSServiceRoleForCloudWatchApplicationSignals service-linked role. This role grants Application Signals the following permissions:
-
xray:GetServiceGraph
-
logs:StartQuery
-
logs:GetQueryResults
-
cloudwatch:GetMetricData
-
cloudwatch:ListMetrics
-
tag:GetResources
For more information about this role, see Service-linked role permissions for CloudWatch Application Signals.
-
Step 2: Create IAM roles
You must create an IAM role. If you already have created this role, you might need to add permissions to it.
-
ECS task role— Containers use this role to run. The permissions should be whatever your applications need, plus CloudWatchAgentServerPolicy.
For more information about creating IAM roles, see Creating IAM Roles.
Step 3: Prepare CloudWatch agent configuration
First, prepare the agent configuration with Application Signals enabled. To do this, create a local file
named
/tmp/ecs-cwagent.json
.
{
"traces": {
"traces_collected": {
"application_signals": {}
}
},
"logs": {
"metrics_collected": {
"application_signals": {}
}
}
}
Then upload this configuration to the SSM Parameter Store. To do this, enter the
following command. In the file, replace $REGION
with your
actual Region name.
aws ssm put-parameter \ --name "ecs-cwagent" \ --type "String" \ --value "`cat /tmp/ecs-cwagent.json`" \ --region "
$REGION
"
Step 4:
Instrument your application with the CloudWatch agent
The next step is to instrument your application for CloudWatch Application Signals.
To instrument your application on Amazon ECS with the CloudWatch agent
First, specify a bind mount. The volume will be used to share files across containers in the next steps. You will use this bind mount later in this procedure.
"volumes": [ { "name": "opentelemetry-auto-instrumentation" } ]
Add a CloudWatch agent sidecar definition. To do this, append a new container called
ecs-cwagent
to your application's task definition. Replace$REGION
with your actual Region name. Replace$IMAGE
with the path to the latest CloudWatch container image on Amazon Elastic Container Registry. For more information, see cloudwatch-agenton Amazon ECR. If you want to enable the CloudWatch agent with a daemon strategy instead, see the instructions at Deploy using the daemon strategy.
{ "name": "ecs-cwagent", "image": "
$IMAGE
", "essential": true, "secrets": [ { "name": "CW_CONFIG_CONTENT", "valueFrom": "ecs-cwagent" } ], "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-create-group": "true", "awslogs-group": "/ecs/ecs-cwagent", "awslogs-region": "$REGION
", "awslogs-stream-prefix": "ecs" } } }Append a new container
init
to your application's task definition. Replace$IMAGE
with the latest image from the AWS Distro for OpenTelemetry Amazon ECR image repository. { "name": "init", "image": "
$IMAGE
", "essential": false, "command": [ "cp", "/javaagent.jar", "/otel-auto-instrumentation/javaagent.jar" ], "mountPoints": [ { "sourceVolume": "opentelemetry-auto-instrumentation", "containerPath": "/otel-auto-instrumentation", "readOnly": false } ] }Add a dependency on the
init
container to make sure that this container finishes before your application container starts."dependsOn": [ { "containerName": "init", "condition": "SUCCESS" } ]
Add the following environment variables to your application container. You must be using version 1.32.2 or later of the AWS Distro for OpenTelemetry auto-instrumentation agent for Java
. Environment variable Setting to enable Application Signals OTEL_RESOURCE_ATTRIBUTES
Specify the following information as key-value pairs:
service.name
sets the name of the service. This will be diplayed as the service name for your application in Application Signals dashboards. If you don't provide a value for this key, the default ofUnknownService
is used.deployment.environment
sets the environment that the application runs in. This will be diplayed as the Hosted In environment of your application in Application Signals dashboards. If you don't specify this, the default ofgeneric:default
is used.
This attribute key is used only by Application Signals, and is converted into X-Ray trace annotations and CloudWatch metric dimensions.
(Optional) To enable log correlation for Application Signals, set an additional environment variable
aws.log.group.names
to be the log group name for your application log. By doing so, the traces and metrics from your application can be correlated with the relevant log entries from the log group. For this variable, replace$YOUR_APPLICATION_LOG_GROUP
with the log group names for your application. If you have multiple log groups, you can use an ampersand (&
) to separate them as in this example:aws.log.group.names=log-group-1&log-group-2
. To enable metric to log correlation, setting this current environmental variable is enough. For more information, see Enable metric to log correlation. To enable trace to log correlation, you'll also need to change the logging configuration in your application. For more information, see Enable trace to log correlation.OTEL_AWS_APPLICATION_SIGNALS_ENABLED
Set to
true
to have your container start sending X-Ray traces and CloudWatch metrics to Application Signals.OTEL_METRICS_EXPORTER
Set to
none
to disable other metrics exporters.OTEL_LOGS_EXPORTER
Set to
none
to disable other logs exporters.OTEL_EXPORTER_OTLP_PROTOCOL
Set to
http/protobuf
to send metrics and traces to Application Signals using HTTP.OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT
Set to
http://localhost:4316/v1/metrics
to send metrics to the CloudWatch sidecar.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
Set to
http://localhost:4316/v1/traces
to send traces to the CloudWatch sidecar.OTEL_TRACES_SAMPLER
Set this to
xray
to set X-Ray as the traces sampler.OTEL_PROPAGATORS
Set
xray
as one of the propagators.JAVA_TOOL_OPTIONS
Set to
" -javaagent:$
ReplaceAWS_ADOT_JAVA_INSTRUMENTATION_PATH
"AWS_ADOT_JAVA_INSTRUMENTATION_PATH
with the path where the AWS Distro for OpenTelemetry Java auto-instrumentation agent is stored. For example,/otel-auto-instrumentation/javaagent.jar
Mount the volume
opentelemetry-auto-instrumentation
that you defined in step 1 of this procedure. If you don't need to enable log correlation with metrics and traces, use the following example for a Java application. If you want to enable log correlation, see the next step instead.{ "name": "
my-app
", ... "environment": [ { "name": "OTEL_RESOURCE_ATTRIBUTES", "value": "service.name=$SVC_NAME
" }, { "name": "OTEL_LOGS_EXPORTER", "value": "none" }, { "name": "OTEL_METRICS_EXPORTER", "value": "none" }, { "name": "OTEL_EXPORTER_OTLP_PROTOCOL", "value": "http/protobuf" }, { "name": "OTEL_AWS_APPLICATION_SIGNALS_ENABLED", "value": "true" }, { "name": "JAVA_TOOL_OPTIONS", "value": " -javaagent:/otel-auto-instrumentation/javaagent.jar" }, { "name": "OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT", "value": "http://localhost:4316/v1/metrics" }, { "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "value": "http://localhost:4316/v1/traces" }, { "name": "OTEL_TRACES_SAMPLER", "value": "xray" }, { "name": "OTEL_PROPAGATORS", "value": "tracecontext,baggage,b3,xray" } ], "dependsOn": [ { "containerName": "init", "condition": "SUCCESS" } ], "mountPoints": [ { "sourceVolume": "opentelemetry-auto-instrumentation", "containerPath": "/otel-auto-instrumentation", "readOnly": false } ] }
Step 5:
Deploy your application
Create a new revision of your task definition and deploy it to your application cluster. You should see three containers in the newly created task:
init
– A required container for initializing Application Signals.ecs-cwagent
– A container running the CloudWatch agent
– This is the example application container in our documentation. In your actual workloads, this specific container might not exist or might be replaced with your own service containers.my-app