Enable Application Signals on Amazon EC2 - Amazon CloudWatch
Step 1: Enable Application Signals in your accountStep 2: Download and start the CloudWatch agentStep 3: Instrument your application and start it

Enable Application Signals on Amazon EC2

For applications running on Amazon EC2 or other instance types, you install and configure the CloudWatch agent and AWS Distro for OpenTelemetry yourself. On these architectures enabled with a custom Application Signals setup, Application Signals doesn't autodiscover the names of your services or the hosts or clusters they run on. You must specify these names during the custom setup, and the names that you specify are what is displayed on Application Signals dashboards.

The instructions in this section are for both Java applications and Python applications. The steps have been tested on Amazon EC2 instances, but are also expected to work on other architectures that support AWS Distro for OpenTelemetry.

Requirements

  • To get support for Application Signals, you must use the most recent version of both the CloudWatch agent and the AWS Distro for OpenTelemetry agent.

  • You must have the AWS CLI installed on the instance. We recommend AWS CLI version 2, but version 1 should also work. For more information about installing the AWS CLI, see Install or update the latest version of the AWS CLI.

Important

If you are already using OpenTelemetry with an application that you intend to enable for Application Signals, see OpenTelemetry compatibility considerations before you enable Application Signals.

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

  1. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

  2. In the navigation pane, choose Services.

  3. Choose Start discovering your Services.

  4. Select the check box and choose Start discovering your Services.

    When you complete this step for the first time in your account, Application Signals 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: Download and start the CloudWatch agent

To install the CloudWatch agent as part of enabling Application Signals on an Amazon EC2 instance or on-premises host

  1. Download the latest version of the CloudWatch agent to the instance. If the instance already has the CloudWatch agent installed, you might need to update it. Only versions of the agent released on November 30, 2023 or later support CloudWatch Application Signals.

    For information about downloading the CloudWatch agent, see Download the CloudWatch agent package.

  2. Before you start the CloudWatch agent, configure it to enable Application Signals. The following example is a CloudWatch agent configuration that enables Application Signals for both metrics and traces on an EC2 host.

    We recommend that you place this file at /opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json on Linux systems.

    {
  "traces": {
    "traces_collected": {
      "application_signals": {}
    }
  },
  "logs": {
    "metrics_collected": {
      "application_signals": {}
    }
  }
}

  3. Attach the CloudWatchAgentServerPolicy IAM policy to the IAM role of your Amazon EC2 instance. For permissions for on-premises hosts, see Permissions for on-premises servers.

    1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

    2. Choose Roles and find the role used by your Amazon EC2 instance. Then choose the name of that role.

    3. In the Permissions tab, choose Add permissions, Attach policies.

    4. Find CloudWatchAgentServerPolicy. Use the search box if needed. Then select the check box for that policy and choose Add permissions.

  4. Start the CloudWatch agent by entering the following commands. Replace agent-config-file-path with the path to the CloudWatch agent configuration file, such as ./amazon-cloudwatch-agent.json. You must include the file: prefix as shown.

    export CONFIG_FILE_PATH=./amazon-cloudwatch-agent.json
    sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl \
-a fetch-config \
-m ec2 -s -c file:agent-config-file-path

Permissions for on-premises servers

For an on-premises host, you will need to provide AWS authorization to your device.

To set up permissions for an on-premises host

  1. Create the IAM user to be used to provide permissions to your on-premises host:

    1. Open the IAM console at https://console.aws.amazon.com/iam/.

    2. Choose Users, Create User.

    3. In User details, for User name, enter a name for the new IAM user. This is the sign-in name for AWS that will be used to authenticate your host. Then choose Next

    4. On the Set permissions page, under Permissions options, select Attach policies directly.

    5. From the Permissions policies list, select the CloudWatchAgentServerPolicy policy to add to your user. Then choose Next.

    6. On the Review and create page, ensure that you are satisfied with the user name and that the CloudWatchAgentServerPolicy policy is in the Permissions summary.

    7. Choose Create user

  2. Create and retrieve your AWS access key and secret key:

    1. In the navigation pane in the IAM console, choose Users and then select the user name of the user that you created in the previous step.

    2. On the user's page, choose the Security credentials tab. Then, in the Access keys section, choose Create access key.

    3. For Create access key Step 1, choose Command Line Interface (CLI).

    4. For Create access key Step 2, optionally enter a tag and then choose Next.

    5. For Create access key Step 3, select Download .csv file to save a .csv file with your IAM user's access key and secret access key. You need this information for the next steps.

    6. Choose Done.

  3. Configure your AWS credentials in your on-premises host by entering the following command. Replace ACCESS_KEY_ID and SECRET_ACCESS_ID with your newly generated access key and secret access key from the .csv file that you downloaded in the previous step.

    $ aws configure
AWS Access Key ID [None]: ACCESS_KEY_ID
AWS Secret Access Key [None]: SECRET_ACCESS_ID
Default region name [None]: MY_REGION
Default output format [None]: json

Step 3: Instrument your application and start it

The next step is to instrument your application for CloudWatch Application Signals.

Java
To instrument your Java applications as part of enabling Application Signals on an Amazon EC2 instance or on-premises host

  1. Download the latest version of the AWS Distro for OpenTelemetry Java auto-instrumentation agent. You can download the latest version by using this link. You can view information about all released versions at aws-otel-java-instrumentation Releases.

  2. To optimize your Application Signals benefits, use environment variables to provide additional information before you start your application. This information will be displayed in Application Signals dashboards.

    1. For the OTEL_RESOURCE_ATTRIBUTES variable, specify the following information as key-value pairs:

      • (Optional) service.name sets the name of the service. This will be displayed as the service name for your application in Application Signals dashboards. If you don't provide a value for this key, the default of UnknownService is used.

      • (Optional) 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, one of the following defaults is used:

        • If this is an instance that is part of an Auto Scaling group, it is set to ec2:name-of-Auto-Scaling-group

        • If this is an Amazon EC2 instance that is not part of an Auto Scaling group, it is set to ec2:default

        • If this is an on-premises host, it is set to generic:default

        This environment variable is used only by Application Signals, and is converted into X-Ray trace annotations and CloudWatch metric dimensions.

      • For the OTEL_EXPORTER_OTLP_TRACES_ENDPOINT variable, specify the base endpoint URL where traces are to be exported to. The CloudWatch agent exposes 4316 as its OTLP port. On Amazon EC2, because applications communicate with the local CloudWatch agent, you should set this value to OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces

      • For the OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT variable, specify the base endpoint URL where metrics are to be exported to. The CloudWatch agent exposes 4316 as its OTLP port. On Amazon EC2, because applications communicate with the local CloudWatch agent, you should set this value to OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics

      • For the JAVA_TOOL_OPTIONS variable, specify the path where the AWS Distro for OpenTelemetry Java auto-instrumentation agent is stored.

        export JAVA_TOOL_OPTIONS=" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH"

        For example:

        export AWS_ADOT_JAVA_INSTRUMENTATION_PATH=./aws-opentelemetry-agent.jar

      • For the OTEL_METRICS_EXPORTER variable, we recommend that you set the value to none. This disables other metrics exporters so that only the Application Signals exporter is used.

      • Set OTEL_AWS_APPLICATION_SIGNALS_ENABLED to true. This generates Application Signals metrics from traces.

  3. Start your application with the environment variables listed in the previous step. The following is an example of a starting script.

    Note

    The following configuration supports only versions 1.32.2 and later of the AWS Distro for OpenTelemetry auto-instrumentation agent for Java.

    JAVA_TOOL_OPTIONS=" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH" \
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORT=none \
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
OTEL_RESOURCE_ATTRIBUTES=service.name=$YOUR_SVC_NAME \
java -jar $MY_JAVA_APP.jar

  4. (Optional) To enable trace log correlation, set an additional environment variable aws.log.group.names to be the log group name for your application log. Then the traces from your application can be correlated with the relevant log entries from this specific log group. To enable trace log correlation, you also need to change the logging configuration in your application. For more information, see Enable trace log correlation.

    The following is an example of a starting script that helps enable trace log correlation. 

    JAVA_TOOL_OPTIONS=" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH" \
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORT=none \
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
OTEL_RESOURCE_ATTRIBUTES=aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=$YOUR_SVC_NAME \
java -jar $MY_JAVA_APP.jar
Python
To instrument your Python applications as part of enabling Application Signals on an Amazon EC2 instance

  1. Download the latest version of the AWS Distro for OpenTelemetry Python auto-instrumentation agent. Install it by running the following command.

    pip install aws-opentelemetry-distro

    You can view information about all released versions at AWS Distro for OpenTelemetry Python instrumentation.

  2. To optimize your Application Signals benefits, use environment variables to provide additional information before you start your application. This information will be displayed in Application Signals dashboards.

    1. For the OTEL_RESOURCE_ATTRIBUTES variable, 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 of UnknownService 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, one of the following defaults is used:

        • If this is an instance that is part of an Auto Scaling group, it is set to ec2:name-of-Auto-Scaling-group.

        • If this is an Amazon EC2 instance that is not part of an Auto Scaling group, it is set to ec2:default

        • If this is an on-premises host, it is set to generic:default

        This attribute key is used only by Application Signals, and is converted into X-Ray trace annotations and CloudWatch metric dimensions.

    2. For the OTEL_EXPORTER_OTLP_PROTOCOL variable, specify http/protobuf to export telemetry data over HTTP to the CloudWatch agent endpoints listed in the following steps.

    3. For the OTEL_EXPORTER_OTLP_TRACES_ENDPOINT variable, specify the base endpoint URL where traces are to be exported to. The CloudWatch agent exposes 4316 as its OTLP port over HTTP. On Amazon EC2, because applications communicate with the local CloudWatch agent, you should set this value to OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces

    4. For the OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT variable, specify the base endpoint URL where metrics are to be exported to. The CloudWatch agent exposes 4316 as its OTLP port over HTTP. On Amazon EC2, because applications communicate with the local CloudWatch agent, you should set this value to OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics

    5. For the OTEL_METRICS_EXPORTER variable, we recommend that you set the value to none. This disables other metrics exporters so that only the Application Signals exporter is used.

    6. Set the OTEL_AWS_APPLICATION_SIGNALS_ENABLED variable to true to have your container start sending X-Ray traces and CloudWatch metrics to Application Signals.

  3. Start your application with the environment variables discussed in the previous step. The following is an example of a starting script.

    • Replace $SVC_NAME with your application name. This will be displayed as the name of the application, in Application Signals dashboards.

    • Replace $PYTHON_APP with the location and name of your application.

    OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
OTEL_PYTHON_DISTRO=aws_distro \
OTEL_PYTHON_CONFIGURATOR=aws_configurator \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_TRACES_SAMPLER=xray \
OTEL_TRACES_SAMPLER_ARG="endpoint=http://localhost:2000" \
OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
OTEL_RESOURCE_ATTRIBUTES=service.name=$SVC_NAME \ 
opentelemetry-instrument python $MY_PYTHON_APP.py

    Before you enable Application Signals for your Python applications, be aware of the following considerations.

    • In some containerized applications, a missing PYTHONPATH environment variable can sometimes cause the application to fail to start. To resolve this, ensure that you set the PYTHONPATH environment variable to the location of your application’s working directory. This is due to a known issue with OpenTelemetry auto-instrumentation. For more information about this issue, see Python autoinstrumentation setting of PYTHONPATH is not compliant.

    • For Django applications, there are additional required configurations, which are outlined in the OpenTelemetry Python documentation.

      • Use the --noreload flag to prevent automatic reloading.

      • Set the DJANGO_SETTINGS_MODULE environment variable to the location of your Django application’s settings.py file. This ensures that OpenTelemetry can correctly access and integrate with your Django settings.

  4. (Optional) To enable trace log correlation, set an additional environment variable aws.log.group.names to be the log group name for your application log. Then the traces from your application can be correlated with the relevant log entries from this specific log group. To enable trace log correlation, you also need to change the logging configuration in your application. For more information, see Enable trace log correlation.

    The following is an example of a starting script that helps enable trace log correlation. 

    OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
OTEL_PYTHON_DISTRO=aws_distro \
OTEL_PYTHON_CONFIGURATOR=aws_configurator \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_TRACES_SAMPLER=xray \
OTEL_TRACES_SAMPLER_ARG="endpoint=http://localhost:2000" \
OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
OTEL_RESOURCE_ATTRIBUTES=aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,aws.hostedin.environment=$YOUR_HOST_ENV,service.name=$YOUR_SVC_NAME \ 
java -jar $MY_PYTHON_APP.jar