3分钟上手SkyWalking指标开发：计数器与Gauge实战指南

3分钟上手SkyWalking指标开发：计数器与Gauge实战指南

【免费下载链接】skywalking APM, Application Performance Monitoring System 项目地址: https://gitcode.com/gh_mirrors/sky/skywalking

你是否还在为服务监控指标不满足业务需求而烦恼？是否想实时掌握接口调用频次、资源使用率等关键数据？本文将带你零基础实现SkyWalking自定义计数器（Counter）与仪表盘（Gauge）指标，3分钟上手企业级监控指标开发。

指标体系基础

SkyWalking的Meter系统提供流式指标计算能力，与传统OAL定义不同，它专注于数据类型本身，支持更灵活的作用域定义。每个指标需包含：

• 全局唯一名称：避免与OAL变量冲突
• 聚合函数：如avg、histogram等
• 作用域类型：服务、实例或端点级别

详细概念可参考官方文档：docs/en/concepts-and-designs/meter.md

指标工作流程

计数器（Counter）实现

计数器用于累计递增指标，如接口调用次数、错误发生频次等。其核心是记录样本间的增量变化，而非绝对值。

核心实现代码

计数器窗口管理类维护样本序列，计算时间窗口内的增量： oap-server/analyzer/meter-analyzer/src/main/java/org/apache/skywalking/oap/meter/analyzer/dsl/counter/CounterWindow.java

关键逻辑：

public Tuple2<Long, Double> increase(String metricName, Labels labels, double value, long rangeMillis, long timestamp) {
    // 计算时间窗口内的增量值
    Window<Sample> window = getWindow(metricName, labels);
    double increase = calculateIncrease(window, value, timestamp, rangeMillis);
    return Tuple2.of(window.size(), increase);
}

配置示例

在告警规则中引用计数器指标： dist-material/config-examples/alarm-settings.yml

service_error_count_rule:
  expression: sum(increase(service_errors_total[5m])) > 10
  period: 5
  message: 服务错误数5分钟内超过10次

仪表盘（Gauge）实现

Gauge用于监测瞬时值，如CPU使用率、内存占用等波动指标，直接记录当前数值无需累计。

类型转换处理

Prometheus指标转换器中Gauge类型的处理逻辑： oap-server/analyzer/meter-analyzer/src/main/java/org/apache/skywalking/oap/meter/analyzer/prometheus/PrometheusMetricConverter.java

Case($(instanceOf(Gauge.class)), t -> Collections.singletonList(Sample.builder()
    .name(t.getName())
    .labels(convertLabels(t.getLabels()))
    .value(t.getValue())
    .timestamp(t.getTimestamp())
    .build()));

应用场景

• 系统资源监控：JVM堆内存使用量
• 业务指标：在线用户数、队列长度
• 性能指标：当前活跃线程数

指标开发最佳实践

命名规范

• 计数器：使用_total后缀（如http_requests_total）
• Gauge：直接描述测量对象（如system_cpu_usage）

性能优化

1. 合理设置时间窗口，避免过大窗口导致内存占用
2. 高基数指标使用标签过滤：

include-names-regex: order-service|payment-service

测试验证

使用单元测试验证计数器逻辑： oap-server/analyzer/meter-analyzer/src/test/java/org/apache/skywalking/oap/meter/analyzer/dsl/counter/CounterWindowTest.java

总结与进阶

通过本文你已掌握：

• 计数器与Gauge的核心实现原理
• 配置文件编写与指标引用方法
• 性能优化与测试验证技巧

进阶学习：

• 复杂指标：oap-server/analyzer/meter-analyzer/src/main/java/org/apache/skywalking/oap/meter/analyzer/dsl/Sample.java
• 告警集成：dist-material/alarm-settings.yml

立即动手开发你的业务指标，让SkyWalking监控系统真正为业务赋能！

【免费下载链接】skywalking APM, Application Performance Monitoring System 项目地址: https://gitcode.com/gh_mirrors/sky/skywalking