[i18n] print_printable_section [i18n] print_click_to_print.

[i18n] print_show_regular.

添加自定义采集

在本地开发、验证使用 docker compose 是最便捷的方式，可通过该方式快速地在本地搭建部署一套完整的环境自行管理采集器、ES、prometheus、grafana 等组件。

docker compose --project-directory ./build/docker up

docker compose 建议使用 plugins 方式安装，参考 https://docs.docker.com/compose/install/linux/

1 - 添加自定义采集

框架提供了非常便捷的 API，包括模块启动、数据存储、容器信息、bpf 相关 （load, attach, read, detach, unload）等，用户可通过自定义的采集逻辑，灵活选择合适的采集模式和数据存储的方式。

tracing 类型

根据实际场景，你可以在 core/autotracing 或 core/events 目录下实现接口 ITracingEvent 即可完成 tracing 类型的采集。

// ITracingEvent represents a tracing/event
type ITracingEvent interface {
    Start(ctx context.Context) error
}

步骤如下：

type exampleTracing struct{}

// 注册回调
func init() {
    tracing.RegisterEventTracing("example", newExample)
}

// 创建 tracing
func newExample() (*tracing.EventTracingAttr, error) {
    return &tracing.EventTracingAttr{
        TracingData: &exampleTracing{},
        Internal:    10, // 再次开启 tracing 的间隔时间 seconds
        Flag:        tracing.FlagTracing, // 标记为 tracing 类型
    }, nil
}

// 实现接口 ITracingEvent
func (t *exampleTracing) Start(ctx context.Context) error {
    // do something
    ...

    // 存储数据到 ES 和 本地
    storage.Save("example", ccontainerID, time.Now(), tracerData)
}

// 也可同时实现接口 Collector 以 Prometheus 格式输出 （可选）
func (c *exampleTracing) Update() ([]*metric.Data, error) {
    // from tracerData to prometheus.Metric 
    ...

    return data, nil
}

Metric 类型

在 core/metrics 目录下添加接口 Collector 的实现即可完成 Metric 类型的采集。

type Collector interface {
    // Get new metrics and expose them via prometheus registry.
    Update() ([]*Data, error)
}

步骤如下：

type exampleMetric struct{}

// 注册回调
func init() {
    tracing.RegisterEventTracing("example", newExample)
}

// 创建 Metric
func newExample() (*tracing.EventTracingAttr, error) {
    return &tracing.EventTracingAttr{
        TracingData: &filenrCollector{
            metric: []*metric.Data{
                metric.NewGaugeData("name1", 0, "description of example_name1", nil),
                metric.NewGaugeData("name2", 0, "description of example_name2", nil),                
            },
        },
        Flag: tracing.FlagMetric, // 标记为 Metric 类型
    }, nil
}

// 实现接口 Collector 以 Prometheus 格式输出
func (c *exampleMetric) Update() ([]*metric.Data, error) {
    // do something
    ...

    return data, nil
}

在项目 core 目录下已集成了 3 个采集模块的多种实际场景的示例，包括 bpf 代码、map 数据交互、容器信息等，更多详情可参考对应代码实现。

2 - 如何添加自定义 Autotracing

概述

  • 类型：异常事件驱动（tracing/autotracing）
  • 功能：自动跟踪系统异常状态，并在异常发生时再触发抓取现场上下文信息
  • 特点：
    • 当系统出现异常时，autotracing 会自动触发，捕获相关的上下文信息
    • 事件数据会实时存储在本地并存储到远端ES，同时你也可以生成Prometheus 统计指标进行观测。
    • 适用于获取现场时性能开销较大的场景，例如检测到指标上升到一定阈值、上升速度过快再触发抓取
  • 已集成：cpu 异常使用跟踪（cpu idle）、D状态跟踪（dload）、容器内外部争抢（waitrate）、内存突发分配（memburst）、磁盘异常跟踪（iotracer）

如何添加 Autotracing ？

AutoTracing 只需实现 ITracingEvent 接口并完成注册，即可将事件添加到系统中。

AutoTracing 与 Event 类型在框架实现上没有任何区别，只是针对不同的场景进行了实际应用的区分。

// ITracingEvent represents a autotracing or event
type ITracingEvent interface {
    Start(ctx context.Context) error
}

1. 创建结构体

type exampleTracing struct{}

2. 注册回调函数

func init() {
    tracing.RegisterEventTracing("example", newExample)
}

func newExample() (*tracing.EventTracingAttr, error) {
    return &tracing.EventTracingAttr{
        TracingData: &exampleTracing{},
        Internal:    10, // 再次开启 tracing 的间隔时间 seconds
        Flag:        tracing.FlagTracing, // 标记为 tracing 类型； | tracing.FlagMetric（可选）
    }, nil
}

3. 实现接口 ITracingEvent

func (t *exampleTracing) Start(ctx context.Context) error {
    // detect your care about 
    ...

    // 存储数据到 ES 和 本地
    storage.Save("example", ccontainerID, time.Now(), tracerData)
}

另外也可同时实现接口 Collector 以 Prometheus 格式输出 （可选）

func (c *exampleTracing) Update() ([]*metric.Data, error) {
    // from tracerData to prometheus.Metric 
    ...

    return data, nil
}

在项目 core/autotracing 目录下已集成了多种实际场景的 autotracing 示例，以及框架提供的丰富底层接口，包括 bpf prog，map 数据交互、容器信息等，更多详情可参考对应代码实现。

3 - 如何添加自定义 Event

概述

  • 类型：异常事件驱动（tracing/event）
  • 功能：常态运行在系统达到预设阈值后抓取上下文信息
  • 特点：
    • 与 autotracing 不同，event 是常态运行，而不是在异常时再触发。
    • 事件数据会实时存储在本地并存储到远端ES，同时你也可以生成Prometheus 统计指标进行观测。
    • 适合用于常态监控和实时分析，能够及时发现系统中的异常行为， event 类型的采集对系统性能影响可忽略。
  • 已集成：软中断异常（softirq）、内存异常分配（oom）、软锁定（softlockup）、D 状态进程（hungtask）、内存回收（memreclaim）、异常丢包（dropwatch）、网络入向延迟（net_rx_latency） 等

如何添加事件指标

只需实现 ITracingEvent 接口并完成注册，即可将事件添加到系统。

AutoTracing 与 Event 类型在框架实现上没有任何区别，只是针对不同的场景进行了实际应用的区分。

// ITracingEvent represents a tracing/event
type ITracingEvent interface {
    Start(ctx context.Context) error
}

1. 创建 Event 结构体

type exampleTracing struct{}

2. 注册回调函数

func init() {
    tracing.RegisterEventTracing("example", newExample)
}

func newExample() (*tracing.EventTracingAttr, error) {
    return &tracing.EventTracingAttr{
        TracingData: &exampleTracing{},
        Internal:    10, // 再次开启 tracing 的间隔时间 seconds
        Flag:        tracing.FlagTracing, // 标记为 tracing 类型；| tracing.FlagMetric（可选）
    }, nil
}

3. 实现接口 ITracingEvent

func (t *exampleTracing) Start(ctx context.Context) error {
    // do something
    ...

    // 存储数据到 ES 和 本地
    storage.Save("example", ccontainerID, time.Now(), tracerData)
}

另外也可同时实现接口 Collector 以 Prometheus 格式输出 （可选）

func (c *exampleTracing) Update() ([]*metric.Data, error) {
    // from tracerData to prometheus.Metric 
    ...

    return data, nil
}

在项目 core/events 目录下已集成了多种实际场景的 events 示例，以及框架提供的丰富底层接口，包括 bpf prog, map 数据交互、容器信息等，更多详情可参考对应代码实现。

4 - 如何添加自定义 Metrics

概述

Metrics 类型用于采集系统性能等指标数据，可输出为 Prometheus 格式，作为服务端对外提供数据，通过接口 /metrics (curl localhost:<port>/metrics) 获取。

  • 类型：指标数据采集

  • 功能：采集各子系统的性能指标数据

  • 特点：

    • metrics 主要用于采集系统的性能指标，如 CPU 使用率、内存使用率、网络等，适合用于监控系统的性能指标，支持实时分析和长期趋势观察。
    • 指标数据可以来自常规 procfs/sysfs 采集，也可以从 tracing (autotracing, event) 类型生成指标数据
    • Prometheus 格式输出，便于无缝集成到 Prometheus 观测体系

  • 已集成：

    • cpu (sys, usr, util, load, nr_running…)
    • memory（vmstat, memory_stat, directreclaim, asyncreclaim…）
    • IO (d2c, q2c, freeze, flush…)
    • 网络（arp, socket mem, qdisc, netstat, netdev, socketstat…）

如何添加统计指标

只需实现 Collector 接口并完成注册，即可将指标添加到系统中。

type Collector interface {
    // Get new metrics and expose them via prometheus registry.
    Update() ([]*Data, error)
}

1. 创建结构体

在 core/metrics 目录下创建实现 Collector 接口的结构体：

type exampleMetric struct{
}

2. 注册回调函数

func init() {
    tracing.RegisterEventTracing("example", newExample)
}

func newExample() (*tracing.EventTracingAttr, error) {
    return &tracing.EventTracingAttr{
        TracingData: &exampleMetric{},
        Flag: tracing.FlagMetric, // 标记为 Metric 类型
    }, nil
}

3. 实现 Update 方法

func (c *exampleMetric) Update() ([]*metric.Data, error) {
    // do something
    ...
	return []*metric.Data{
		metric.NewGaugeData("example", value, "description of example", nil),
	}, nil

}

在项目 core/metrics 目录下已集成了多种实际场景的 Metrics 示例，以及框架提供的丰富底层接口，包括 bpf prog, map 数据交互、容器信息等，更多详情可参考对应代码实现。