Telegraf Nebius Cloud Monitoring 输出插件配置、认证与数据格式全解析【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegrafNebius 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。配置参数详解参数类型默认值说明timeoutduration20s每次 HTTP 写入的超时时间。源码中的默认常量defaultRequestTimeout time.Second * 20见 nebius_cloud_monitoring.goendpointstringhttps://monitoring.api.il.nebius.cloud/monitoring/v2/data/writeNebius Cloud Monitoring 写入 API 地址正常情况下无需修改。默认值对应源码常量defaultEndpoint见 nebius_cloud_monitoring.go从源码的Init()方法nebius_cloud_monitoring.go可以确认当timeout未设置或小于等于 0 时使用默认的 20 秒当endpoint为空时回退到官方默认端点。同时Init()会构建带超时的http.Client其Transport显式使用ProxyFromEnvironment即会遵循环境变量中的 HTTP(S) 代理配置适用于需要代理出网的云环境。三、认证机制Compute 元数据服务免密钥认证插件目前只支持一种认证方式——基于 Nebius Cloud Compute 实例元数据的自动认证这也是该插件与大多数需要显式 AK/SK 的输出插件最大的差异点。当插件运行在 Nebius Compute 实例内部时它会自动从实例元数据服务中获取IAM Token用于 API 鉴权通过Authorization: Bearer token头携带Folder ID资源归属的项目 ID作为请求查询参数folderId携带。插件内部使用了 Google Cloud 的元数据命名规范Nebius 云内元数据端点兼容 GCE metadata 格式并硬编码了保留的链路本地 IP 作为元数据端点地址源码注释说明目前 Nebius 元数据端点尚无 DNS只能使用保留 IPdefaultMetadataTokenURL 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.goexport NEBIUS_SERVICEcustom四、指标上报的数据格式与命名规则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.gotype 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映射规则如下指标名拼接Telegraf 的一条指标measurement往往包含多个字段field插件会为每个字段生成一条独立的 Nebius 指标命名格式为measurement名_field名即源码中的m.Name() _ field.Key。例如测试用例中 Telegraf 指标cluster的字段cpu会变成 Nebius 指标cluster_cpu见 nebius_cloud_monitoring_test.go。数值转换字段值通过internal.ToFloat64统一转换为float64。该转换支持 float 与 int 系列数值类型测试用例验证了int64最大值与普通int的转换结果nebius_cloud_monitoring_test.go。若字段值无法转换为数值例如字符串、布尔值插件会记录错误日志并跳过该字段不会中断整批写入。标签传递Telegraf 指标的所有标签会原样复制到 Nebius 指标labels中但name例外见下一节。时间戳使用m.Time().Format(time.RFC3339)格式化为 RFC3339 字符串。批量发送所有转换后的指标放入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.goClose()仅释放 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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/telegrafNebius 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。配置参数详解参数类型默认值说明timeoutduration20s每次 HTTP 写入的超时时间。源码中的默认常量defaultRequestTimeout time.Second * 20见 nebius_cloud_monitoring.goendpointstringhttps://monitoring.api.il.nebius.cloud/monitoring/v2/data/writeNebius Cloud Monitoring 写入 API 地址正常情况下无需修改。默认值对应源码常量defaultEndpoint见 nebius_cloud_monitoring.go从源码的Init()方法nebius_cloud_monitoring.go可以确认当timeout未设置或小于等于 0 时使用默认的 20 秒当endpoint为空时回退到官方默认端点。同时Init()会构建带超时的http.Client其Transport显式使用ProxyFromEnvironment即会遵循环境变量中的 HTTP(S) 代理配置适用于需要代理出网的云环境。三、认证机制Compute 元数据服务免密钥认证插件目前只支持一种认证方式——基于 Nebius Cloud Compute 实例元数据的自动认证这也是该插件与大多数需要显式 AK/SK 的输出插件最大的差异点。当插件运行在 Nebius Compute 实例内部时它会自动从实例元数据服务中获取IAM Token用于 API 鉴权通过Authorization: Bearer token头携带Folder ID资源归属的项目 ID作为请求查询参数folderId携带。插件内部使用了 Google Cloud 的元数据命名规范Nebius 云内元数据端点兼容 GCE metadata 格式并硬编码了保留的链路本地 IP 作为元数据端点地址源码注释说明目前 Nebius 元数据端点尚无 DNS只能使用保留 IPdefaultMetadataTokenURL 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.goexport NEBIUS_SERVICEcustom四、指标上报的数据格式与命名规则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.gotype 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映射规则如下指标名拼接Telegraf 的一条指标measurement往往包含多个字段field插件会为每个字段生成一条独立的 Nebius 指标命名格式为measurement名_field名即源码中的m.Name() _ field.Key。例如测试用例中 Telegraf 指标cluster的字段cpu会变成 Nebius 指标cluster_cpu见 nebius_cloud_monitoring_test.go。数值转换字段值通过internal.ToFloat64统一转换为float64。该转换支持 float 与 int 系列数值类型测试用例验证了int64最大值与普通int的转换结果nebius_cloud_monitoring_test.go。若字段值无法转换为数值例如字符串、布尔值插件会记录错误日志并跳过该字段不会中断整批写入。标签传递Telegraf 指标的所有标签会原样复制到 Nebius 指标labels中但name例外见下一节。时间戳使用m.Time().Format(time.RFC3339)格式化为 RFC3339 字符串。批量发送所有转换后的指标放入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.goClose()仅释放 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考