用户手册

客户端 API 使用说明

SOFALookout 客户端设计上保持了 API 与实现解耦。如果我们只需要基于 SOFALookout API 进行埋点,那么只需要依赖 API 包即可。在没有依赖具体实现模块依赖时(比如 client 依赖 或 SOFABoot(Spring Boot)Start 依赖),API 包会自动使用 NoopRegistry,使得所有埋点的地方都已空实现替代。

1.API 依赖引入

  1. <dependency>
  2. <groupId>com.alipay.sofa.lookout</groupId>
  3. <artifactId>lookout-api</artifactId>
  4. <version>${lookout.client.version}</version>
  5. </dependency>

2.关于 ID

Lookout metrics 相比传统的 metrics 库单一维度的信息描述,提供了支持多维度描述的 tags 能力。 Lookout metrics 的唯一标识 Id 类,由 name 和 tags 构成。

  1. Id basicId = registry.createId("rpc.provider.service.stats");
  2. id = basicId.withTag("service", "com.alipay.demo.demoService")
  3. .withTag("method", "sayHi")
  4. .withTag("protocol", "tr")
  5. .withTag("alias", "group1");

上面是 Id 的简单示例了,如何创建 Id,如何打 tag,(每打一次 tag,都会生成并返回一个新的 Id 对象引用)切记!使用返回新的 Id 对象了哦。

  • 不要主动缓存 Id 或具体的 Metric 对象,Lookout 的 Registry 已经登记记录了。相等的 Id ( name 和 tags 一样)会复用已有的Id 对应 Metric 对象。

2.1 Priority tag (不是必须)

PRIORITY 枚举级别: HIGH, NORMAL, LOW;

  1. id.withTag(LookoutConstants.LOW_PRIORITY_TAG);

如果不打该 Tag (建议),默认是 NORMAL 级别。级别代表了采集间隔周期(HIGH:2s, NORMAL: 30s, LOW: 1min)

2.2 关于 tags

  • 通用的 tags,比如:本机 ip,机房等详细会统一附上,不需要单独指定。
  • 普通 Java 项目直接 lookout-client 时,tags 需要自己指定,特别记住:appName 别忘啦!tag:app=xx
  • key 必须小写,尽量是字母,数字,下划线;
    (尤其是运行期的 Counter, Timer, DistributeSummary 这些 metrics)某个类型的 tag 的 values 尽量是稳定不变有限集合,而且 tags 尽量少,防止 metrics 数量超过最大限制! 比如:rpc 场合 service, method 两个 tag 对应的值是有限较小的;
    反例是每次 rpc 调用都有是个独立的 tag-value。 因此,总体原则自定义打 tags 时要尽量少,对应 values 的集合数量尽量小;
    专门用途的 TAG 名称: “priority”: 表示优先级。
  • 系统保留的 tag key 统配格式_*_,以下划线开始,以下划线结束(比如: “type“ )。 请不要使用这种格式的 key,可能会被系统覆盖或丢弃

3.可接入的统计( Metric )类型API

Counter 「计数器」

  • 场景:方法调用次数;
  • 主动汇报的数据包括: count, rate (也就是 qps);
  • 使用方式
  1. Counter counter=registry.counter(id);
  2. counter.inc();

Timer 「耗时统计器」

  • 场景:统计任务,方法耗时,支持分桶统计
  • 主动汇报的数据包括:elapPerExec (单次执行耗时), total 耗时,Max 耗时,(上报单位:秒);
  • 使用方式
  1. Timer timer=registry.timer(id);
  2. timer.record(2, TimeUnit.SECONDS);

DistributionSummary 「值分布情况统计器」

  • 场景:比如 io 流量,支持分桶统计
  • 主动汇报的数据包括: count, total(size), max(size);
  • 使用方式:
  1. DistributionSummary distributionSummary=registry.distributionSummary(id);
  2. distributionSummary.record(1024);

Gauge 「即时数据观察」

  • 场景:比如线程池,内存值等即时值;
  • 主动汇报的数据包括: value;
    往注册表中登记新 gauge 时,ID 值相等,注册表继续使用已有的(忽略新的);

注意,推荐 gauge 观察的对象尽量是单例的(复用),并且建议在运行时一直活着(而不是作为一个临时的统计)!,如果不是单例或者只存活一段时间,那么一定要从 Registry 中 remove 掉,否则影响 GC(主要是它持有的外部对象引用无法释放,浪费空间)!!

  • 使用方式:
  1. registry.gauge(id,new Gauge<Double>() {
  2. @Override
  3. public Double value() {
  4. return 0.1;
  5. }
  6. });

MixinMetric 「上述基本统计 metrics 的混合管理体」

MixinMetric 是 Lookout 特有的,表示多个基本 metrics 的混合体。引入该 Mixin 目的是优化对「同一度量目标」(即测量目标一致,tags 一致)的多测量指标传输和存储效率,比如:同一线程池的各种指标(线程总数,活跃总数,等待队列大小…)。

  • 使用方式(比如,对一次服务调用,加入多个测量指标:调用耗时,输入字节,调用次数,输出字节等等)
  1. //1. getOrAdd MixinMetric
  2. MixinMetric rpcServiceMetric=registry.minxinMetric(id);
  3. //2. getOrAdd basic component metric to use
  4. Timer rpcTimer = rpcServiceMetric.timer("perf");
  5. DistributionSummary rpcOutSizeMetric = rpcServiceMetric.distributionSummary("inputSize");

Top 工具

  • 场景:列出 TOP 5/10/20…(前 5/10/20… 名)度量信息;

  • 具体背景: 当希望更细粒度地跟踪和度量时,比如某条 sql 语句(某个 URL )的请求耗时,你可能需要将 sql (或 url )作为一个tag ,比如:

  1. sql_execute_cost:sql=select..
  2. sql_execute_cost:sql=insert..
  3. sql_execute_cost:sql=insert2..
  4. ...

这样产生的 metrics 就会非常多!而 metrics 总数量(避免影响业务)上限一般控制在 5k 左右,所以建议尽量少的 tags,每个 tag values 尽量可枚举,且数量也尽量少。

但如果你确实希望定位到一些细粒度的问题,那么推荐使用 TopUtil(它可以只记录前几名的数据,淘汰掉其他数据)。

  • 使用方式
  1. TopGauger topGauger = TopUtil.topGauger(registry, registry.createId("top5sql"), 5);
  2. topGauger.record(1000l, new BasicTag("sql1", "select1"));
  3. topGauger.record(2000l, new BasicTag("sql2", "select2"));
  4. ...