可观测性APM链路追踪指标监控日志分析微服务【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址https://gitcode.com/gh_mirrors/sk/skywalking点击查看免费下载本指南围绕 SkyWalking OAP 的receiver-telegraf模块展开讲解如何让 OAP 通过 HTTP 接收 InfluxDB Telegraf 采集的 CPU、内存、磁盘、网络等虚拟机指标并经 MALMetric Analysis Language规则转换成 SkyWalking 的 meter 指标体系。读完本文你将掌握 Telegraf 端outputs.http JSON 格式的配置方法、OAP 端receiver-telegraf模块的激活方式、telegraf-rules规则文件的编写与扩展以及数据从 Telegraf 流入 OAP 的完整底层处理链路。一、Telegraf Receiver 是什么Telegraf Receiver 是 SkyWalking OAP 的一个指标接收模块模块名receiver-telegraf源码位于 skywalking-telegraf-receiver-plugin它借助 OAP 的meter-system度量系统接收并解析 InfluxDB Telegraf 上报的指标数据使 SkyWalking 的监控平台能够直接消费 Telegraf 生态采集的各类系统指标。其数据链路为Telegraf inputs plugins -- Telegraf Receiver -- SkyWalking OAP Server即Telegraf 的输入插件input plugins负责采集指标通过 HTTP 输出插件推送给 OAP 的 Telegraf ReceiverReceiver 将数据转换为 meter 采样Sample再经由 MAL 规则文件完成指标定义、聚合与落地存储。OAP 在**启动阶段bootstrap**即加载规则配置规则文件位于$CLASSPATH/telegraf-rules目录下。需要注意如果新配置格式不合法not well-formedOAP 可能无法正常启动——这一点与 Prometheus fetcher 等其他接收器的行为一致修改规则文件后应先在本地校验格式。二、Telegraf 端配置三大约束原文档明确列出了使用 Telegraf Receiver 的三个前提条件三者缺一不可1. 输出方式必须使用 HTTPTelegraf Receiver 模块通过HTTP接收 Telegraf 的指标因此在telegraf.conf中必须将输出插件设置为[[outputs.http]]即采用 Telegraf 的 HTTP output 插件将采集到的指标 POST 到 OAP。2. 数据格式必须为 JSONTelegraf Receiver 模块只处理 Telegraf 的JSON指标格式因此需要显式声明数据格式data_format json3. 时间戳单位必须为秒secondTelegraf 的 JSON 输出中默认的json_timestamp_units单位为秒second而 Telegraf Receiver只处理秒级时间戳。如果你在telegraf.conf中显式配置了时间戳单位那么以下写法是可行的json_timestamp_units 1s从源码角度看秒级时间戳在 OAP 内部会被换算为毫秒参与 meter 计算见下文底层处理原理因此 1 秒以外的其他时间戳单位如1ms、1us、1ns不被该接收器支持。综上一个最小可用的telegraf.conf输出段大致如下[[outputs.http]] url http://oap-host:12800/telegraf data_format json json_timestamp_units 1s其中/telegraf是 OAP 侧暴露的 HTTP 端点由共享 HTTP 服务端口承载默认 12800具体路径见下文源码分析。三、OAP 端激活配置Telegraf Receiver 在 OAP 的application.yml中默认配置如下参见 application.ymlreceiver-telegraf: selector: ${SW_RECEIVER_TELEGRAF:default} default: activeFiles: ${SW_RECEIVER_TELEGRAF_ACTIVE_FILES:vm}各配置项含义配置项环境变量默认值说明selectorSW_RECEIVER_TELEGRAFdefault模块选择器决定使用哪个 providerdefault即 TelegrafReceiverProviderdefault.activeFilesSW_RECEIVER_TELEGRAF_ACTIVE_FILESvm激活的规则文件名不含.yaml后缀多个文件用英文逗号,分隔激活方式由于默认值即为default/vmOAP 启动后该模块默认即处于激活状态若要停用可将SW_RECEIVER_TELEGRAF置为空或其它值若要激活其他规则文件例如自建的custom.yaml通过系统环境变量设置export SW_RECEIVER_TELEGRAF_ACTIVE_FILESvm,customactiveFiles的解析逻辑在 TelegrafReceiverProvider.java 中实现使用Splitter.on(,)按逗号拆分再调用Rules.loadRules(telegraf-rules, activeFiles)从 classpath 的telegraf-rules目录加载对应 YAML 规则文件目录常量定义于 TelegrafModuleConfig.javaCONFIG_PATH telegraf-rules。加载失败如文件缺失、YAML 非法会抛出ModuleStartException这正是配置不合法会导致 OAP 启动失败的源码根源。另外值得注意的是该 Provider 在start()阶段而非prepare()阶段加载规则并且在requiredModules()中声明了CoreModule、SharingServerModule、StorageModule这是为了配合 runtime-rule动态规则机制——静态 MAL 规则加载时可通过存储模块读取已被覆盖的动态规则缓存见 TelegrafReceiverProvider.java 中的注释说明。四、默认规则文件vm.yaml详解当前仓库自带的默认规则文件是telegraf-rules/vm.yaml负责处理虚拟机VM指标也是文档规则表中唯一列出的内置规则规则名说明配置文件数据来源vm虚拟机指标telegraf-rules/vm.yamlTelegraf inputs plugins → Telegraf Receiver → SkyWalking OAP Server规则文件位于 oap-server/server-starter/src/main/resources/telegraf-rules/vm.yaml其内容由 MALMetric Analysis Language编写MAL 的完整语法规范见 MAL 文档。核心结构如下expSuffix: service([host], Layer.OS_LINUX) metricPrefix: meter_vm metricsRules: # cpu - name: cpu_total_percentage exp: cpu_usage_active.tagEqual(cpu, cpu-total) - name: cpu_average_used exp: cpu_usage_active.tagNotEqual(cpu, cpu-total).avg([host, cpu]) - name: cpu_load1 exp: system_load1 - name: cpu_load5 exp: system_load5 - name: cpu_load15 exp: system_load15 # memory - name: memory_total exp: mem_total - name: memory_available exp: mem_available - name: memory_used exp: mem_used # swap - name: memory_swap_free exp: mem_swap_free - name: memory_swap_total exp: mem_swap_total - name: memory_swap_percentage exp: 100 - ((mem_swap_free / mem_swap_total) * 100) # node filesystem - name: filesystem_percentage exp: disk_used_percent.avg([host, device]) # node disk - name: disk_read exp: diskio_read_bytes.rate(PT1M) - name: disk_written exp: diskio_write_bytes.rate(PT1M) # node net - name: network_receive exp: net_bytes_recv.irate() - name: network_transmit exp: net_bytes_sent.irate() # node netstat - name: tcp_curr_estab exp: netstat_tcp_established - name: tcp_tw exp: netstat_tcp_time_wait - name: tcp_alloc exp: netstat_tcp_listen - name: udp_inuse exp: netstat_udp_socket对这份规则文件的要点解读expSuffix为所有规则追加后缀表达式。此处service([host], Layer.OS_LINUX)表示取 Telegraf 数据中的host标签作为 SkyWalking 服务Service名称并归属到OS_LINUX这一层Layer从而将每台被采集的机器建模为一个 OS_LINUX 服务。metricPrefix: meter_vm生成的 SkyWalking 指标统一以meter_vm_为前缀例如meter_vm_cpu_total_percentage、meter_vm_memory_total。指标表达式来源表达式左侧如cpu_usage_active、system_load1、mem_total、diskio_read_bytes、net_bytes_recv、netstat_tcp_established等对应的是 Telegraf CPU / Mem / Disk / Net / Netstat / System 等输入插件输出的字段名其命名格式为插件指标名_字段名这一映射由下文底层处理原理中的 Sample 转换逻辑决定。聚合算子avg按标签求平均、rate(PT1M)1 分钟速率、irate()瞬时速率、tagEqual/tagNotEqual标签过滤等均为 MAL 内置 DSL 算子。指标语义速查生成的 SkyWalking 指标含义对应 Telegraf 输入meter_vm_cpu_total_percentageCPU 总使用百分比仅cpucpu-totalCPU 插件meter_vm_cpu_average_used各 CPU 核平均使用率排除 cpu-totalCPU 插件meter_vm_cpu_load1/5/151/5/15 分钟系统负载System 插件meter_vm_memory_total/available/used内存总量/可用/已用Mem 插件meter_vm_memory_swap_free/total/percentageSwap 空闲/总量/使用百分比Mem 插件meter_vm_filesystem_percentage文件系统使用百分比Disk 插件meter_vm_disk_read/written磁盘读/写速率PT1MDiskIO 插件meter_vm_network_receive/transmit网络接收/发送瞬时速率Net 插件meter_vm_tcp_curr_estab/tcp_tw/tcp_alloc/udp_inuseTCP 连接数、TIME_WAIT、监听数、UDP Socket 数Netstat 插件五、底层处理原理源码级为了让读者真正理解为什么 Telegraf 的指标能变成 SkyWalking 的 meter 指标这里梳理 Telegraf Receiver 的完整处理链路。该模块的类结构如下TelegrafReceiverModule.java模块定义模块名为receiver-telegrafTelegrafReceiverProvider.java模块 Provider负责加载规则、注册 HTTP 端点TelegrafServiceHandler.java核心处理 Handler定义/telegraf端点与数据转换逻辑TelegrafData.java / TelegrafDatum.java请求体的 JSON POJO 模型。1. HTTP 端点注册在start()阶段Provider 通过SharingServerModule共享 HTTP 服务默认端口 12800提供的HTTPHandlerRegister将TelegrafServiceHandler注册为POST方法处理器httpHandlerRegister.addHandler( new TelegrafServiceHandler(getManager(), meterSystem, configs), Collections.singletonList(HttpMethod.POST));对应端点注解为Post(/telegraf)即 OAP 共享 HTTP 端口上的POST /telegraf参见 TelegrafServiceHandler.java。这解释了 Telegraf 端outputs.http的 URL 应指向http://oap-host:共享HTTP端口/telegraf。2. JSON 请求解析TelegrafData本身实现了 Armeria 的RequestConverterFunction将请求体 JSON 反序列化为TelegrafData对象MAPPER.readValue(request.contentUtf8(), TelegrafData.class)。其结构为TelegrafData包含一个ListTelegrafDatum metrics字段TelegrafDatum包含四个字段——name指标名如cpu、mem、tags标签 Map如host、cpu、fields字段值 Map如usage_active、total、used、timestamp秒级时间戳。JsonIgnoreProperties(ignoreUnknown true)表示忽略未知字段兼容 Telegraf 未来新增字段。3. Telegraf 数据 → MAL Sample 的转换TelegrafServiceHandler.convertTelegraf(TelegrafDatum)完成关键映射见 TelegrafServiceHandler.java遍历fields仅处理值为Number类型的字段字符串、布尔等非数值字段被忽略每个数值字段生成一个Sample其name为指标名_字段名例如cpu插件的usage_active字段 →cpu_usage_active这正是vm.yaml中表达式左侧名称的由来timestamp为timestamp * 1000L秒 → 毫秒与只处理秒级时间戳的约束呼应value取字段数值的doubleValue()labels为 Telegraf 的tags如host、cpu供 MAL 的service([host])、tagEqual等算子使用。随后convertSampleFamily(TelegrafData)将所有 metrics 的 Sample 汇总按时间戳分组、再按名称分组构建出 meter 分析器所需的SampleFamily集合见 TelegrafServiceHandler.java。4. MAL 规则执行与可观测性Handler 构造时会将每个规则文件包装为MetricConvert复用oap.meter.analyzer.v2的 MAL 引擎并发布到MalStaticBindingHook以便 dsl-debugging 模块静态绑定调试。收到数据后sampleFamily.forEach(s - metricConvert.forEach(m - m.toMeter(s)));即逐条执行 MAL 表达式将 Sample 转化为 SkyWalking meter 指标并写入 MeterSystem最终落入存储层。此外Handler 还埋点了两个自监控指标telemetrytelegraf_in_latency处理 Telegraf 数据的耗时直方图telegraf_error_countTelegraf 数据分析出错计数。这两个指标带protocolhttp标签可在 SkyWalking 的自监控SO11y页面观察该接收器的健康状态。六、测试验证规则与数据示例仓库为 Telegraf Receiver 提供了完整的单元测试与 MAL 脚本验证数据单元测试TelegrafMetricsTest.java通过 Mock 的 ModuleManager / MeterSystem 构造TelegrafServiceHandler加载vm规则验证 JSON 报文 → TelegrafData → SampleFamily → meter 指标的全链路正确性。MAL 脚本测试数据vm.data.yaml以script指向 telegraf-rules/vm.yamlinput给出模拟的 Telegraf 采样含host、cpu标签expected断言最终产出的meter_vm_*指标及 Service 实体scope: SERVICE, layer: OS_LINUX。该文件可作为验证自定义规则正确性的模板新增规则文件后仿照此文件构造input与expected运行 meter-analyzer-scripts-test 即可在本地验证规则语义。七、扩展自定义规则原文档明确指出Telegraf 生态有大量输入插件用户可以为不同插件定制自己的规则文件。扩展步骤总结如下在 Telegraf 侧启用所需输入插件如[[inputs.disk]]、[[inputs.net]]等确保输出满足三大约束[[outputs.http]]data_format jsonjson_timestamp_units 1sURL 指向 OAP 共享 HTTP 端口的/telegraf编写 MAL 规则文件YAML 格式语法见 MAL 文档放入$CLASSPATH/telegraf-rules/目录运行时 classpath 对应 OAP 发行包的oap-libs与配置文件目录源码对应 oap-server/server-starter/src/main/resources/telegraf-rules激活规则设置SW_RECEIVER_TELEGRAF_ACTIVE_FILES环境变量多个规则文件以逗号分隔重启 OAP 并验证规则文件格式错误会导致启动失败启动成功后可在 SkyWalking UI 的服务OS_LINUX视角查看生成的meter_vm_*指标。提示规则文件中的表达式名称必须与 Telegraf 上报的name _ field命名一致参考convertTelegraf的拼接逻辑并在vm.data.yaml中准备对应的input样例先行验证可大幅降低排查成本。八、小结Telegraf Receiver 让 SkyWalking OAP 得以复用 Telegraf 庞大的采集插件生态把虚拟机乃至各类中间件的系统指标统一纳入 SkyWalking 的 meter 指标体系。核心要点可归纳为协议约束HTTP JSON 秒级时间戳三者是 Telegraf 与 OAP 之间通信的硬性前提配置入口OAP 侧通过receiver-telegraf模块的activeFilesSW_RECEIVER_TELEGRAF_ACTIVE_FILES激活规则规则驱动telegraf-rules/vm.yaml以 MAL 定义指标从采集字段到 SkyWalking 指标的映射与聚合源码闭环POST /telegraf端点 → JSON 反序列化 → Sample/SampleFamily 转换 → MAL 执行 → MeterSystem 落库并伴有telegraf_in_latency、telegraf_error_count自监控指标。读者可结合 vm.yaml、TelegrafServiceHandler.java 与 vm.data.yaml 三个文件快速上手从 Telegraf 到 SkyWalking 的指标接入与规则扩展。赞分享可观测性APM链路追踪指标监控日志分析微服务【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址https://gitcode.com/gh_mirrors/sk/skywalking点击查看免费下载相关推荐SkyWalking Telegraf Receiver 接入指南将 InfluxDB Telegraf 采集的指标纳入 OAP 监控体系SkyWalking Telegraf Receiver 接入指南将 InfluxDB Telegraf 采集的指标纳入 OAP 监控体系 Telegraf可观测性后端微服务云原生SkyWalking OAP OpenTelemetry Receiver 接入指南OTLP 指标采集与 MAL 规则深度解析SkyWalking OAP OpenTelemetry Receiver 接入指南OTLP 指标采集与 MAL 规则深度解析 导读 本文聚焦 Apache可观测性APM链路追踪指标监控日志分析微服务SkyWalking OAP Zabbix Receiver 接入指南Zabbix Agent Active Checks 协议指标采集与配置详解SkyWalking OAP Zabbix Receiver 接入指南Zabbix Agent Active Checks 协议指标采集与配置详解 本指南聚焦可观测性APM链路追踪指标监控日志分析微服务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考