最佳做法指南：Azure Copilot 可观测性代理（预览版）

Azure Monitor 的 问题和调查功能 使用 Observability Agent（可观测性代理） 来分析 Application Insights 遥测数据，以帮助排查问题。 通过遵循这些最佳做法，可以确保可观测性代理调查具有丰富的数据来生成最相关的见解。

捕获所有请求、依赖项和异常遥测数据

确保从您的应用程序中收集所有的关键遥测类型：

• 请求 （传入 HTTP 调用） - Application Insights 软件开发工具包（SDK）默认自动跟踪许多框架的 Web 请求（例如，ASP.NET/ASP.NET Core）。
• 依赖项 （对外部服务的出站调用） - 大多数 SDK 会自动收集常见依赖项（HTTP 调用、SQL 调用等），如果配置正确。 例如，.NET Application Insights SDK 启用依赖项跟踪模块，该模块会自动记录 HTTP 调用、数据库查询等。 在其他环境（如 Python）中，可能无法现成地捕获某些依赖项。 检查框架的文档，如果未自动收集依赖项，请使用遥测客户端 API 手动跟踪它（例如在 Python 中为 track_dependency 或在 .NET 中为 TrackDependency）。 此方法可确保 Azure Monitor 能够识别服务对数据库、API、存储帐户和其他服务的调用。
• 异常 – 大多数设置中 SDK 会自动记录未经处理的异常。 但是，如果在代码中捕获异常，请确保将它们记录到 Application Insights（例如，通过调用 TelemetryClient.TrackException 的方式），或者在记录日志后重新抛出它们。 每个错误都应显示为 Application Insights 中的异常遥测；否则，可观测性代理可能会错过重要的故障信号。

允许未经处理的异常涌现

确保未经处理的异常冒升到 Application Insights SDK 或 OpenTelemetry，以便可以记录它们。 实际上，此方法意味着应避免捕获异常，除非已记录或重新引发它们。 如果发生异常，则允许异常传播或对异常进行显式跟踪。 此方法允许内置遥测模块观察异常并将其发送到 Application Insights。 未能这样做会导致可观测性代理根本无法观察到的错误。 可观测性代理依赖于异常遥测来查明问题（例如，确定特定异常导致的故障峰值）。 设定一项规则，确保任何关键异常不会被悄无声息地吞没。 如果使用全局错误处理程序，请通过 TelemetryClient.TrackException 或等效的 OpenTelemetry 调用记录异常。 此方法可确保 Azure Monitor 知道发生了错误，并且可观测性代理将其包含在调查结果中。

使用最新的 Application Insights SDK 或 OpenTelemetry 发行版

始终 为应用程序使用最新的官方 Azure Monitor OpenTelemetry SDK 或 Application Insights SDK 。 较新版本包含对最新遥测数据模型的重要修补程序、性能改进和支持。 使用最新版本可确保应用的遥测数据与可观测代理的分析引擎兼容，并发送所有必要的信号。 例如，较新的 SDK 可能会自动捕获比旧版本更多的指标或上下文。 Azure Monitor 团队建议为新应用程序采用基于 OpenTelemetry 的检测，因为它是 Application Insights 的未来。 旧版 SDK 可能还会以效率较低的方式收集遥测数据。 （例如，过时的 .NET SDK 可能会发出过多的计数器作为自定义指标，而较新版本允许筛选这些计数器。升级使你可以更好地控制和与最佳做法保持一致。 简言之，保持工具 SDK 的最新状态可确保您获得完整的功能支持（例如，更新的 Azure 服务的自动依赖项跟踪）和最新的漏洞修复，以提供准确的数据。 这也意味着您的遥测数据包含观察性代理所期望的所有字段。 请始终查看 SDK 发行说明，并将 NuGet/NPM/PyPI 包或 OpenTelemetry 发行版升级到最新的稳定版本。 （如果要从经典 SDK 迁移到 OpenTelemetry，请参阅 官方 Application Insights OpenTelemetry 数据收集 文档以获取指导。

为每个微服务设置云角色名称

如果应用程序由多个服务或组件组成，请为每个服务或组件 分配不同的云角色名称 。 云角色名称是一个遥测属性，用于标识发出遥测的逻辑组件或微服务。 设置此属性对于分布式应用程序至关重要 - 它允许 Azure Monitor 按服务对遥测进行分组。 例如，在 Azure 门户的应用程序映射中，每个节点都标有云角色名称。 在调查期间，具有适当的角色名称意味着可观测性代理可以区分异常源自哪个组件。 如果没有，来自所有服务的数据可能会混合在一起，使分析变得不那么清晰。

默认情况下，Application Insights SDK 和 Azure Monitor OpenTelemetry 会尝试填充角色名称（例如，使用云服务名称或条目程序集名称）。 但是，最好 用一个对应用体系结构有意义的名称覆盖它。 例如，将“OrderingService”、“InventoryAPI”和其他名称设置为角色名称，而不是泛型默认值。 在代码中，可以通过配置或遥测初始化器设置此属性。 在 .NET 中，您可以执行以下操作：TelemetryClient.Context.Cloud.RoleName = "InventoryAPI"; 在 OpenTelemetry（Azure Monitor 发行版）中，可以配置资源属性，例如service.nameservice.namespace，确定云角色名称和实例。 了解如何使用不同语言执行此配置。

为什么此属性很重要？ 可观测性代理将事件在微服务之间进行关联。 如果每个遥测项知道它来自哪个微服务，那么可观测性代理就可以识别，例如，“服务 A 由于遇到缓慢的依赖项，导致服务 B 出现故障。”这样你就可以更清楚地了解跨服务的问题。 因此，为所有组件（包括后台服务和函数）一致地设置云角色名称，以便分布式遥测按角色正确隔离。

使用一致且可预测的资源命名

对 Azure 资源（遥测中的组件）使用 标准命名约定 ，以便其用途清晰且计算机可读。 一般情况下，一致的命名是 Azure 最佳做法，但此处我们强调它甚至有助于观察性代理。 当资源名称可预测并包含关键上下文时，调查摘要和相关性更易于理解。

请考虑遵循 Azure 的准则。 例如，在名称中包含资源类型的指示器和有意义的标识符（例如 prod-web-eastus-001 Web 应用）。 此外， 请参阅资源缩写的官方列表，以保持名称简洁但信息丰富。

为什么此方法对于调查很重要：可观测性代理的调查摘要提到问题中涉及的资源名称。 如果这些名称明确，你和生成解释的可观测性代理程序就可以更轻松地推断出每个资源的角色。 例如，一个发现可能指出 “虚拟机（VM）vm-app-prod-01 的 CPU 使用率过高……” - 类似 vm-app-prod-01 这样的名称已经告诉你，该服务器是生产应用服务器 VM。 如果它被模糊命名（例如， contoso123），摘要将更难解释。 此外，跨资源一致的命名意味着结构;可观测性代理可能按名称模式对相关资源进行分组（例如，在其名称中指出具有“inventory”的多个组件）。

此外，在遥测中，如果使用自定义维度或云角色名称，也会对这些项应用一致的命名。 适当时，请使用与资源名称相同的术语。 目标是避免混淆，使各个环节之间的联系更加清晰明了。 Azure Monitor 的分析确实包含资源元数据（如资源类型），但一个好名称有助于每个人（人类和可观测性代理）快速掌握方案。

简言之，请采用命名约定并坚持它。 这是一个简单的步骤，导致更易读的调查输出和更流畅的协作。 与其他人共享问题时，他们可以轻松地从名称中识别资源。 如果需要指导，请使用链接的文档获取最佳做法和缩写标准。

在遥测中包括资源上下文，以实现自动范围界定

可观测性代理可以在检测到相关信号时 自动将其范围扩展到相关资源 。 可以通过在遥测数据中包含资源标识符来帮助此功能。 实际上，此方法意味着：当代码与 Azure 资源（或任何外部资源）交互时，请在遥测数据中提供该资源的一些标识符。

例： 假设应用调用 Azure 存储队列或 Azure SQL 数据库。 如果使用 Application Insights SDK 的依赖项跟踪，则会自动记录目标终结点（例如队列 URL 或数据库名称）。 确保启用此功能，因为它在依赖项遥测中本质上承载资源标识（如 Azure 资源的名称或 URL）。 在自定义日志记录方案中，可以添加自定义属性，例如 "AzureResourceId" 或将资源名称包含在遥测消息中。

在现代云环境中，尤其是在应用程序在 Azure Kubernetes 服务（AKS）上运行时，在遥测中捕获群集上下文也很重要。 目前在 AKS 上运行的许多微服务不会使用群集或 Pod 信息标记其遥测数据，这限制了可观测性代理将应用程序问题与群集级事件连接的能力。 为了应对这一限制：

• 尽可能使用 AKS 自动仪表化（预览版）： 对于 AKS 上的 Java 和 Node.js 工作负载，Azure Monitor 提供无代码自动仪表化功能，Azure Monitor 的 OpenTelemetry 代理能够在不更改代码的情况下注入至 Pod。 此功能使用群集元数据（例如群集名称、命名空间和 Pod 标识符）以及应用程序数据自动扩充遥测数据。 （请参阅 使用 Azure Monitor Application Insights 在 AKS 上监视应用程序（预览版）， 了解如何启用此功能。

• 为其他方案手动添加群集元数据： 如果自动结构不适用于技术堆栈（例如 AKS 上的 .NET 或 Python 应用），请像往常一样使用 Application Insights SDK 或 OpenTelemetry 检测应用程序，但将 Kubernetes 上下文作为自定义维度包含在内。 例如，.NET 服务可以使用 Application Insights for Kubernetes 官方库 自动将群集名称、命名空间、Pod 和节点信息附加到每个遥测项。 在任何语言中，还可以实现遥测初始值设定项或类似机制，以便将这些详细信息添加到每个遥测事件。

通过提供此类资源上下文（例如特定的资源标识符或群集详细信息），使可观测性代理能够执行自动域界定，其中包括调查分析中的相关资源。 此功能会导致更全面的调查，这些调查不仅考虑了应用程序，还考虑了可能导致问题的上游或底层基础结构组件。 例如，如果应用中的故障峰值与 AKS 群集中的节点问题或 Pod 重启相吻合，则如果具有群集上下文，可观测性代理可能会显示该连接。 简言之，进行检测时应始终考虑资源上下文，以便可观测性代理在故障排除期间能够全面掌握信息。

避免重写遥测属性 - 使用自定义维度

Application Insights 遥测项附带一组标准属性（上下文字段），例如操作 ID、操作名称、用户 ID、会话 ID、云角色等。请勿替代或重新利用这些自定义数据的内置属性。 这样做可能会混淆遥测关联和可观测性代理的分析。 而是将任何自定义业务数据附加为 自定义维度 （也称为自定义属性）。

原因：Azure Monitor 将标准遥测上下文字段用于特定目的。 例如，operation_Id 和 operation_ParentId 将分布式跟踪中的相关调用关联起来，user_Id 和 session_Id 帮助归组用户会话等。 如果您用某些特定于应用程序的含义替代操作名称或用户 ID，会破坏其预期的用途，并且监测代理程序可能无法再正确进行事件关联。 （有关这些字段及其角色的参考信息，请参阅 Application Insights 遥测数据模型 。

最佳做法： 若要记录详细信息（例如订单 ID、客户层或任何特定于域的上下文），请使用遥测 API 添加自定义属性。 例如，使用 .NET SDK，可以通过遥测项（TrackEvent(..., properties) 或 TrackTrace(..., properties)）上的 Properties 字典添加自定义键值对。 这些对在日志中显示为自定义维度。 同样，在其他语言或 OpenTelemetry 中，可以将属性/标记附加到跨度或日志。 通过将数据保留在自定义维度中，可以确保内置架构保持不变，以供 Azure Monitor 使用。

此方法使标准遥测保持一致，但仍允许扩充数据。 可观测性代理在相关时在支持数据中包含自定义维度，但此方法不会中断遥测关联的方式。 例如，如果要使用特定业务事务 ID 标记请求，请不要尝试劫持操作 ID；而是将其添加为单独的属性（例如 "TransactionId"）。 这样，可观测性代理仍然可以遵循操作 ID，将请求与依赖项和异常链接，而您的自定义“事务 ID”（TransactionId）提供了更多上下文。

简言之，将默认遥测属性视同保留的，仅将其设置为预期值。 将任何额外信息放入自定义维度。 此方法可产生清晰、结构化良好的遥测数据，可观测性代理可以有效地使用。

使用自定义事件和操作实施关键操作步骤

默认的监测工具并不会捕获应用程序中的每一个重要活动。 使用自定义遥测（如 TrackEvent 和 StartOperation）检测代码的关键部分，尤其是那些处理后台处理、队列消息或任何重要业务逻辑的部分。 此方法可确保有意义的操作对观测代理可见。

使用 TrackEvent（自定义事件） 记录高级业务或功能事件。 例如，可以在订单或批处理作业启动时跟踪事件。 这些事件可以包括详细信息的自定义维度（例如 OrderID、amount）。 对于调查而言，它们非常有用，因为它们可以将系统中的重要事件与基本请求流程区分开来。 如果问题与特定序列（例如，处理队列消息）相关，则具有“QueueMessageReceived”或“QueueMessageProcessed”的自定义事件可以帮助可观测代理确定出现问题的位置。 （至少，你可以通过查看事件的时间线来关联流中发生异常的位置。）

使用 StartOperation/StopOperation（自定义操作）跟踪超出单个请求或依赖项调用的长时间运行或异步进程。 Application Insights .NET SDK 提供了一个 StartOperation<T> API，该 API 使用其自己的持续时间和上下文创建新的遥测操作（例如 RequestTelemetry 或 DependencyTelemetry）。 可以使用此 API 手动划定操作，跟踪其范围内的遥测数据，然后完成该操作。 例如，如果服务从 Azure 队列拉取消息并处理该消息，则可以将该过程视为自定义作：在开始处理队列消息时启动遥测作，并在完成后停止该消息。 在该范围内，任何跟踪的子调用或异常都可以与该操作关联。 此方法提供了该工作单元的完整图。 Azure Monitor 将它视为类似于请求：在门户中看到该请求的持续时间、成功/失败、子依赖项等，可观测性代理可以像任何其他请求一样进行分析。

模式： 许多模式（如队列处理、批处理作业或计划任务）都需要手动检测，因为它们不是 SDK 自动收集的 HTTP 请求。 在应用中识别这些操作，并适当地添加遥测。 在 .NET 中使用 TelemetryClient.StartOperation()（或使用其他语言中的等效功能）开始跟踪，并确保调用 StopOperation()（或释放该操作），以便在正确的时机发送遥测数据。 在该操作中，根据需要使用TrackException、TrackEvent、TrackTrace以记录详细信息。

通过检测关键工作流：

• 使不可见的进程对可观测代理可见。
• 可观测性代理然后可以考虑这些自定义操作和事件。 例如，如果特定的后台任务导致了问题，StartOperation 中的遥测数据会清楚显示出来，可能会以一个发现的形式浮现出来（如“2AM 夜间同步作业期间出现问题”）。
• 此外，您还可以获得更深入的见解，以便在不依赖可观测性代理的情况下进行故障排除。

有关此方法的详细信息，请参阅 使用 Application Insights .NET SDK 跟踪自定义作指南，该 SDK 提供了手动作跟踪（传入请求模拟、队列方案等）的模式，以及 有关使用 TrackEvent 和其他 API 的本指南。

在 Application Insights 中收集和跟踪详细日志

在 Application Insights 遥测中启用 跟踪日志（日志消息）的收集，并合理使用它们。 跟踪（也称为日志）是应用程序发出的文本消息，例如，通过记录器编写的调试日志或信息日志。 这些跟踪不会直接引发警报，但它们提供了应用程序活动的痕迹导航跟踪，这在可观测性代理的调查期间可能非常宝贵。

如何确保跟踪收集： 如果使用 .NET，请确保 Application Insights 与日志记录框架（ILogger、log4net、NLog 等）集成，或用于 TelemetryClient.TrackTrace 重要消息。 在 Java、Node.js、Python 等平台上，将 Azure Monitor 导出程序或 OpenTelemetry SDK 与您的日志系统集成，或显式发送跟踪遥测数据。 例如，Python 的 Azure Monitor 集成可以捕获标准日志记录模块的日志记录，而对于其他语言，您可能会使用 OpenTelemetry 的日志记录检测工具。目标是让您的诊断消息最终出现在 Azure Monitor 中的 Application Insights "跟踪" 表中。 检查是否可以在门户中查看日志消息（在 日志 > 跟踪下）。 否则，请参阅平台特定文档以启用 Application Insights 日志收集（例如，请查看 在 Application Insights 中探索 .NET 跟踪日志，或者使用适用于 Java 和 Python 等语言的 Azure Monitor OpenTelemetry 发行版）。

为什么这很重要： 在调查期间，可观测代理会对每个异常事件分析跟踪日志。 例如，如果调查发现异常出现峰值，相关的跟踪日志可以帮助可观测性代理优化调查结果（这可能是由于正在进行特定操作或处理特定输入）。 放置良好的跟踪语句（如输入函数、某些变量的值或某些步骤的完成）可以阐明异常的原因。 此跟踪能充当指引，并可供可观测性代理用于摘要，以提供可能的解释以及接下来该做什么。

跟踪的最佳做法： 在生产环境中至少收集Information级别或更低级别的日志（可以根据需要调整详细程度）。 在日志消息中包含相关上下文，但避免过于冗长的日志记录，这可能会导致信号与噪音混淆。 确保每个日志都有一些上下文标识符（例如操作 ID 或关联 ID）。如果使用 SDK 的日志记录集成，Application Insights 会自动附加这些 ID。 当与自定义操作或事件配对时，跟踪特别有用 - 在关键部分记录日志，以便逐步了解发生的情况。

总之， 不要只依赖于高级遥测。 细粒度跟踪数据通常对可观测性代理的“情况”提供“解释”。启用跟踪收集，并在诊断 Azure Monitor 显示的问题时利用此功能。

创建 Application Insights 可用性测试

使用 Application Insights 为应用程序设置 可用性测试 。 可用性测试（也称为 Web 测试或 Ping 测试）按计划从各种位置主动地对您的应用程序的终结点进行 Ping 操作。 它们有助于提前检测停机时间或极端减速，并与 Azure Monitor 警报集成。 通过创建可用性测试，可确保如果应用无法访问，警报会触发，Azure Monitor 可以启动对问题的可观测性代理调查。

如何使用： 在 Application Insights 中，可以创建不同类型的可用性测试：

• 简单的 URL ping 测试（现在被标准测试取代），它会命中给定 URL 并检查它在超时内是否成功响应。
• 标准可用性测试，允许更多配置（HTTP 方法、成功条件等）。

出于大多数目的，建议在关键终结点（例如主页、API 登录接口、重要的健康检查）上设置几个标准可用性测试。 可以在 Azure 门户的 Application Insights 资源的 可用性 窗格下进行此设置。 选择测试类型、频率（例如每 5 分钟），以及世界各地的测试位置。 为测试失败启用警报，以便在终结点关闭时生成 Azure Monitor 警报。

为什么它很重要： 可观测性代理支持 Application Insights 警报，其中包括可用性测试。 当可用性测试检测到问题时，它们可能会触发调查，以帮助确定服务不可用的根本原因。

相关内容

• Azure Copilot 监测代理概述
• Azure Monitor 问题和调查（预览版）概述
• 使用 Azure Monitor 问题和调查
• Azure Copilot 可观测性代理的负责任使用