对 Application Signals 安装进行问题排查 - Amazon CloudWatch
启用 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 之前筛选容器日志？

对 Application Signals 安装进行问题排查

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

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

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

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

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

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

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

启用 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）模块格式。目前，AWS 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 代理时应用的权限后来可能被更改或撤销。

  • 生成遥测数据时，请检查 AWS 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 控制台，则在创建或更新附加组件时选择可选配置设置时，会找到冲突解决方法。如果您使用的是 AWS 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 之前筛选容器日志？

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