Exporting collector-less trace using Amazon Distro for OpenTelemetry (ADOT) SDKs - Amazon CloudWatch
PrerequisiteSet up IAM permissions for Amazon EC2Set up IAM permissions for on-premise hostsEnabling ADOT SDKs
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Exporting collector-less trace using Amazon Distro for OpenTelemetry (ADOT) SDKs

You can use the ADOT SDKs to go collector-less and to send traces directly to the OTLP endpoint (for traces).

Note

By default, Application Signals is enabled when you enable Transaction Search. Application Signals is not supported on Amazon Distro for OpenTelemetry and must be disabled.

Prerequisite

Make sure Transaction Search is enabled to send spans to the X-Ray OTLP endpoint. For more information, see Getting started with Transaction Search.

Set up IAM permissions for Amazon EC2

Follow these steps to attach the AWSXrayWriteOnlyPolicy IAM policy to the IAM role of your Amazon EC2 instance:

  1. Open the CloudWatch console at https://console.amazonaws.cn/cloudwatch/.

  2. Choose Roles and find and select the role used by your Amazon EC2 instance.

  3. Under the Permissions tab, choose Add permissions, then Attach policies.

  4. Using the search box, search for the AWSXrayWriteOnlyPolicy policy.

  5. Select the AWSXrayWriteOnlyPolicy policy and choose Add permissions.

Set up IAM permissions for on-premise hosts

Follow these steps to create an IAM user that can be used to provide permissions to your on-premise hosts.

  1. Open the CloudWatch console at https://console.amazonaws.cn/cloudwatch/.

  2. Choose Users and then Create User.

  3. Choose Users, Create User.

  4. Under User details, for User name, enter a name for the new IAM user. This is the sign-in name for Amazon that will be used to authenticate your host.

  5. Choose Next.

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

  7. From the Permissions policies list, select the AWSXrayWriteOnlyPolicy policy to add to your user.

  8. Choose Next.

  9. On the Review and create page, make sure that you are satisfied with the user name and that the AWSXrayWriteOnlyPolicy policy is under the Permissions summary.

  10. Choose Create user.

  11. Create and retrieve your Amazon 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.

    3. Under the Access keys section, choose Create access key.

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

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

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

    7. Choose Done.

  12. Configure your Amazon 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

Enabling ADOT SDKs

You can enable traces for your application to be sent directly to the OTLP endpoint from Amazon Distro for OpenTelemetry (ADOT) SDK on Java, Node.js, Python, and .Net.

Java

  1. Download the latest version of the Amazon Distro for OpenTelemetry Java auto-instrumentation agent. You can download the latest version by using this command:

    curl -L -O https://github.com/aws-observability/aws-otel-java-instrumentation/releases/latest/download/aws-opentelemetry-agent.jar

    To view all the released versions, see aws-otel-java-instrumentation releases.

  2. To enable the exporter that directly sends traces to the X-Ray OTLP traces endpoint and to optimize benefits, use the environment variables to provide additional information before you start your application.

  3. 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. When 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. When 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

  4. For the OTEL_EXPORTER_OTLP_TRACES_ENDPOINT variable, specify the X-Ray OTLP traces endpoint: https://xray.[AWSRegion].amazonaws.com/v1/traces. For example:

    export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://xray.us-west-2.amazonaws.com/v1/traces"

  5. For the JAVA_TOOL_OPTIONS variable, specify the path where the Amazon 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"

  6. For the OTEL_METRICS_EXPORTER variable, it is recommended to set the value to none.

  7. For the OTEL_LOGS_EXPORTER variable, it is recommended to set the value to none.

  8. For the OTEL_TRACES_EXPORTER variable, you have to set the value for otlp (this is optional and is the default value if this environment variable is not set).

  9. For the OTEL_EXPORTER_OTLP_PROTOCOL variable, you have to set the value to http/protobuf (this is optional and is the default value if this environment variable is not set). The X-Ray OTLP endpoint currently only supports the HTTP protocol.

  10. Your application should now be running with Amazon Distro for OpenTelemetry Java instrumentation and will generate spans. These spans are stored in the aws/spans CloudWatch LogsLogGroup in your account. You can also view the traces and metrics correlated with your spans in the CloudWatch Traces and Metrics Console.

  11. Start your application with the environment variables you set. Here is an example of a starting script.

    (Note: The following configuration supports only versions 1.32.2 and later of the Amazon Distro for OpenTelemetry auto-instrumentation agent for Java.)

    JAVA_TOOL_OPTIONS=" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH" \
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="service.name=$YOUR_SVC_NAME" \
java -jar $MY_JAVA_APP.jar
Node.js

  1. Download the latest version of the Amazon Distro for OpenTelemetry JavaScript auto-instrumentation agent for Node.js. You can install using the command:

    npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation

    To view information about all released versions, see Amazon Distro for OpenTelemetry JavaScript instrumentation.

  2. To enable the exporter that directly sends traces to the X-Ray OTLP endpoint and to optimize benefits, use the environment variables to provide additional information before you start your application.

  3. 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. When 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. When you don't specify this variable, 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.

  4. For the OTEL_EXPORTER_OTLP_TRACES_ENDPOINT variable, specify the X-Ray OTLP traces endpoint: https://xray.[AWSRegion].amazonaws.com/v1/traces.

    For example:

    export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://xray.us-west-2.amazonaws.com/v1/traces"

  5. For the OTEL_METRICS_EXPORTER variable, it is recommended to set the value to none. Application Signals metrics are generated by the OTLP endpoint.

  6. For the OTEL_LOGS_EXPORTER variable, it is recommended to set the value to none.

  7. For the OTEL_TRACES_EXPORTER variable, you have to set the value for otlp (this is optional and is the default value if this environment variable is not set).

  8. For the OTEL_EXPORTER_OTLP_PROTOCOL variable, you have to set the value to http/protobuf (this is optional and is the default value if this environment variable is not set). The X-Ray OTLP endpoint currently only supports the HTTP protocol.

  9. Your application should now be running with Amazon Distro for OpenTelemetry Java instrumentation and will generate spans. These spans are stored in the aws/spans CloudWatch LogsLogGroup in your account. You can also view the traces and metrics correlated with your spans in the CloudWatch Traces and Metrics Console.

  10. Start your application with the environment variables you set. Here is an example of a starting script.

    (Note: Replace $SVC_NAME with your application name. This is displayed as the name of the application.

    OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="service.name=$SVC_NAME" \
node —require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register' your-application.js
Python

  1. Download the latest version of the Amazon Distro for OpenTelemetry Python auto-instrumentation agent. You can install using the command:

    pip install aws-opentelemetry-distro

  2. To enable the exporter to directly send traces to the X-Ray OTLP endpoint and to optimize benefits, use the environment variables to provide additional information before you start your application.

  3. 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. When 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. When 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.

  4. For the OTEL_EXPORTER_OTLP_TRACES_ENDPOINT variable, specify the X-Ray OTLP traces endpoint: https://xray.[AWSRegion].amazonaws.com/v1/traces.

    For example:

    export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://xray.us-west-2.amazonaws.com/v1/traces"

  5. For the OTEL_METRICS_EXPORTER variable, it is recommended to set the value to none. Application Signals metrics are generated by the OTLP endpoint.

  6. For the OTEL_LOGS_EXPORTER variable, it is recommended to set the value to none.

  7. For the OTEL_TRACES_EXPORTER variable, you have to set the value for otlp (this is optional and is the default value if this environment variable is not set).

  8. For the OTEL_EXPORTER_OTLP_PROTOCOL variable, you have to set the value to http/protobuf (this is optional and is the default value if this environment variable is not set). The X-Ray OTLP endpoint currently only supports the HTTP protocol.

  9. Your application should now be running with Amazon Distro for OpenTelemetry Java instrumentation and will generate spans. These spans are stored in the aws/spans CloudWatch LogsLogGroup in your account. You can also view the traces and metrics correlated with your spans in the CloudWatch Traces and Metrics Console.

  10. Start your application with the environment variables you set. Here is an example of a starting script.

    (Note: Replace $SVC_NAME with your application name and replace $PYTHON_APP with the location and name of your application.

    OTEL_METRICS_EXPORTER=none \ 
OTEL_LOGS_EXPORTER=none \ 
OTEL_PYTHON_DISTRO=aws_distro \
 OTEL_PYTHON_CONFIGURATOR=aws_configurator \ 
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="service.name=$SVC_NAME" \
opentelemetry-instrument python $MY_PYTHON_APP.py
.Net

To enable the exporter that directly sends traces to the X-Ray OTLP traces endpoint and to optimize benefits, set the environment variables to provide additional information before you start your application. These variables are also necessary to set up the .NET instrumentation.

  1. Replace dotnet-service-name in the OTEL_RESOURCE_ATTRIBUTES environment variable with the service name of your choice.

  2. Set OTEL_TRACES_EXPORTER=none.

  3. Set OTEL_AWS_SIG_V4_ENABLED=true.

    An example for Linux.

    export INSTALL_DIR=OpenTelemetryDistribution
export CORECLR_ENABLE_PROFILING=1
export CORECLR_PROFILER={918728DD-259F-4A6A-AC2B-B85E1B658318}
export CORECLR_PROFILER_PATH=${INSTALL_DIR}/linux-x64/OpenTelemetry.AutoInstrumentation.Native.so
export DOTNET_ADDITIONAL_DEPS=${INSTALL_DIR}/AdditionalDeps
export DOTNET_SHARED_STORE=${INSTALL_DIR}/store
export DOTNET_STARTUP_HOOKS=${INSTALL_DIR}/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll
export OTEL_DOTNET_AUTO_HOME=${INSTALL_DIR}

export OTEL_DOTNET_AUTO_PLUGINS="AWS.Distro.OpenTelemetry.AutoInstrumentation.Plugin, AWS.Distro.OpenTelemetry.AutoInstrumentation"
export OTEL_TRACES_EXPORTER=none
export OTEL_AWS_SIG_V4_ENABLED=true

export OTEL_RESOURCE_ATTRIBUTES=service.name=dotnet-service-name
export OTEL_METRICS_EXPORTER=none
export OTEL_LOGS_EXPORTER=none
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces

    An example for Windows Server.

    $env:INSTALL_DIR = "OpenTelemetryDistribution" 
$env:CORECLR_ENABLE_PROFILING = 1 
$env:CORECLR_PROFILER = "{918728DD-259F-4A6A-AC2B-B85E1B658318}" 
$env:CORECLR_PROFILER_PATH = Join-Path $env:INSTALL_DIR "win-x64/OpenTelemetry.AutoInstrumentation.Native.dll" 
$env:DOTNET_ADDITIONAL_DEPS = Join-Path $env:INSTALL_DIR "AdditionalDeps" 
$env:DOTNET_SHARED_STORE = Join-Path $env:INSTALL_DIR "store" 
$env:DOTNET_STARTUP_HOOKS = Join-Path $env:INSTALL_DIR "net/OpenTelemetry.AutoInstrumentation.StartupHook.dll" 
$env:OTEL_DOTNET_AUTO_HOME = $env:INSTALL_DIR 
$env:OTEL_DOTNET_AUTO_PLUGINS = "AWS.Distro.OpenTelemetry.AutoInstrumentation.Plugin, AWS.Distro.OpenTelemetry.AutoInstrumentation"

$env:OTEL_TRACES_EXPORTER=none
$env:OTEL_AWS_SIG_V4_ENABLED=true

$env:OTEL_RESOURCE_ATTRIBUTES=service.name=dotnet-service-name
$env:OTEL_METRICS_EXPORTER=none
$env:OTEL_LOGS_EXPORTER=none
$env:OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
$env:OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces

  4. Start your application with the environment variables.

  5. (Optional) Alternatively, you can use the installation scripts provided to help installation and setup of Amazon Distro for OpenTelemetry .NET auto-instrumentation package.

    For Linux, download and install the Bash installation script from the GitHub releases page:

    # Download and Install
curl -L -O https://github.com/aws-observability/aws-otel-dotnet-instrumentation/releases/latest/download/aws-otel-dotnet-install.sh
chmod +x ./aws-otel-dotnet-install.sh
./aws-otel-dotnet-install.sh
# Instrument
. $HOME/.otel-dotnet-auto/instrument.shexport OTEL_RESOURCE_ATTRIBUTES=service.name=dotnet-service-name

    For Windows Server, download and install the PowerShell installation script from the GitHub releases page:

    # Download and Install
$module_url = "https://github.com/aws-observability/aws-otel-dotnet-instrumentation/releases/latest/download/AWS.Otel.DotNet.Auto.psm1"
$download_path = Join-Path $env:temp "AWS.Otel.DotNet.Auto.psm1"
Invoke-WebRequest -Uri $module_url -OutFile $download_path
Import-Module $download_path
Install-OpenTelemetryCore
# Instrument
Import-Module $download_path
Register-OpenTelemetryForCurrentSession -OTelServiceName "dotnet-service-name"
Register-OpenTelemetryForIIS

    You can find the NuGet package of the Amazon Distro for OpenTelemetry .NET auto-instrumentation package in the official NuGet repository. Make sure to check the README file for instructions.