排查在 Azure Monitor 中收集 Prometheus 指标时出现的问题

项目
12/18/2024

按照本文中的步骤确定无法在 Azure Monitor 中按预期方式收集 Prometheus 指标的原因。

副本 Pod 从 kube-state-metrics 中抓取指标，抓取 ama-metrics-prometheus-config configmap 中的自定义抓取目标，并抓取自定义资源中定义的自定义抓取指标。 DaemonSet Pod 从其各自节点上的以下目标抓取指标：kubelet、cAdvisor、node-exporter 和 ama-metrics-prometheus-config-node configmap 中的自定义抓取目标。要查看日志和 Prometheus UI 的 Pod 将取决于正在调查的抓取目标。

使用 PowerShell 脚本进行故障排除

如果在尝试为 AKS 群集启用监视时遇到错误，请按照以下说明运行故障排除脚本。此脚本旨在就群集上是否存在配置问题进行基本诊断，你可以在创建支持请求时附加生成的文件，以便更快地解决支持案例。

指标限制

适用于 Prometheus 的 Azure Monitor 托管服务具有用于引入的默认限制和配额。达到引入限制时，可能会发生限制。可以请求增加这些限制。有关 Prometheus 指标限制的信息，请参阅Azure Monitor 服务限制。

在 Azure 门户中，导航到你的 Azure Monitor 工作区。转到 Metrics，然后选择指标 Active Time Series % Utilization 和 Events Per Minute Received % Utilization。验证两者是否都低于 100%。

若要详细了解如何监视引入指标并针对其发出警报，请参阅监视 Azure Monitor 工作区指标引入。

指标数据收集中的间歇性间隙

在节点更新期间，对于从群集级别收集器收集的指标，你可能会在指标数据中看到 1 到 2 分钟的间隙。之所以存在此间隙，是因为运行它的节点正在更新，作为正常更新过程的一部分。这会影响群集范围内的目标，例如 kube-state-metrics 和指定的自定义应用程序目标。手动更新群集或自动更新时，会出现这种情况。此行为是预期行为，它的发生是由于它基于的节点正在更新。我们推荐的警报规则均不受此行为的影响。

Pod 状态

使用以下命令检查 pod 状态：

kubectl get pods -n kube-system | grep ama-metrics

当服务正常运行时，会返回以下格式为 ama-metrics-xxxxxxxxxx-xxxxx 的 Pod 的列表：

ama-metrics-operator-targets-*
ama-metrics-ksm-*
ama-metrics-node-* Pod（适用于群集中的每个节点）。

每个 pod 的状态应为 Running，并且重启次数与已应用的 configmap 更改次数相等。 ama-metrics-operator-targets-* Pod 在开始时可能会有额外的重启，这是预期的：

如果每个 pod 的状态为 Running，但有一个或多个 pod 重启，请运行以下命令：

kubectl describe pod <ama-metrics pod name> -n kube-system

此命令会提供重启的原因。如果已进行 configmap 更改，则需要重启 pod。如果重启的原因是 OOMKilled，则 pod 无法与指标量保持一致。请参阅有关指标量的缩放建议。

如果 pod 按预期方式运行，则接下来请检查容器日志。

检查重新标记配置

如果缺少指标，还可以检查是否有重新标记配置。使用重新标记配置时，请确保重新标记不会筛选掉目标，并且配置的标签与目标正确匹配。有关详细信息，请参阅 Prometheus 重新标记配置文档。

容器日志

使用以下命令查看容器日志：

kubectl logs <ama-metrics pod name> -n kube-system -c prometheus-collector

启动时，任何初始错误都以红色显示，而警告则以黄色显示。（至少需要安装 PowerShell 版本 7 或 Linux 发行版才能查看彩色日志内容。）

验证获取身份验证令牌时是否出现问题：
- 每隔 5 分钟会记录一次消息“AKS 资源没有配置”。
- Pod 每隔 15 分钟重启一次以重试，同时出现错误：“AKS 资源没有配置”。
  - 如果是这样，请检查资源组中是否存在数据收集规则和数据收集终结点。
  - 此外，请验证 Azure Monitor 工作区是否存在。
  - 验证你是否没有专用 AKS 群集，并且它未链接到任何其他服务的 Azure Monitor 专用链接范围。目前不支持此方案。

配置处理

使用以下命令查看容器日志：

kubectl logs <ama-metrics-operator-targets pod name> -n kube-system -c config-reader

验证分析 Prometheus 配置、与启用的任何默认抓取目标合并以及验证完整配置时是否未发生任何错误。
如果你确实加入了自定义 Prometheus 配置，请验证它是否在日志中被识别。如果不同：
- 验证 configmap 的名称是否正确：ama-metrics-prometheus-config，所在命名空间为 kube-system。
- 验证在配置映射中，Prometheus 配置是否位于 data 下的 prometheus-config 部分下，如下所示：
```
kind: ConfigMap
apiVersion: v1
metadata:
  name: ama-metrics-prometheus-config
  namespace: kube-system
data:
  prometheus-config: |-
    scrape_configs:
    - job_name: <your scrape job here>
```
如果确实创建了自定义资源，则应已在创建 Pod/服务监视器期间看到任何验证错误。如果仍然看不到目标中的指标，请确保日志未显示任何错误。

kubectl logs <ama-metrics-operator-targets pod name> -n kube-system -c targetallocator

验证 MetricsExtension 中是否未发生有关对 Azure Monitor 工作区进行身份验证的错误。
验证 OpenTelemetry collector 中是否未发生有关抓取目标的错误。

运行以下命令：

kubectl logs <ama-metrics pod name> -n kube-system -c addon-token-adapter

如果对 Azure Monitor 工作区进行身份验证时出现问题，此命令会显示错误。下面是一个没有问题的日志示例：

如果日志中没有错误，则可以使用 Prometheus 接口进行调试，以验证是否正在抓取预期的配置和目标。

Prometheus 接口

每个 ama-metrics-* Pod 都有端口 9090 上提供的 Prometheus 代理模式用户界面。自定义配置和自定义资源目标由 ama-metrics-* Pod 抓取，节点目标则由 ama-metrics-node-* pod 抓取。端口转发到副本 Pod 或其中一个守护程序集 Pod，检查配置、服务发现和目标终结点，如此处所述，以验证自定义配置是否正确，是否已为每个作业发现预期目标，并且在抓取特定目标时没有错误。

运行命令 kubectl port-forward <ama-metrics pod> -n kube-system 9090。

打开浏览器并访问地址 127.0.0.1:9090/config。此用户界面具有完整的抓取配置。验证所有作业是否都包含在配置中。
转到 127.0.0.1:9090/service-discovery 以查看指定的服务发现对象发现的目标，以及 relabel_configs 筛选的目标。例如，如果某个 Pod 缺少指标，你可以查看该 Pod 是否被发现以及它的 URI 是什么。然后，可以在查看目标时使用此 URI 来确定是否发生任何抓取错误。
转到 127.0.0.1:9090/targets 以查看所有作业、上次抓取该作业的终结点的时间，以及任何错误

自定义资源

如果确实包含了自定义资源，请确保它们显示在配置、服务发现和目标下方。

配置

服务发现

目标

如果没有问题并且正在抓取预期的目标，则你可以通过启用调试模式来查看正在抓取的确切指标。

调试模式

警告

此模式可能会影响性能，应该出于调试目的短时间启用。

可以按照此处的说明，通过将 debug-mode 下的 configmap 设置 enabled 更改为 true，将指标加载项配置为以调试模式运行。

启用后，所有抓取的 Prometheus 指标将托管在端口 9091 上。运行以下命令：

kubectl port-forward <ama-metrics pod name> -n kube-system 9091

在浏览器中转到 127.0.0.1:9091/metrics，以查看 OpenTelemetry 收集器是否抓取了指标。每个 ama-metrics-* Pod 都可以访问此用户界面。如果未显示指标，原因可能是指标或标签名称长度或者标签数量有问题。此外，检查是否超出了本文中指定的 Prometheus 指标的引入配额。

指标名称、标签名称和标签值

指标抓取目前存在下表中所列的限制：

properties	限制
标签名称长度	小于或等于 511 个字符。如果作业中的任何时序超过此限制，整个抓取作业会失败，并且在引入之前会从该作业中删除指标。你可以看到该作业显示了 up=0，并且目标 Ux 显示 up=0 的原因。
标签值长度	小于或等于 1023 个字符。如果作业中的任何时序超过此限制，整个抓取会失败，并且在引入之前会从该作业中删除指标。你可以看到该作业显示了 up=0，并且目标 Ux 显示 up=0 的原因。
每个时序的标签数量	小于或等于 63。如果作业中的任何时序超过此限制，整个抓取作业会失败，并且在引入之前会从该作业中删除指标。你可以看到该作业显示了 up=0，并且目标 Ux 显示 up=0 的原因。
度量值名称长度	小于或等于 511 个字符。如果作业中的任何时序超过此限制，只会删除该特定时序。 MetricextensionConsoleDebugLog 将记录已删除的指标的跟踪。
大小写不同的标签名称	同一指标示例中大小写不同的两个标签被视为重复的标签处理，在引入时会被删除。例如，时序 `my_metric{ExampleLabel="label_value_0", examplelabel="label_value_1}` 会因重复的标签而被删除，因为 `ExampleLabel` 和 `examplelabel` 被视为相同的标签名称。

检查 Azure Monitor 工作区上的引入配额

如果发现缺少指标，可以先检查是否超出了你的 Azure Monitor 工作区的引入限制。在 Azure 门户中，可以检查任何 Azure Monitor 工作区的当前使用情况。可以在 Azure Monitor 工作区的 Metrics 菜单下查看当前使用指标。以下利用率指标可作为每个 Azure Monitor 工作区的标准指标。

活动时序 - 在过去 12 小时内最近引入工作区中的唯一时序数量
活动时序限制 - 可以主动引入工作区的唯一时序数量限制
活动时序利用率百分比 - 当前利用的活动时序百分比
每分钟引入的事件数 - 最近每分钟收到的事件（示例）数
每分钟引入的事件数限制 - 在事件受到限制之前每分钟可以引入的最大事件数
每分钟引入的事件利用率百分比 - 当前正在利用的指标引入率限制百分比

若要避免指标引入限制，可监视引入限制并对其设置警报。请参阅监视引入限制。

请参阅服务配额和限制，了解默认配额以及可以根据使用情况增加的内容。可以使用 Azure Monitor 工作区的 Support Request 菜单请求增加 Azure Monitor 工作区的配额。确保在支持请求中包含 Azure Monitor 工作区的 ID、内部 ID 和位置/区域，你可以在 Azure 门户 Azure Monitor 工作区的“属性”菜单中找到这些信息。

由于 Azure Policy 评估，创建 Azure Monitor 工作区失败

如果创建 Azure Monitor 工作区失败，并出现错误 [策略禁止使用资源“resource-name-xyz”]，则可能存在正在阻止创建资源的 Azure 策略。如果有策略为 Azure 资源或资源组强制实施命名约定，则需为创建 Azure Monitor 工作区的命名约定创建豁免。

创建 Azure Monitor 工作区时，“MA_azure-monitor-workspace-name_location_managed”形式的资源组中默认自动创建“azure-monitor-workspace-name”形式的数据收集规则和数据收集终结点。目前无法更改这些资源的名称，需要在 Azure Policy 上设置豁免，以免除上述资源免受策略评估。请参阅Azure Policy 豁免结构。

后续步骤

查看大规模收集指标时的注意事项。

通过