在 Amazon EC2 上启用 Application Signals
对于在 Amazon EC2 或其他实例类型上运行的应用程序,您可以自行安装并配置 CloudWatch 代理和 AWS Distro for OpenTelemetry。在这些启用了自定义 Application Signals 设置的架构上,Application Signals 不会自动发现您的服务的名称或运行这些服务的主机或集群。您必须在自定义设置期间指定这些名称,而您指定的名称就是显示在 Application Signals 控制面板上的名称。
本节中的说明适用于 Java 应用程序和 Python 应用程序。这些步骤已在 Amazon EC2 实例上进行了测试,但预计也可以在支持 AWS Distro for OpenTelemetry 的其他架构上运行。
要求
如果您已经在打算为 Application Signals 启用的应用程序中使用 OpenTelemetry,请在启用 Application Signals 之前参阅 OpenTelemetry 兼容性注意事项。
步骤 1:在账户中启用 Application Signals
如果您尚未在此账户中启用 Application Signals,则必须向 Application Signals 授予发现您的服务所需的权限。为此,请执行以下操作:您的账户只需执行一次该操作。
步骤 2:下载并启动 CloudWatch 代理
作为在 Amazon EC2 实例或本地主机上启用 Application Signals 的一部分安装 CloudWatch 代理
将最新版本的 CloudWatch 代理下载到实例。如果实例已安装 CloudWatch 代理,您可能需要对其进行更新。只有在 2023 年 11 月 30 日或之后发布的代理版本支持 CloudWatch Application Signals。
有关下载 CloudWatch 代理的信息,请参阅 下载 CloudWatch 代理软件包。
启动 CloudWatch 代理之前,请将其配置为启用 Application Signals。以下示例是 CloudWatch 代理配置,该配置为 EC2 主机上的指标和跟踪启用 Application Signals。
建议您将此文件放在 Linux 系统中的 /opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json
。
{
"traces": {
"traces_collected": {
"application_signals": {}
}
},
"logs": {
"metrics_collected": {
"application_signals": {}
}
}
}
将 CloudWatchAgentServerPolicy IAM 策略附加到 Amazon EC2 实例的 IAM 角色。有关本地主机的权限,请参阅 本地服务器的权限。
登录 AWS Management Console,然后通过以下网址打开 IAM 控制台:https://console.aws.amazon.com/iam/。
选择角色并查找您的 Amazon EC2 实例使用的角色。然后选择该角色的名称。
在权限选项卡中,选择添加权限、附加策略。
查找 CloudWatchAgentServerPolicy。如果需要,请使用搜索框。然后选择该策略对应的复选框,选择添加权限。
通过输入以下命令启动 CloudWatch 代理。将 agent-config-file-path
替换为指向 CloudWatch 代理配置文件的路径,例如 ./amazon-cloudwatch-agent.json
。必须包含 file:
前缀,如图所示。
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
本地服务器的权限
对于本地主机,您需要为设备提供 AWS 授权。
设置本地主机的权限
创建用于向本地主机提供权限的 IAM 用户:
通过 https://console.aws.amazon.com/iam/ 打开 IAM 控制台。
依次选择用户、创建用户。
在用户详情中,为用户名输入新 IAM 用户的名称。这是 AWS 的登录名,将用于对您的主机进行身份验证。然后选择下一个
在设置权限页面的权限选项下,选择直接附加策略。
从权限策略列表中,选择要添加到您的用户的 CloudWatchAgentServerPolicy 策略。然后选择下一步。
在查看并创建页面上,确保您对用户名满意,并且 CloudWatchAgentServerPolicy 策略位于权限摘要中。
选择 Create user。
创建和检索您的 AWS 访问密钥和秘密密钥:
在 IAM 控制台的导航窗格中,选择用户,然后选择您在上一步中所创建用户的用户名。
在用户的页面上,选择安全凭证选项卡。然后,在访问密钥部分,选择创建访问密钥。
对于创建访问密钥步骤 1,选择命令行界面 (CLI)。
对于创建访问密钥步骤 2,(可选)输入标记,然后选择下一步。
对于创建访问密钥步骤 3,选择下载.csv 文件以保存包含您的 IAM 用户访问密钥和秘密访问密钥的 .csv 文件。您在后续步骤中需要此信息。
选择完成。
通过输入以下命令,在本地主机中配置 AWS 凭证。将 ACCESS_KEY_ID
和 SECRET_ACCESS_ID
替换为您在上一步中下载的 .csv 文件中新生成的访问密钥和秘密访问密钥。
$ 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
步骤 3:检测您的应用程序并将其启动
下一步是为 CloudWatch Application Signals 检测您的应用程序。
- Java
-
检测 Java 应用程序,作为在 Amazon EC2 实例或本地主机上启用 Application Signals 的一部分流程
下载最新版本的 AWS Distro for OpenTelemetry Java 自动检测代理。您可以使用此链接下载最新版本。您可以在 aws-otel-java-instrumentation 版本上查看有关所有已发布版本的信息。
要优化 Application Signals 的优势,请在启动应用程序之前使用环境变量提供更多信息。此信息将显示在 Application Signals 控制面板中。
对于 OTEL_RESOURCE_ATTRIBUTES
变量,将以下信息指定为键值对:
(可选)service.name
设置服务的名称。这将作为应用程序的服务名称在 Application Signals 控制面板中显示。如果您不提供此键的值,将使用默认值 UnknownService
。
(可选)deployment.environment
设置应用程序运行所在的环境。这将作为应用程序的托管环境显示在 Application Signals 控制面板中。如果您未指定此项,则使用以下默认值之一:
如果这是属于自动扩缩组的实例,则将其设置为 ec2:name-of-Auto-Scaling-group
如果这是不属于自动扩缩组的 Amazon EC2 实例,则将其设置为 ec2:default
如果这是本地主机,则将其设置为 generic:default
此环境变量仅供 Application Signals 使用,并转换为 X-Ray 跟踪注释和 CloudWatch 指标维度。
对于 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
变量,指定要将跟踪导出到的基本端点 URL。CloudWatch 代理将 4316 作为其 OTLP 端口公开。在 Amazon EC2 上,由于应用程序与本地 CloudWatch 代理通信,因此您应将此值设置为 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces
对于 OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT
变量,指定要将指标导出到的基本端点 URL。CloudWatch 代理将 4316 作为其 OTLP 端口公开。在 Amazon EC2 上,由于应用程序与本地 CloudWatch 代理通信,因此您应将此值设置为 OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics
对于 JAVA_TOOL_OPTIONS
变量,指定存储 AWS Distro for OpenTelemetry Java 自动检测代理的路径。
export JAVA_TOOL_OPTIONS=" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH
"
例如:
export AWS_ADOT_JAVA_INSTRUMENTATION_PATH=./aws-opentelemetry-agent.jar
对于 OTEL_METRICS_EXPORTER
变量,我们建议您将该值设置为 none
。这将禁用其他指标导出程序,因此仅使用 Application Signals 导出程序。
将 OTEL_AWS_APPLICATION_SIGNALS_ENABLED
设置为 true
。这会从跟踪中生成 Application Signals 指标。
使用上一步中列出的环境变量启动应用程序。以下是启动脚本的示例。
以下配置仅支持适用于 Java 的 AWS Distro for OpenTelemetry 自动检测代理版本 1.32.2 及更高版本。
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
(可选)要启用跟踪日志关联,请将其他环境变量 aws.log.group.names
设置为应用程序日志的日志组名称。然后,应用程序的跟踪便可与该特定日志组的相关日志条目相关联。要启用跟踪日志关联,您还需要更改应用程序中的日志记录配置。有关更多信息,请参阅 启用跟踪日志关联。
以下是帮助启用跟踪日志关联的启动脚本示例。
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
-
检测 Python 应用程序,作为在 Amazon EC2 实例上启用 Application Signals 的一部分流程
下载最新版本的 AWS Distro for OpenTelemetry Python 自动检测代理。通过运行以下 命令安装它。
pip install aws-opentelemetry-distro
您可以在 AWS Distro for OpenTelemetry Python instrumentation 上查看有关所有已发布版本的信息。
要优化 Application Signals 的优势,请在启动应用程序之前使用环境变量提供更多信息。此信息将显示在 Application Signals 控制面板中。
对于 OTEL_RESOURCE_ATTRIBUTES
变量,将以下信息指定为键值对:
service.name
设置服务的名称。这将作为应用程序的服务名称显示在 Application Signals 控制面板中。如果您不提供此键的值,将使用默认值 UnknownService
。
deployment.environment
设置应用程序运行所在的环境。这将作为应用程序的托管环境显示在 Application Signals 控制面板中。如果您未指定此项,则使用以下默认值之一:
如果这是属于自动扩缩组的实例,则将其设置为 ec2:name-of-Auto-Scaling-group
。
如果这是不属于自动扩缩组的 Amazon EC2 实例,则将其设置为 ec2:default
如果这是本地主机,则将其设置为 generic:default
此属性键仅供 Application Signals 使用,并转换为 X-Ray 跟踪注释和 CloudWatch 指标维度。
对于 OTEL_EXPORTER_OTLP_PROTOCOL
变量,指定 http/protobuf
以通过 HTTP 将遥测数据导出到以下步骤中列出的 CloudWatch 代理端点。
对于 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
变量,指定要将跟踪导出到的基本端点 URL。CloudWatch 代理将 4316 作为其 HTTP 上的 OTLP 端口公开。在 Amazon EC2 上,由于应用程序与本地 CloudWatch 代理通信,因此您应将此值设置为 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces
对于 OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT
变量,指定要将指标导出到的基本端点 URL。CloudWatch 代理将 4316 作为其 HTTP 上的 OTLP 端口公开。在 Amazon EC2 上,由于应用程序与本地 CloudWatch 代理通信,因此您应将此值设置为 OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics
对于 OTEL_METRICS_EXPORTER
变量,我们建议您将该值设置为 none
。这将禁用其他指标导出程序,因此仅使用 Application Signals 导出程序。
将 OTEL_AWS_APPLICATION_SIGNALS_ENABLED
变量设置为 true
以使您的容器开始向 Application Signals 发送 X-Ray 跟踪和 CloudWatch 指标。
使用上一步中讨论的环境变量启动应用程序。以下是启动脚本的示例。
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
在为 Python 应用程序启用 Application Signals 之前,请注意以下注意事项。
(可选)要启用跟踪日志关联,请将其他环境变量 aws.log.group.names
设置为应用程序日志的日志组名称。然后,应用程序的跟踪便可与该特定日志组的相关日志条目相关联。要启用跟踪日志关联,您还需要更改应用程序中的日志记录配置。有关更多信息,请参阅 启用跟踪日志关联。
以下是帮助启用跟踪日志关联的启动脚本示例。
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