使用自定义设置在 Amazon EC2 和其他平台上启用 Application Signals - Amazon CloudWatch
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

使用自定义设置在 Amazon EC2 和其他平台上启用 Application Signals

Application Signals 目前为预览版。如果您对此功能有任何反馈,可以通过 app-signals-feedback@amazon.com 联系我们。

对于在 Amazon EC2 上运行的应用程序和其他非 Amazon EKS 的架构,您可以自行安装并配置 CloudWatch 代理和 Amazon Distro for OpenTelemetry。在这些启用了自定义 Application Signals 设置的架构上,Application Signals 不会自动发现您的服务的名称或运行这些服务的主机或集群。您必须在自定义设置期间指定这些名称,而您指定的名称就是显示在 Application Signals 控制面板上的名称。

以下步骤已在 Amazon EC2 实例上进行了测试,但预计也可以在支持 Amazon Distro for OpenTelemetry 的其他架构上运行。

要求

  • 要获得对 Application Signals 的支持,您必须同时使用最新版本的 CloudWatch 代理和 Amazon Distro for OpenTelemetry 代理。

  • 必须已在实例上安装 Amazon CLI。我们推荐 Amazon CLI 版本 2,但版本 1 应该也可以使用。有关安装 Amazon CLI 的更多信息,请参阅安装或更新 Amazon CLI 的最新版本

重要

如果您已经在打算为 Application Signals 启用的应用程序中使用 OpenTelemetry,请在启用 Application Signals 之前参阅 OpenTelemetry 兼容性注意事项

步骤 1:在账户中启用 Application Signals

如果您尚未在此账户中启用 Application Signals,则必须向 Application Signals 授予发现您的服务所需的权限。为此,请执行以下操作:您的账户只需执行一次该操作。

为您的应用程序启用 Application Signals
  1. 通过 https://console.aws.amazon.com/cloudwatch/ 打开 CloudWatch 控制台。

  2. 在导航窗格中,选择服务

  3. 选择开始发现您的服务

  4. 选中该复选框并选择开始发现服务

    首次在您的账户中完成此步骤会创建 AWSServiceRoleForCloudWatchApplicationSignals 服务相关角色。此角色授予 Application Signals 以下权限:

    • xray:GetServiceGraph

    • logs:StartQuery

    • logs:GetQueryResults

    • cloudwatch:GetMetricData

    • cloudwatch:ListMetrics

    • tag:GetResources

    有关该角色的更多信息,请参阅 CloudWatch Application Signals 的服务相关角色权限

步骤 2:下载并启动 CloudWatch 代理

作为在 Amazon EC2 实例上启用 Application Signals 的一部分安装 CloudWatch 代理
  1. 将最新版本的 CloudWatch 代理下载到实例。如果实例已安装 CloudWatch 代理,您可能需要对其进行更新。只有在 2023 年 11 月 30 日或之后发布的代理版本支持 CloudWatch Application Signals。

    有关下载 CloudWatch 代理的信息,请参阅 下载 CloudWatch 代理软件包

  2. 启动 CloudWatch 代理之前,请将其配置为启用 Application Signals。以下示例是 CloudWatch 代理配置,该配置为 EC2 主机上的指标和跟踪启用 Application Signals。

    您可以通过输入以下命令来创建该文件:

    vim amazon-cloudwatch-agent.json

    添加以下内容作为该文件的内容。

    { "traces": { "traces_collected": { "app_signals": {} } }, "logs": { "metrics_collected": { "app_signals": {} } } }
  3. CloudWatchAgentServerPolicyAWSXrayWriteOnlyAccess IAM policy 附加到您的 Amazon EC2 实例的 IAM 角色。

    1. 登录 Amazon Web Services Management Console,然后使用以下网址打开 IAM 控制台:https://console.aws.amazon.com/iam/

    2. 选择角色并查找您的 Amazon EC2 实例使用的角色。然后选择该角色的名称。

    3. 权限选项卡中,选择添加权限附加策略

    4. 查找 CloudWatchAgentServerPolicy。如果需要,请使用搜索框。然后选择该策略对应的复选框,选择添加权限

    5. 查找 AWSXrayWriteOnlyAccess。如果需要,请使用搜索框。然后选择该策略对应的复选框,选择添加权限

  4. 通过输入以下命令启动 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:$CONFIG_FILE_PATH

步骤 3:检测您的应用程序并将其启动

下一步是为 CloudWatch Application Signals 检测您的应用程序。

Java
检测 Java 应用程序,作为在 Amazon EC2 实例上启用 Application Signals 的一部分流程
  1. 下载最新版本的 Amazon Distro for OpenTelemetry Java 自动检测代理。您可以使用此链接下载最新版本。您可以在 aws-otel-java-instrumentation 版本上查看有关所有已发布版本的信息。

  2. 要优化 Application Signals 的优势,请在启动应用程序之前使用环境变量提供更多信息。此信息将显示在 Application Signals 控制面板中。

    1. 对于 OTEL_RESOURCE_ATTRIBUTES 变量,将以下信息指定为键值对:

      • aws.hostedin.environment 设置应用程序运行所在的环境。这将作为应用程序的托管环境显示在 Application Signals 控制面板中。此属性键仅供 Application Signals 使用,并转换为 X-Ray 跟踪注释和 CloudWatch 指标维度。如果您不提供此键的值,将使用默认值 Generic

      • service.name 设置服务的名称。这将作为应用程序的服务名称显示在 Application Signals 控制面板中。如果您不提供此键的值,将使用默认值 unknown_service

    2. 对于 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 变量,指定要将跟踪导出到的基本端点 URL。CloudWatch 代理将 4315 作为其 OLTP 端口公开。在 Amazon EC2 上,由于应用程序与本地 CloudWatch 代理通信,因此您应将此值设置为 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4315

    3. 对于 OTEL_AWS_APP_SIGNALS_EXPORTER_ENDPOINT 变量,指定要将指标导出到的基本端点 URL。CloudWatch 代理将 4315 作为其 OLTP 端口公开。在 Amazon EC2 上,由于应用程序与本地 CloudWatch 代理通信,因此您应将此值设置为 OTEL_AWS_APP_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4315

    4. 对于 JAVA_TOOL_OPTIONS 变量,指定存储 Amazon Distro for OpenTelemetry Java 自动检测代理的路径。

      export JAVA_TOOL_OPTIONS=' -javaagent:$ADOT_AGENT_PATH'

      例如:

      export ADOT_AGENT_PATH=./aws-opentelemetry-agent.jar
    5. 对于 OTEL_METRICS_EXPORTER 变量,我们建议您将该值设置为 none。这将禁用其他指标导出程序,因此仅使用 Application Signals 导出程序。

    6. 对于 OTEL_AWS_APP_SIGNALS_ENABLED 变量,通过将 OTEL_AWS_APP_SIGNALS_ENABLED 设置为 true 来启用 SpanMetricProcessor(SMP)。这会从跟踪中生成 Application Signals 指标。

  3. 使用上一步中讨论的环境变量启动应用程序。以下是启动脚本的示例。

    JAVA_TOOL_OPTIONS=' -javaagent:$ADOT_AGENT_PATH' \ OTEL_METRICS_EXPORTER=none \ OTEL_AWS_APP_SIGNALS_ENABLED=true \ OTEL_AWS_APP_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4315 \ OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4315 \ OTEL_RESOURCE_ATTRIBUTES=aws.hostedin.environment=$YOUR_HOST_ENV,service.name=$YOUR_SVC_NAME \ java -jar $MY_JAVA_APP.jar
Python
检测 Python 应用程序,作为在 Amazon EC2 实例上启用 Application Signals 的一部分流程
  1. 下载最新版本的 Amazon Distro for OpenTelemetry Python 自动检测代理。通过运行以下 命令安装它。

    pip install aws-opentelemetry-distro

    您可以在 Amazon Distro for OpenTelemetry Python instrumentation 上查看有关所有已发布版本的信息。

  2. 要优化 Application Signals 的优势,请在启动应用程序之前使用环境变量提供更多信息。此信息将显示在 Application Signals 控制面板中。

    1. 对于 OTEL_RESOURCE_ATTRIBUTES 变量,将以下信息指定为键值对:

      • aws.hostedin.environment 设置应用程序运行所在的环境。这将作为应用程序的托管环境显示在 Application Signals 控制面板中。此属性键仅供 Application Signals 使用,并转换为 X-Ray 跟踪注释和 CloudWatch 指标维度。如果您不提供此键的值,将使用默认值 Generic

      • service.name 设置服务的名称。这将作为应用程序的服务名称显示在 Application Signals 控制面板中。如果您不提供此键的值,将使用默认值 unknown_service

    2. 对于 OTEL_EXPORTER_OTLP_PROTOCOL 变量,指定 http/protobuf 以通过 HTTP 将遥测数据导出到以下步骤中列出的 CloudWatch 代理端点。

    3. 对于 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 变量,指定要将跟踪导出到的基本端点 URL。CloudWatch 代理将 4316 作为其 HTTP 上的 OLTP 端口公开。在 Amazon EC2 上,由于应用程序与本地 CloudWatch 代理通信,因此您应将此值设置为 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces

    4. 对于 OTEL_AWS_APP_SIGNALS_EXPORTER_ENDPOINT 变量,指定要将指标导出到的基本端点 URL。CloudWatch 代理将 4316 作为其 HTTP 上的 OLTP 端口公开。在 Amazon EC2 上,由于应用程序与本地 CloudWatch 代理通信,因此您应将此值设置为 OTEL_AWS_APP_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics

    5. 对于 OTEL_METRICS_EXPORTER 变量,我们建议您将该值设置为 none。这将禁用其他指标导出程序,因此仅使用 Application Signals 导出程序。

    6. 对于 OTEL_AWS_APP_SIGNALS_ENABLED 变量,通过将 OTEL_AWS_APP_SIGNALS_ENABLED 设置为 true 来启用 SpanMetricProcessor。这会从跟踪中生成 Application Signals 指标。

  3. 使用上一步中讨论的环境变量启动应用程序。以下是启动脚本的示例。

    • $HOST_ENV 替换为运行应用程序的主机环境。这将作为应用程序的托管环境在 Application Signals 控制面板中显示。

    • $SVC_NAME 替换为您的应用程序的名称。这将作为应用程序的名称在 Application Signals 控制面板中显示。

    • $PYTHON_APP 替换为您的应用程序的位置和名称。

    OTEL_METRICS_EXPORTER=none \ OTEL_LOGS_EXPORTER=none \ OTEL_AWS_APP_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_APP_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \ OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \ OTEL_RESOURCE_ATTRIBUTES=aws.hostedin.environment=$HOST_ENV,service.name=$SVC_NAME \ opentelemetry-instrument python $PYTHON_APP.py

    在为 Python 应用程序启用 Application Signals 之前,请注意以下注意事项。

    • 在某些容器化应用程序中,缺少 PYTHONPATH 环境变量有时可能会导致应用程序无法启动。要解决此问题,请确保将 PYTHONPATH 环境变量设置为应用程序工作目录的位置。这是由于 OpenTelemetry 自动检测的已知问题造成的。有关此问题的更多信息,请参阅 Python autoinstrumentation setting of PYTHONPATH is not compliant(PYTHONPATH 的 Python 自动检测设置不兼容)。

    • 对于 Django 应用程序,还有其他必需的配置,这些配置在 OpenTelemetry Python 文档中进行了概述。

      • 使用 --noreload 标志可防止自动重新加载。

      • DJANGO_SETTINGS_MODULE 环境变量设置为 Django 应用程序 settings.py 文件的位置。这样可确保 OpenTelemetry 能够正确访问您的 Django 设置,并与之集成。