# Telegraf 对接

使用 Telegraf HTTP 输出与 Prometheus Remote Write 把指标写入夜莺，并核验认证、存储和实际数据。

最后校对于 2026-10-11

这页办完，你会把已有 Telegraf 的指标写进夜莺使用的时序库，不需要更换采集器。 示例使用 **Telegraf 1.36.3、夜莺 v9**；Telegraf 负责采集，夜莺接收后写入内置时序库或配置的外置存储。

## 用 Telegraf 还是 Categraf？[​](#telegraf-vs-categraf "用 Telegraf 还是 Categraf？的直接链接")

两者都是 Go 写的 MIT 协议采集器，夜莺都能接收。实际使用中要看的差别：

|                  | Telegraf                                                                | Categraf                                                                                                       |
| ---------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| 插件             | 300+ 输入插件，另有处理器和大量输出插件                                 | 90+ 输入插件，覆盖操作系统、数据库、中间件、网络设备和 Kubernetes                                              |
| 怎么写入夜莺     | `outputs.http` 加 `data_format = "prometheusremotewrite"`（配置见下文） | 默认就是 Prometheus Remote Write                                                                               |
| 夜莺的主机列表   | 不发送夜莺的心跳                                                        | 每 10 秒发送一次带主机元数据的[心跳](https://n9e.io/zh/docs/data/categraf/targets.md)，填充「基础设施 → 主机」 |
| 内置仪表盘和规则 | 少数模板带 Telegraf 规则组（例如 Linux）                                | 很多[集成模板](https://n9e.io/zh/integrations.md)带有 Categraf 规则组和 Categraf 仪表盘                        |
| 指标名           | Telegraf 插件的命名，例如 `cpu_usage_active`                            | 部分主机插件与 Telegraf 同名，有些规则两边通用                                                                 |

**继续用 Telegraf**：已经部署好，或依赖 Categraf 没有的插件。夜莺的告警功能不要求换采集器。**选 Categraf**：新主机想直接用上主机列表，以及内置的仪表盘和[告警规则](https://n9e.io/zh/alert-rules.md)，不必改写指标名。迁移期间两者可以并存。

## 开始之前[​](#before-you-start "开始之前的直接链接")

* 夜莺已启动，Telegraf 所在机器能访问 `http://<夜莺地址>:17000`。
* `[HTTP.APIForAgent]` 的 `Enable` 为 `true`。
* 已确认使用[内置时序库](https://n9e.io/zh/docs/install/embedded-tsdb.md)，或正确配置了[外置写入目标](https://n9e.io/zh/docs/install/external-tsdb.md)。

用现有 Telegraf 安装即可。新安装参考 [Telegraf 官方安装说明](https://docs.influxdata.com/telegraf/v1/install/)，不要继续使用旧文里的 1.20.4 下载脚本。

## 配置输出[​](#configure-output "配置输出的直接链接")

把下面内容合入 `telegraf.conf`，替换地址。`outputs.http` 是输出插件，`prometheusremotewrite` 是序列化格式。

```
[agent]

interval = "15s"

flush_interval = "15s"



[[outputs.http]]

url = "http://127.0.0.1:17000/prometheus/v1/write"

method = "POST"

data_format = "prometheusremotewrite"

[outputs.http.headers]

Content-Type = "application/x-protobuf"

Content-Encoding = "snappy"

X-Prometheus-Remote-Write-Version = "0.1.0"



[[inputs.cpu]]

percpu = false

totalcpu = true

collect_cpu_time = false

report_active = true



[[inputs.mem]]
```

如夜莺配置了 `[HTTP.APIForAgent.BasicAuth]`，在 `[outputs.http.headers]` **之前**的 `[[outputs.http]]` 中增加 `username`、`password`，与服务端一致。未开启认证时无需填写。

已有配置里如果仍启用了默认 InfluxDB 输出，确认是否需要它，避免额外输出失败混淆排查。 旧 OpenTSDB 接口仍属于兼容协议，字段和指标命名与 Remote Write 不同，迁移时要核对原有仪表盘。

## 验证采集和写入[​](#verify "验证采集和写入的直接链接")

```
telegraf --config /etc/telegraf/telegraf.conf --test

telegraf --config /etc/telegraf/telegraf.conf --once
```

**预期结果**：`--test` 显示 CPU、内存采集结果；`--once` 完成一次采集和输出，没有 401、404 或连接失败。`--test` 本身不验证向夜莺写入。

在夜莺即时查询里选择实际接收数据的时序库，查询 `cpu_usage_active`；应出现带 Telegraf 标签的数据。 确认后，按现有服务方式重启 Telegraf。安装了官方 systemd 单元的机器可以执行 `sudo systemctl restart telegraf`。

Telegraf 不会上报 Categraf 的 heartbeat 元信息；看到时序数据，不等于具备同样的对象注册和自愈能力。 Histogram / Summary 的批量序列化还有边界，见 [1.36.3 格式说明](https://github.com/influxdata/telegraf/blob/v1.36.3/plugins/serializers/prometheusremotewrite/README.md)。

## 下一步[​](#next "下一步的直接链接")

* [数据写入协议](https://n9e.io/zh/docs/reference/write-protocols.md)
* [创建第一条告警](https://n9e.io/zh/docs/alerting/first-rule.md)