ubuntu filebeat如何进行插件开发

Ubuntu 下 Filebeat 插件开发实践

一 开发方式与选型

• Processor 插件（最常见）：在事件进入输出前对日志进行加工，如字段增删改、采样、脱敏、路由判定等。实现简单、热插拔友好，适合大多数业务定制需求。
• Output 插件（较少见）：将事件发送到非官方支持的后端（如自研消息总线、存储）。需要熟悉 libbeat 的 publisher 接口与并发模型。
• 输入插件（官方一般不推荐自定义）：Filebeat 的输入模型与生命周期较复杂，官方更建议优先组合现有输入与处理器实现需求；若确需自定义，通常要深入修改或 fork 官方代码。
• 插件形态：
  • 内嵌式：把插件代码放入 beats/libbeat/processors 等目录，随 beats 一起编译，稳定、便于调试。
  • Go 插件（.so）：使用 -buildmode=plugin 编译共享库，运行时通过 -plugin 加载；优点是解耦二进制，但对 Go 版本、libbeat 版本、架构 要求严格，生产上需谨慎。

二 快速上手 Processor 插件

• 步骤概览
  1. 准备环境：安装 Go ≥1.19、git，拉取 elastic/beats（建议与要运行的 Filebeat 版本一致）。
  2. 在本地创建插件目录（示例）：beats/x-pack/filebeat/processor/myplugin。
  3. 实现插件（示例为“按行数采样丢弃”的处理器，保留前 N 条，其余丢弃）：

// file: beats/x-pack/filebeat/processor/myplugin/sample.go
package myplugin

import (
	"sync"

	"github.com/elastic/beats/v7/libbeat/beat"
	"github.com/elastic/beats/v7/libbeat/common"
	"github.com/elastic/beats/v7/libbeat/processors"
	"github.com/pkg/errors"
)

const pluginName = "sample_keep"

type sampleKeep struct {
	config struct {
		Keep uint `config:"keep" validate:"min=0"`
	}
	mu   sync.Mutex
	seen uint
}

func init() {
	processors.RegisterPlugin(pluginName, newSampleKeep)
}

func newSampleKeep(cfg *common.Config) (processors.Processor, error) {
	p := &sampleKeep{}
	if err := cfg.Unpack(&p.config); err != nil {
		return nil, errors.Wrapf(err, "fail to unpack config for %v", pluginName)
	}
	return p, nil
}

func (p *sampleKeep) Run(event *beat.Event) (*beat.Event, error) {
	p.mu.Lock()
	defer p.mu.Unlock()
	if p.seen < p.config.Keep {
		p.seen++
		return event, nil
	}
	return nil, nil // 丢弃
}

func (p *sampleKeep) String() string { return pluginName }

4. 在 filebeat.yml 中使用（注意插件名与代码中一致）：

processors:
  - sample_keep:
      keep: 1000

5. 构建与运行
   • 内嵌式：在 beats 根目录执行 make filebeat，然后用 ./filebeat -e -c filebeat.yml 运行。
   • 验证：观察日志是否按预期保留/丢弃，必要时加 logging.level: debug 排查。

• 要点
  • 插件必须实现 init() 注册、*Run(beat.Event) 处理、String() 名称 三个要素。
  • 通过 cfg.Unpack(&yourConfig) 解析配置，可结合 validate tag 做参数校验。
  • 并发安全：对内部计数器/缓存加锁（如示例中的 sync.Mutex）。

三 构建与运行要点

• 内嵌式（推荐）
  • 与 beats 源码一起编译，避免版本不匹配问题：make filebeat 后直接运行生成的二进制。
• Go 插件（.so）方式
  • 编译：go build -buildmode=plugin -o myplugin.so path/to/plugin.go（插件需依赖与 Filebeat 一致的 libbeat 版本与 Go 版本）。
  • 运行：./filebeat -e -c filebeat.yml -plugin ./myplugin.so（可多次 -plugin 加载多个插件）。
  • 限制：插件与 Filebeat 必须同架构同 Go 版本编译；跨平台（如 macOS 编译的 .so 不能在 Linux 使用）；Go 插件生态在生产环境稳定性不如内嵌式，官方资料也提示需谨慎。

四 常见问题与排查

• 插件不生效
  • 检查 processors: 缩进与名称是否与插件 String() 返回值一致；确认已随 beats 编译或正确通过 -plugin 加载；开启 logging.level: debug 查看插件注册与执行日志。
• 配置无法解析或校验失败
  • 使用 cfg.Unpack 绑定结构体，并为字段添加 validate 规则；在 init() 中使用 processors.RegisterPlugin 注册。
• 并发与性能
  • 处理器可能被多协程并发调用，确保对共享状态加锁；避免在 Run() 中做阻塞或耗时 I/O，必要时将耗时逻辑放到异步 goroutine 并控制并发度。
• 版本与兼容性
  • 插件与运行的 Filebeat 版本需一致（尤其是 libbeat 的 API 与结构定义）；使用 Go 插件时，Go 版本也必须一致，否则会出现加载或运行期符号不匹配问题。