Nightingale 集成指南：使用 Categraf GCP 指标采集插件监控 Google Cloud
【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale
导读
本文围绕 integrations/GoogleCloud 目录下的 GCP 指标采集插件（GCP Metrics Collection Plugin）展开，说明如何通过 Categraf 采集 Google Cloud（GCP）平台上的监控指标，并将其汇入 Nightingale 进行存储、告警与可视化。读完本文，你将掌握该插件的权限配置、认证方式、全部配置参数的含义与取值范围，以及如何针对 GCE 实例等资源做精细化过滤采集。
一、插件定位：GCP 监控指标如何进入 Nightingale
Nightingale 本身不负责监控数据的采集，项目官方推荐使用 Categraf）：Categraf 采集操作系统、网络设备、中间件、数据库以及各类云平台（如 GCP）的监控数据，再通过Prometheus Remote Write协议推送到 Nightingale，由 Nightingale 完成时序存储（如 Prometheus、VictoriaMetrics 等）与告警可视化。
本项目根目录下的integrations/目录即存放了大量采集插件的示例配置、告警规则与仪表盘模板，其中 GoogleCloud 就是面向 Google Cloud 的采集插件包：
- collect/googlecloud/gcp.toml：GCP 采集插件的 TOML 配置模板；
- markdown/README.en_US.md 与 markdown/README.md：插件的英文/中文使用说明（本文即基于英文文档展开）。
该插件通过 Google Cloud Monitoring API 拉取指标，因此需要给服务账号授予只读监控权限，并配置项目 ID 与凭据。
二、所需权限：只读访问 Google Cloud Monitoring
使用该插件前，需要为服务账号（Service Account）授予以下 OAuth Scope：
https://www.googleapis.com/auth/monitoring.read这是 Google Cloud Monitoring 的只读权限范围，仅允许读取监控数据（时间序列、告警策略等），无法修改任何资源，符合最小权限原则。实际使用中，你需要在 Google Cloud Console 中：
- 创建或选择一个服务账号；
- 为该账号授予包含
monitoring.read权限范围的凭据（如 JSON 格式的 service account key）； - 将 key 文件下载到采集器所在机器上，供插件读取。
提示：更精细的做法是仅对目标项目（project）授予该权限，避免凭据具备跨项目读取能力。
三、配置文件与核心参数详解
插件的完整配置模板见 collect/googlecloud/gcp.toml。其整体结构沿用 Categraf 插件的通用形态：顶层interval定义采集周期，[[instances]]数组内定义每个采集实例的具体参数。以下逐项解析英文文档 README.en_US.md 中的配置：
# collect interval, recommended to be >= 1 minute interval=60 [[instances]] # set the project_id project_id="your-project-id" # set the credentials key file credentials_file="/path/to/your/key.json" # or set the credentials JSON directly credentials_json="xxx"| 参数 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|
interval | 是 | 60 | 采集周期（秒），建议不小于 1 分钟（60s），因为 Cloud Monitoring 的指标最小粒度通常为 60 秒 |
project_id | 是 | 无 | GCP 项目 ID，即 metrics 归属的项目 |
credentials_file | 二选一 | 无 | 服务账号 key 文件的路径，例如/path/to/your/key.json |
credentials_json | 二选一 | 无 | 直接以字符串形式内嵌凭据 JSON（当不便引用文件时使用） |
credentials_file与credentials_json只需配置其一：前者适合在服务器上用文件管理凭据，后者适合把凭据直接写入配置文件、随配置分发。
3.1 时间窗口：delay 与 period
指标拉取并非取"当前时刻"，而是基于一个延迟窗口，以应对 GCP 监控数据落盘的延迟：
# metric end time = now - delay #delay="2m" # metric start time = now - deley - period #period="1m"delay：指标结束时间= 当前时间 − delay。即允许数据延迟多久后再拉取，默认建议2m（2 分钟）。如果拉得太"新"，GCP 侧数据尚未写入，容易取到空值；period：指标起始时间= 当前时间 − delay − period，即一次拉取覆盖的时间跨度，默认建议1m（1 分钟）。注意文档原文中该行注释为deley（拼写笔误），实际含义即 delay。
两者共同决定了每次请求的时间区间[now - delay - period, now - delay]，可视为与 CloudWatch 插件中delay/period参数（见 integrations/CloudWatch/collect/cloudwatch/cloud.toml）对齐的同类设计：delay必须能覆盖指标在云侧的可查延迟，period则通常是采集周期的整数倍。
3.2 指标过滤器 filter
#filter="metric.type=\"compute.googleapis.com/instance/cpu/utilization\" AND resource.labels.zone=\"asia-northeast1-a\""filter使用 Google Cloud Monitoring 的过滤表达式语法，可以按metric.type（指标类型）与resource.labels（资源标签）筛选要采集的指标。示例含义为：只采集asia-northeast1-a可用区中 GCE 实例的 CPU 利用率指标。合理设置 filter 可以显著减少 API 请求量与数据处理量。
3.3 请求控制：timeout 与 request_inflight
# request timeout #timeout="5s" # cache TTL for the metric list; only takes effect when filter is empty #cache_ttl="1h" # give the GCE instance_name an alias and put it into a label #gce_host_tag="xxx" # maximum number of concurrent requests in flight #request_inflight=30 # request_inflight valid range is (0,100] # set a larger value only if you know what you are doing force_request_inflight= 200timeout：单次 HTTP 请求超时时间，示例为5s；cache_ttl：指标列表（metric list）的缓存时长。仅当 filter 为空时生效，即插件在未指定 filter 时需要先枚举全部指标，用缓存避免每次采集都重复拉取指标清单；gce_host_tag：给 GCE 实例的instance_name取一个别名并放入 label 中，便于在 Nightingale 侧按主机维度关联与筛选；request_inflight：并发在途请求数上限，合法取值范围为(0, 100]；force_request_inflight：强制并发数设置。文档特别注明：request_inflight的合法范围是(0,100]，而示例force_request_inflight= 200超出了该范围——这类"强制"参数只有在你清楚自己在做什么（例如已确认 GCP 配额允许更高并发）时才建议使用，否则可能触发 GCP API 限流。
四、一个可落地的完整配置示例
将上述参数组合，得到一份针对单项目的可用配置（可直接写入 Categraf 的采集配置目录）：
# 采集周期：GCP 指标最小粒度为 1 分钟，建议不低于 60s interval=60 [[instances]] project_id="your-project-id" credentials_file="/etc/categraf/gcp-key.json" # 数据延迟与时间窗 delay="2m" period="1m" # 按需过滤：只采 GCE 实例 CPU 利用率 filter="metric.type=\"compute.googleapis.com/instance/cpu/utilization\"" # 请求控制 timeout="5s" cache_ttl="1h" request_inflight=30 # 主机别名标签（可选） gce_host_tag="gce_instance"配置完成后，启动/重载 Categraf，插件会按interval周期通过 Cloud Monitoring API 拉取指标，转换为 Prometheus 格式的时序数据后由 Categraf 经 Remote Write 推送到 Nightingale。后续即可在 Nightingale 中针对这些指标创建告警规则与仪表盘（integrations/目录内的各组件包通常还附带 alerts 规则与 dashboards 模板，可参考同类云平台插件，如 CloudWatch）。
五、使用建议与注意事项
- 采集周期下限：GCP 指标的最小数据粒度是 60 秒，
interval建议保持>= 60，否则可能出现空轮询，浪费 API 配额； - 凭据安全：
credentials_file指向的 key 文件务必设置合理的文件权限；若使用credentials_json内嵌凭据，需注意配置文件本身的访问控制； - 并发与配额：
request_inflight默认上限 100，贸然使用force_request_inflight放大并发可能触发 Google Cloud Monitoring API 的速率限制（rate limit），仅在确认配额充足时使用； - 善用 filter：能明确
metric.type与resource.labels时，优先配置 filter 缩小采集范围，既可降低 API 调用量，也能减少 Nightingale 侧的存储压力； - 延迟窗口：如果发现指标经常缺失或为空，优先检查
delay是否覆盖了数据落盘延迟，可适当调大（如 3m~5m）。
六、小结
GCP 指标采集插件以极简的 TOML 配置即可完成 Google Cloud 监控数据的接入：通过monitoring.read只读权限 + 服务账号凭据，配合project_id与时间窗、过滤器、并发控制等参数，即可将 GCE 等 GCP 资源的指标稳定地采集进 Nightingale 体系。本文涉及的配置模板与说明文档均位于 integrations/GoogleCloud，可直接在仓库中查阅、复制并落地使用。
【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
