Telegraf Nebius Cloud Monitoring 输出插件：配置、认证与数据格式全解析

Telegraf Nebius Cloud Monitoring 输出插件：配置、认证与数据格式全解析

【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf

Nebius Cloud Monitoring 是 Nebius Cloud 平台提供的托管监控服务，允许用户将自定义指标写入云端并统一观测。Telegraf 从 v1.27.0 起内置了outputs.nebius_cloud_monitoring插件，专门用于把采集到的指标批量发送到 Nebius 监控后端。本文以该插件的官方文档为骨架，结合仓库内 核心实现、单元测试 与 示例配置，完整讲解如何配置、如何在 Compute 实例内完成免密钥认证、指标数据在线上如何组织，以及name标签为何必须被改名为_name。读完本文，你将能够在 Nebius 云环境中把 Telegraf 的任意指标无缝送入 Nebius Cloud Monitoring。

一、插件能力与适用场景

该插件是一个标准的 Telegraf Output（输出）插件，把 Telegraf 采集、处理后得到的指标批量 POST 到 Nebius Cloud Monitoring 的写入 API。它的典型应用场景包括：

• 运行在 Nebius Cloud Compute 虚拟机中的服务，需要把系统指标（如 CPU、内存、磁盘、systemd 单元状态）上报到云端监控面板；
• 需要把 Telegraf 聚合（aggregate）后的指标同步到 Nebius 监控服务，实现统一的云上告警与可视化；
• 在无需管理静态密钥的前提下，利用实例元数据服务自动获取 IAM 凭证，实现开箱即用的免密钥上报。

插件通过 plugins/outputs/registry.go 中定义的outputs.Add注册机制挂载，注册名为nebius_cloud_monitoring（见 nebius_cloud_monitoring.go）。若使用自定义构建，需要在构建标签中加入outputs或outputs.nebius_cloud_monitoring（见 plugins/outputs/all/nebius_cloud_monitoring.go）。

二、快速配置

插件的 示例配置 非常精简，全文如下：

# Send aggregated metrics to Nebius.Cloud Monitoring [[outputs.nebius_cloud_monitoring]] ## Timeout for HTTP writes. # timeout = "20s" ## Nebius.Cloud monitoring API endpoint. Normally should not be changed # endpoint = "https://monitoring.api.il.nebius.cloud/monitoring/v2/data/write"

与所有 Telegraf 插件一样，该输出还支持一系列全局配置选项（如namepass、namedrop、tagpass、tagexclude、别名alias以及处理器排序等），用于对指标进行过滤、改写和组织，详见 docs/CONFIGURATION.md，其通用说明位于 docs/includes/plugin_config.md。

配置参数详解

从源码的Init()方法（nebius_cloud_monitoring.go）可以确认：当timeout未设置或小于等于 0 时使用默认的 20 秒；当endpoint为空时回退到官方默认端点。同时Init()会构建带超时的http.Client，其Transport显式使用ProxyFromEnvironment，即会遵循环境变量中的 HTTP(S) 代理配置，适用于需要代理出网的云环境。

三、认证机制：Compute 元数据服务免密钥认证

插件目前只支持一种认证方式——基于 Nebius Cloud Compute 实例元数据的自动认证，这也是该插件与大多数需要显式 AK/SK 的输出插件最大的差异点。

当插件运行在 Nebius Compute 实例内部时，它会自动从实例元数据服务中获取：

1. IAM Token（用于 API 鉴权，通过Authorization: Bearer <token>头携带）；
2. Folder ID（资源归属的项目 ID，作为请求查询参数folderId携带）。

插件内部使用了 Google Cloud 的元数据命名规范（Nebius 云内元数据端点兼容 GCE metadata 格式），并硬编码了保留的链路本地 IP 作为元数据端点地址（源码注释说明目前 Nebius 元数据端点尚无 DNS，只能使用保留 IP）：

defaultMetadataTokenURL = "http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token" defaultMetadataFolderURL = "http://169.254.169.254/computeMetadata/v1/instance/vendor/folder-id"

（见 nebius_cloud_monitoring.go）

请求元数据时，插件会在 HTTP 请求头中设置Metadata-Flavor: Google（见getResponseFromMetadata函数，nebius_cloud_monitoring.go），并校验响应状态码必须在 2xx 范围内，否则返回错误。

整个认证流程分两条链路：

• 连接阶段（Connect()）：插件启动时先从元数据服务拉取 Folder ID 并缓存在内存中，同时打印目标写入 URL 与 Folder ID 的日志（nebius_cloud_monitoring.go）。这与 Telegraf 定义的Output接口生命周期一致：Connect()在插件启动时仅调用一次（接口定义见 output.go）。
• 写入阶段（send()）：每次发送数据前检查已缓存的 IAM Token 是否过期（iamTokenExpirationTime.Before(time.Now())），过期或为空时重新从元数据服务获取新 Token，并依据返回的expires_in秒数计算下次刷新时间（nebius_cloud_monitoring.go）。

需要特别强调的是：这套认证流程只对云内虚拟机生效，元数据端点仅在 Nebius Cloud 的 VM 网络内可达。在本地开发环境或非 Nebius 云主机上直接运行该插件会因无法访问169.254.169.254而报错，这是该插件的使用前提与限制。

服务名（service）参数

在写入请求中，插件还会携带一个查询参数service，其默认值为custom，但可以通过环境变量NEBIUS_SERVICE覆盖（见 nebius_cloud_monitoring.go）：

export NEBIUS_SERVICE=custom

四、指标上报的数据格式与命名规则

Nebius Monitoring 后端使用 JSON 格式接收指标。单条指标的基本结构如下（来自文档原示例）：

{ "name": "metric_name", "labels": { "key": "value", "foo": "bar" }, "ts": "2023-06-06T11:10:50Z", "value": 0 }

字段语义：

• name：指标名，服务端将其作为时序指标的唯一标识；
• labels：标签集合（键值对），用于区分同一指标的不同维度；
• ts：时间戳，RFC3339 格式；
• value：数值。

从源码可以看到，实际请求体是一个包含metrics数组的批量消息（nebius_cloud_monitoring.go）：

type nebiusCloudMonitoringMessage struct { TS string `json:"ts,omitempty"` Labels map[string]string `json:"labels,omitempty"` Metrics []nebiusCloudMonitoringMetric `json:"metrics"` }

单条指标还支持可选字段type（注释标注取值DGAUGE | IGAUGE | COUNTER | RATE，默认DGAUGE），插件当前未显式设置该字段。

Telegraf 指标到 Nebius JSON 的映射规则

在Write()方法中（nebius_cloud_monitoring.go），映射规则如下：

1. 指标名拼接：Telegraf 的一条指标（measurement）往往包含多个字段（field），插件会为每个字段生成一条独立的 Nebius 指标，命名格式为measurement名_field名，即源码中的m.Name() + "_" + field.Key。例如测试用例中 Telegraf 指标cluster的字段cpu会变成 Nebius 指标cluster_cpu（见 nebius_cloud_monitoring_test.go）。
2. 数值转换：字段值通过internal.ToFloat64统一转换为float64。该转换支持 float 与 int 系列数值类型，测试用例验证了int64最大值与普通int的转换结果（nebius_cloud_monitoring_test.go）。若字段值无法转换为数值（例如字符串、布尔值），插件会记录错误日志并跳过该字段，不会中断整批写入。
3. 标签传递：Telegraf 指标的所有标签会原样复制到 Nebius 指标labels中（但name例外，见下一节）。
4. 时间戳：使用m.Time().Format(time.RFC3339)格式化为 RFC3339 字符串。
5. 批量发送：所有转换后的指标放入metrics数组，序列化为 JSON 后追加一个换行符，再通过 HTTP POST 一次性发送。

五、保留标签：name必须改名为_name

这是本插件使用中最容易踩坑的规则。由于 Nebius 监控后端用 JSON 字段name承载指标名，标签（labels）的键不能使用name，否则会与指标名冲突。

插件内部通过replaceReservedTagNames函数（nebius_cloud_monitoring.go）自动处理：凡是名为name的标签，一律改写为_name，其余标签保持不变。

以下面的原始 payload 为例（来自文档原示例），其标签中包含"name": "accounts-daemon.service"：

{ "name": "systemd_units_load_code", "labels": { "active": "active", "host": "vm", "load": "loaded", "name": "accounts-daemon.service", "sub": "running" }, "ts": "2023-06-06T11:10:50Z", "value": 0 }

发送到后端时会自动被改写为：

{ "name": "systemd_units_load_code", "labels": { "active": "active", "host": "vm", "load": "loaded", "_name": "accounts-daemon.service", "sub": "running" }, "ts": "2023-06-06T11:10:50Z", "value": 0 }

单元测试 TestReplaceReservedTagNames 与TestWrite中的 "label with name 'name' is replaced with '_name'" 用例（nebius_cloud_monitoring_test.go）都验证了这一行为。因此，若你的采集指标中带有name标签（例如 systemd 单元名、进程名等），无需在 Telegraf 侧手动改名，插件会自动完成兼容处理。

六、源码级剖析：一次完整的写入流程

综合上述内容，一次完整的指标上报经历了以下调用链：

Write(metrics) ├─ 遍历每条 metric 的每个 field │ ├─ internal.ToFloat64 数值化（失败则跳过并记录日志） │ ├─ 指标名拼接 m.Name() + "_" + field.Key │ ├─ replaceReservedTagNames 处理 name 标签 │ ├─ 时间戳格式化为 RFC3339 │ └─ 生成 nebiusCloudMonitoringMetric ├─ json.Marshal 序列化，追加换行 └─ send(body) ├─ 检查/刷新 IAM Token（从元数据服务获取，带过期时间缓存） ├─ 构造 POST 请求，查询参数携带 folderId 与 service ├─ 设置 Content-Type: application/json 与 Authorization: Bearer <token> ├─ 发送请求，校验 2xx 响应 └─ 非 2xx 时返回 "failed to write batch" 错误

该流程严格遵循 Telegraf 输出插件的Output接口契约（Connect/Close/Write，见 output.go），Close()仅释放 HTTP 客户端。此外，插件在Init()阶段通过selfstat注册了metric_outside_window计数器（nebius_cloud_monitoring.go），该统计量可供内部自监控使用，从命名看用于记录落入监控窗口之外的指标数量（当前实现尚未赋值，从代码结构可以推断其预留了该观测能力）。

从测试实现看（nebius_cloud_monitoring_test.go），测试通过httptest起了一个模拟元数据服务器（/token与/folder两个路径分别返回 IAM Token JSON 和 folder id），再用另一个httptest服务器模拟写入端点，完整走通了Init → Connect → Write的真实调用链，这为本地验证插件行为提供了可参考的测试范式。

七、使用注意事项与故障排查

• 运行环境限制：插件只支持 Nebius Compute 云内 VM 上的元数据认证，非云环境或云外主机无法使用；默认元数据地址169.254.169.254为链路本地保留 IP，仅云内可达。
• 代理与网络：HTTP 客户端遵循环境代理配置（ProxyFromEnvironment），云内网络若需经代理出网，请提前配置HTTP_PROXY/HTTPS_PROXY环境变量。
• 非数值字段：字符串、布尔等非数值字段会被跳过并在日志中记录，请确保监控的字段为数值类型，或配合处理器（processor）完成类型转换。
• 标签冲突：采集指标中若存在name标签，最终会以_name上报，查询监控数据时需使用改名后的标签名。
• IAM Token 刷新：Token 依据元数据返回的expires_in自动续期，无需人工干预；若频繁出现 401，请检查实例服务账号权限与所在 Folder。
• Endpoint 覆盖：endpoint与timeout均可通过配置覆盖默认值，用于对接代理网关或调整超时策略。

八、总结

outputs.nebius_cloud_monitoring是 Telegraf 面向 Nebius 云的官方输出插件，核心价值在于三点：极简的两参数配置、基于 Compute 元数据服务的免密钥自动认证，以及自动的name → _name标签兼容处理。它把 Telegraf 的任意数值指标以measurement_field命名规范映射到 Nebius 监控的 JSON 写入协议，配合 IAM Token 的过期自动刷新，能够在云内虚拟机场景下实现"即配即用"的指标上报。相关文件路径：插件实现 plugins/outputs/nebius_cloud_monitoring/nebius_cloud_monitoring.go、示例配置 plugins/outputs/nebius_cloud_monitoring/sample.conf、单元测试 plugins/outputs/nebius_cloud_monitoring/nebius_cloud_monitoring_test.go，通用插件配置说明见 docs/CONFIGURATION.md。

【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf