对 Application Signals 安装进行问题排查 - Amazon CloudWatch
Application Signals Java 层冷启动性能启用 Application Signals 后，应用程序无法启动启用 Application Signals 后，Python 应用程序无法启动使用 WSGI 服务器的 Python 应用程序没有 Application Signals 数据我的 Node.js 应用程序没有经过检测或者没有生成 Application Signals 遥测Application Signals 控制面板中没有应用程序数据服务指标或依赖项指标具有未知值管理 Amazon CloudWatch Observability EKS 附加组件时处理 ConfigurationConflict我想过滤掉不必要的指标和跟踪InternalOperation 表示什么？如何为 .NET 应用程序启用日志记录？如何解决 .NET 应用程序中的程序集版本冲突？我能禁用 FluentBit 吗？是否可以在导出到 CloudWatch Logs 之前筛选容器日志？ 更新至所需版本的代理或 Amazon EKS 加载项
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

对 Application Signals 安装进行问题排查

本节包含有关 CloudWatch Application Signals 的问题排查提示。

Application Signals Java 层冷启动性能

向 Java Lambda 函数添加 Application Signals 层会增加启动延迟（冷启动时间）。以下提示可以帮助减少时间敏感型函数的延迟。

Java 代理的快速启动 – Application Signals Java Lambda 层包含一项快速启动功能，该功能默认处于关闭状态，但将 OTEL_JAVA_AGENT_FAST_STARTUP_ENABLED 变量设置为 true 可以启用该功能。此功能启用后，会将 JVM 配置为使用分层编译级别 1 C1 编译器来生成快速优化的原生代码，从而加快冷启动速度。C1 编译器优先考虑速度，但牺牲了长期优化，而 C2 编译器则随时间推移来分析数据，从而提供卓越的整体性能。

有关更多信息，请参阅 Fast startup for Java agent。

使用预置并发缩短冷启动时间 – Amazon Lambda 预置并发会预先分配指定数量的函数实例，使其保持初始化状态并随时做好立即处理请求的准备。这样就无需在执行过程中初始化函数环境，缩短了冷启动时间，从而确保性能更快且更一致，对于延迟敏感型工作负载而言，尤其如此。有关更多信息，请参阅为函数配置预置并发。

使用 Lambda SnapStart 优化启动性能 – Amazon Lambda SnapStart 是一项功能，通过在函数的初始化阶段之后创建执行环境的预初始化快照来优化 Lambda 函数的启动性能。然后，该快照会被重复用于启动新实例，跳过函数调用期间的初始化过程，从而显著缩短冷启动时间。有关信息，请参阅使用 Lambda SnapStart 提高启动性能。

启用 Application Signals 后，应用程序无法启动

如果您在 Amazon EKS 集群上启用 Application Signals 后，该集群上的应用程序仍未启动，请检查以下内容：

  • 检查应用程序是否已被其他监控解决方案检测过。Application Signals 可能不支持与其他检测解决方案共存。

  • 确认您的应用程序符合使用 Application Signals 的兼容性要求。有关更多信息，请参阅 支持的系统。

  • 如果您的应用程序未能拉取 Application Signals 构件，例如 Amazon Distro for OpenTelemetery Java 或 Python 代理和 CloudWatch 代理映像，则可能是网络问题。

要缓解此问题，请从应用程序部署清单中移除注释 instrumentation.opentelemetry.io/inject-java: "true" 或 instrumentation.opentelemetry.io/inject-python: "true"，然后重新部署您的应用程序。然后检查应用程序是否正在运行。

已知问题

众所周知，Java SDK 版本 v1.32.5 中的运行时指标收集不适用于使用 JBoss Wildfly 的应用程序。此问题扩展到 Amazon CloudWatch 可观测性 EKS 附加组件，影响版本 2.3.0-eksbuild.1 至 2.5.0-eksbuild.1。

如果您受到影响，请降级版本或通过向应用程序添加环境变量 OTEL_AWS_APPLICATION_SIGNALS_RUNTIME_ENABLED=false 来禁用运行时指标收集。

启用 Application Signals 后，Python 应用程序无法启动

OpenTelemetry 自动检测中的一个已知问题是，缺少 PYTHONPATH 环境变量有时会导致应用程序无法启动。要解决此问题，请确保将 PYTHONPATH 环境变量设置为应用程序工作目录的位置。有关此问题的更多信息，请参阅 Python autoinstrumentation setting of PYTHONPATH is not compliant with Python's module resolution behavior, breaking Django applications。

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

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

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

使用 WSGI 服务器的 Python 应用程序没有 Application Signals 数据

如果使用的是 Gunicorn 或 uWSGI 之类的 WSGI 服务器，您必须进行其他更改才能使 ADOT Python 自动检测正常工作。

注意

在继续操作之前，请确保您使用的是最新版本的 ADOT Python 和 Amazon CloudWatch Observability EKS 加载项。

使用 WSGI 服务器启用 Application Signals 的其他步骤

  1. 在分支的工作进程中导入自动检测。

    对于 Gunicorn，使用 post_fork 钩子：

    # gunicorn.conf.py
def post_fork(server, worker):
    from opentelemetry.instrumentation.auto_instrumentation import sitecustomize

    对于 uWSGI，使用 import 指令。

    #  uwsgi.ini
[uwsgi]
; required for the instrumentation of worker processes
enable-threads = true
lazy-apps = true
import = opentelemetry.instrumentation.auto_instrumentation.sitecustomize

  2. 通过将 OTEL_AWS_PYTHON_DEFER_TO_WORKERS_ENABLED 环境变量设置为 true，启用 ADOT Python 自动检测的配置，以跳过主进程并推迟到工作线程。

我的 Node.js 应用程序没有经过检测或者没有生成 Application Signals 遥测

要为 Node.js 启用 Application Signals，您必须确保 Node.js 应用程序使用 CommonJS（CJS）模块格式。目前，Amazon Distro for OpenTelemetry Node.js 不支持 ESM 模块格式，因为 OpenTelemetry JavaScript 对 ESM 的支持处于实验阶段且仍在进行中。

要确定您的应用程序是否使用 CJS 而不是 ESM，请确保您的应用程序不满足启用 ESM 的条件。

Application Signals 控制面板中没有应用程序数据

如果 Application Signals 控制面板中缺少指标或跟踪，则可能是以下原因。只有在自上次更新以来等待 Application Signals 收集和显示数据的时间达到 15 分钟时，才调查这些原因。

  • 确保您正在使用的库和框架受 ADOT Java 代理的支持。有关更多信息，请参阅库/框架。

  • 确保 CloudWatch 代理正在运行。首先检查 CloudWatch 代理容器组（pod）的状态，并确保它们都处于 Running 状态。

    kubectl -n amazon-cloudwatch get pods.

    将以下内容添加到 CloudWatch 代理配置文件中以启用调试日志，然后重新启动代理。

    "agent": {

  "region": "${REGION}",
  "debug": true
},

    然后检查 CloudWatch 代理容器组（pod）中是否存在错误。

  • 检查 CloudWatch 代理的配置问题。确认以下内容仍在 CloudWatch 代理配置文件中，并且自添加以来，代理曾重新启动。

    "agent": {
  "region": "${REGION}",
  "debug": true
},

    然后查看 OpenTelemetry 调试日志中是否有错误消息，例如 ERROR io.opentelemetry.exporter.internal.grpc.OkHttpGrpcExporter - Failed to export ...。这些消息可能表明问题所在。

    如果这不能解决问题，请使用 OTEL_ 命令描述容器组（pod），来转储并检查名称以 kubectl describe pod 开头的环境变量。

  • 要启用 OpenTelemetry Python 调试日志记录，请将环境变量 OTEL_PYTHON_LOG_LEVEL 设置为 debug 并重新部署应用程序。

  • 检查从 CloudWatch 代理导出数据的权限是否错误或不足。如果您在 CloudWatch 代理日志中看到 Access Denied 消息，则可能是问题所在。您安装 CloudWatch 代理时应用的权限后来可能被更改或撤销。

  • 生成遥测数据时，请检查 Amazon Distro for OpenTelemetry（ADOT）问题。

    确保检测注释 instrumentation.opentelemetry.io/inject-java 和 sidecar.opentelemetry.io/inject-java 已应用于应用程序部署，其值为 true。如果没有这些注释，即使 ADOT 附加组件安装正确，也不会对应用程序容器组（pod）进行检测。

    接下来，检查 init 容器是否已应用于应用程序且 Ready 状态为 True。如果 init 容器未准备就绪，请查看状态以了解原因。

    如果问题仍然存在，则请通过将环境变量 OTEL_JAVAAGENT_DEBUG 设置为 true 并重新部署应用程序来启用 OpenTelemetry Java SDK 的调试日志记录。然后查找以 ERROR io.telemetry 开头的消息。

  • 指标/跨度导出程序可能正在删除数据。要找出答案，请查看应用程序日志中是否有包含 Failed to export... 的消息

  • 向 Application Signals 发送指标或跨度时，CloudWatch 代理可能会受到限制。检查 CloudWatch 代理日志中是否有指示节流的消息。

  • 确保您已启用服务发现设置。您只需在您的区域中执行一次此操作。

    要进行确认，在 CloudWatch 控制台中，依次选择 Application Signals、服务。如果步骤 1 未标记为完成，则请选择开始发现您的服务。数据应在五分钟内开始流入。

服务指标或依赖项指标具有未知值

如果您在 Application Signals 控制面板中看到依赖项名称或操作的 UnknownService、UnknownOperation、UnknownRemoteService 或 UnknownRemoteOperation，则请检查未知远程服务和未知远程操作数据点的出现是否与其部署一致。

  • UnknownService 表示检测的应用程序名称未知。如果 OTEL_SERVICE_NAME 环境变量未定义且未在 OTEL_RESOURCE_ATTRIBUTES 中指定 service.name，则服务名称将设置为 UnknownService。要解决此问题，请在 OTEL_SERVICE_NAME 或 OTEL_RESOURCE_ATTRIBUTES 中指定服务名称。

  • UnknownOperation 表示所调用的操作名称未知。当 Application Signals 无法发现调用远程调用的操作名称，或者提取的操作名称包含高基数值时，就会发生这种情况。

  • UnknownRemoteService 表示目标服务的名称未知。系统无法提取远程调用访问的目标服务名称时，就会发生这种情况。

    一种解决方案是围绕发送请求的函数创建一个自定义跨度，然后添加具有指定值的属性 aws.remote.service。另一种选择是配置 CloudWatch 代理以自定义 RemoteService 的指标值。有关 CloudWatch 代理中自定义的更多信息，请参阅 启用 CloudWatch Application Signals。

  • UnknownRemoteOperation 表示目标操作的名称未知。系统无法提取远程调用访问的目标操作名称时，就会发生这种情况。

    一种解决方案是围绕发送请求的函数创建一个自定义跨度，然后添加具有指定值的属性 aws.remote.operation。另一种选择是配置 CloudWatch 代理以自定义 RemoteOperation 的指标值。有关 CloudWatch 代理中自定义的更多信息，请参阅 启用 CloudWatch Application Signals。

管理 Amazon CloudWatch Observability EKS 附加组件时处理 ConfigurationConflict

在安装或更新 Amazon CloudWatch Observability EKS 附加组件时，如果您发现故障是由 ConfigurationConflict 类型的 Health Issue（其描述以 Conflicts found when trying to apply. Will not continue due to resolve conflicts mode 开头）引起的，这可能是因为您已经在集群上安装了 CloudWatch 代理及其相关组件，例如 ServiceAccount、ClusterRole 和 ClusterRoleBinding。当附加组件尝试安装 CloudWatch 代理及其关联组件时，如果检测到内容有任何变化，在默认情况下这会使安装或更新失败，以避免覆盖集群上资源的状态。

如果您正在尝试载入 Amazon CloudWatch Observability EKS 附加组件，但出现此故障，我们建议您删除之前在集群上安装的现有 CloudWatch 代理设置，然后安装 EKS 附加组件。请务必备份您可能对原始 CloudWatch 代理设置所做的任何自定义，例如自定义代理配置，并在下次安装或更新时将其提供给 Amazon CloudWatch Observability EKS 附加组件。如果您之前安装了 CloudWatch 代理以载入 Container Insights，请参阅 删除 Container Insights 的 CloudWatch 代理和 Fluent Bit 获取更多信息。

或者，该附加组件支持具有指定 OVERWRITE 功能的冲突解决配置选项。您可以使用此选项，通过覆盖集群上的冲突来继续安装或更新附加组件。如果您使用的是 Amazon EKS 控制台，则在创建或更新附加组件时选择可选配置设置时，会找到冲突解决方法。如果您使用的是 Amazon CLI，则可以在命令中提供 --resolve-conflicts OVERWRITE，以创建或更新附加组件。

我想过滤掉不必要的指标和跟踪

如果 Application Signals 正在收集您不想要的跟踪和指标，则请参阅 管理高基数操作，了解有关使用自定义规则配置 CloudWatch 代理以减少基数的信息。

有关自定义跟踪采样规则的信息，请参阅 X-Ray 文档中的 Configure sampling rules。

InternalOperation 表示什么？

InternalOperation 表示由应用程序内部而不是外部调用触发的操作。看到 InternalOperation 是预期的正常行为。

以下是一些可以看到 InternalOperation 的典型示例：

  • 启动时预加载：您的应用程序执行名为 loadDatafromDB 的操作，该操作在预热阶段从数据库中读取元数据。您不会将 loadDatafromDB 视为服务操作，而是将其归类为 InternalOperation。

  • 后台异步执行：您的应用程序订阅事件队列，并在有更新时相应地处理流数据。每个触发的操作都将作为服务操作置于 InternalOperation 下。

  • 从服务注册表检索主机信息：您的应用程序与服务注册表对话以进行服务发现。与发现系统的所有交互都归类为 InternalOperation。

如何为 .NET 应用程序启用日志记录？

要为 .NET 应用程序启用日志记录，请配置以下环境变量。有关如何配置这些环境变量的更多信息，请参阅 OpenTelemetry 文档中的 .NET 自动仪表化问题的故障排除。

  • OTEL_LOG_LEVEL

  • OTEL_DOTNET_AUTO_LOG_DIRECTORY

  • COREHOST_TRACE

  • COREHOST_TRACEFILE

如何解决 .NET 应用程序中的程序集版本冲突？

如果您遇到以下错误，请参阅 OpenTelemetry 文档中的程序集版本冲突以了解解决步骤。

Unhandled exception. System.IO.FileNotFoundException: Could not load file or assembly 'Microsoft.Extensions.DependencyInjection.Abstractions, Version=7.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'. The system cannot find the file specified.

File name: 'Microsoft.Extensions.DependencyInjection.Abstractions, Version=7.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'
   at Microsoft.AspNetCore.Builder.WebApplicationBuilder..ctor(WebApplicationOptions options, Action`1 configureDefaults)
   at Microsoft.AspNetCore.Builder.WebApplication.CreateBuilder(String[] args)
   at Program.<Main>$(String[] args) in /Blog.Core/Blog.Core.Api/Program.cs:line 26

我能禁用 FluentBit 吗？

您可以通过配置 Amazon CloudWatch 可观测性 EKS 加载项来禁用 FluentBit。有关更多信息，请参阅 （可选）其他配置。

是否可以在导出到 CloudWatch Logs 之前筛选容器日志？

不能，尚不支持筛选容器日志。

更新至所需版本的代理或 Amazon EKS 加载项

2024 年 8 月 9 日之后，CloudWatch Application Signals 将不再支持旧版的 Amazon CloudWatch 可观测性 EKS 加载项、CloudWatch 代理和 Amazon Distro for OpenTelemetry 自动检测代理。

  • 对于 Amazon CloudWatch 可观测性 EKS 加载项，将不支持早于 v1.7.0-eksbuild.1 的版本。

  • 对于 CloudWatch 代理，将不支持早于 1.300040.0 的版本。

  • 对于 Amazon Distro for OpenTelemetry 自动检测代理：

    • 对于 Java，不支持早于 1.32.2 的版本。

    • 对于 Python，不支持早于 0.2.0 的版本。

    • 对于 .NET，不支持早于 1.3.2 的版本。

    • 对于 Node.js，不支持早于 0.3.0 的版本。

重要

最新版本的代理包括对 Application Signals 指标架构的更新。这些更新不向后兼容，如果使用不兼容的版本，则可能会导致数据问题。为确保无缝过渡到新功能，请执行以下操作：

  • 如果您的应用程序在 Amazon EKS 上运行，则请务必在更新 Amazon CloudWatch Observability 加载项后重新启动所有已检测的应用程序。

  • 对于在其他平台上运行的应用程序，请确保将 CloudWatch 代理和 Amazon OpenTelemetry 自动检测代理同时升级到最新版本。

以下各节中的说明可以帮助您更新到支持的版本。

更新 Amazon CloudWatch 可观测性 EKS 加载项

要更新 Amazon CloudWatch 可观测性 EKS 加载项，您可以使用 Amazon Web Services Management Console 或 Amazon CLI。

使用控制台

使用控制台升级加载项

  1. 从以下位置打开 Amazon EKS 控制台：https://console.aws.amazon.com/eks/home#/clusters。

  2. 选择要更新的 Amazon EKS 集群的名称。

  3. 选择加载项选项卡，然后选择 Amazon CloudWatch 可观测性。

  4. 依次选择编辑、要更新到的版本和保存更改。

    请务必选择 v1.7.0-eksbuild.1 或更高版本。

  5. 输入以下 Amazon CLI 命令之一以重新启动服务。

      # Restart a deployment
  kubectl rollout restart deployment/name
  # Restart a daemonset
  kubectl rollout restart daemonset/name
  # Restart a statefulset
  kubectl rollout restart statefulset/name

使用 Amazon CLI

使用 Amazon CLI 升级加载项

  1. 输入以下命令以查找最新版本。

    aws eks describe-addon-versions \
--addon-name amazon-cloudwatch-observability

  2. 输入以下命令以更新加载项。将 $VERSION 替换为版本 v1.7.0-eksbuild.1 或更高版本。将 $AWS_REGION 和 $CLUSTER 替换为您的区域和集群名称。

    aws eks update-addon \
--region $AWS_REGION \
--cluster-name $CLUSTER \
--addon-name amazon-cloudwatch-observability \
--addon-version $VERSION \
# required only if the advanced configuration is used.
--configuration-values $JSON_CONFIG
    注意

    如果您为加载项使用自定义配置，则可以在 启用 CloudWatch Application Signals 中找到用于 $JSON_CONFIG 的配置示例。

  3. 输入以下 Amazon CLI 命令之一以重新启动服务。

      # Restart a deployment
  kubectl rollout restart deployment/name
  # Restart a daemonset
  kubectl rollout restart daemonset/name
  # Restart a statefulset
  kubectl rollout restart statefulset/name

更新 CloudWatch 代理和 ADOT 代理

如果您的服务在 Amazon EKS 以外的架构上运行，则需要同时升级 CloudWatch 代理和 ADOT 自动检测代理才能使用最新的 Application Signals 功能。

在 Amazon ECS 上更新

为在 Amazon ECS 上运行的服务升级您的代理

  1. 创建新的任务定义修订。有关更多信息，请参阅使用控制台更新任务定义。

  2. 将 ecs-cwagent 容器的 $IMAGE 替换为 Amazon ECR 上 cloudwatch-agent 的最新映像标签。

    如果您升级到固定版本，则请务必使用版本 1.300040.0 或更高版本。

  3. 将 init 容器的 $IMAGE 替换为以下位置的最新映像标签：

  4. 按照 步骤 4：使用 CloudWatch 代理检测您的应用程序 中的说明更新应用程序容器中的 Application Signals 环境变量。

  5. 使用新任务定义部署服务。

在 Amazon EC2 或其他架构上进行更新

为在 Amazon ECS 或其他架构上运行的服务升级您的代理

  1. 按照 下载 CloudWatch 代理软件包 中的说明操作，将 CloudWatch 代理升级到最新版本。请务必选择版本 1.300040.0 或更高版本。

  2. 从以下位置之一下载最新版本的 Amazon Distro for OpenTelemetry 自动检测代理：

  3. 将更新的 Application Signals 环境变量应用于您的应用程序，然后启动该应用程序。有关更多信息，请参阅 步骤 3：检测您的应用程序并将其启动。