kigo-cat-client

node cat 客户端 v2.0

升级须知

• 所有埋点不需要显示的传入父 transaction
• 需要配合 kigo-context 模块使用

EXAMPLE

var Cat = require('kigo-cat-client');

// Cat 的服务器地址，一个 server 数组，客户端会随机选取一个地址进行连接
var servers = [
  {
    host: 'cat server host',
    port: 'cat server port'
  },
  ...
]

var offset = 1;
var step = 3;

Cat.initialize({
  domain: 'your domain', 
  ip: 'your ip', // 支持模糊匹配，比如 192.168.*.*
  servers: servers,
  offset: offset, // 生成 messageId 递增数字的初始值，可选，默认为 0
  step: step, // 生成 messageId 递增数字的步数，可选，默认为 1
  maxMessageSize: 500, // 缓存的消息到达多少阀值开始丢弃，可选，默认为 1000
});

// 初始化之后可调用 Cat API 进行埋点

API

• initialize(object opts)
• logError(string name, Error e)
• logEvent(string type, string name)
• logEvent(string type, string name, string status, object nameValuePairs)
• logEvent(string type, string name, string status, string nameValuePairs)
• newTransaction(string type, string name)
• newTransactionNullParent(string type, string name)
• logMetricForCount(string name)
• logMetricForCount(string name, int quantity)
• logMetricForDuration(string name, long durationInMillis)
• logMetricForSum(string name, double value)
• logMetricForSum(string name, double value, int quantity)
• logRemoteCallClient()
• logRemoteCallServer(object attachments)

Transaction

• Transaction 适合记录跨越系统边界的程序访问行为，比如远程调用，数据库调用，也适合执行时间较长的业务逻辑监控

• 某些运行期单元要花费一定时间完成工作, 内部需要其他处理逻辑协助, 我们定义为 Transaction

• Transaction 可以嵌套（如 http 请求过程中嵌套了 sql 处理）

• 大部分的Transaction可能会失败, 因此需要一个结果状态码

代码示例

var t = Cat.newTransaction("your transaction type", "your transaction name");
Cat.logEvent("your event type", "your event name");
try {
  yourBusinessOperation();
  t.setStatus(Cat.SUCCESS);
} catch (e) {
  Cat.logError('Error' e);
  t.setStatus(Cat.ERROR);
}
t.complete();

API

• addData(object data)
• addData(string data)
• addData(string key, string value)
• setStatus(string status)
• complete()

Event

• Event用来记录次数，表名单位时间内消息发生次数，比如记录系统异常，它和 Transaction 相比缺少了时间的统计，开销比 Transaction 要小

Metric

• Metric一共有三个API，分别用来记录次数、平均、总和，统一粒度为一分钟

1. logMetricForCount 用于记录一个指标值出现的次数

2. logMetricForDuration 用于记录一个指标出现的平均值

3. logMetricForSum 用于记录一个指标出现的总和

一份埋点的样例

var context = require('kigo-cat-client'); // v2.0 需要配合该模块使用

var pageName = '';
var serverIp = '';
var amount = 0;

function doTransaction() {
  var t = Cat.newTransaction('URL', pageName); // 创建一个 Transaction

  try {
    Cat.logEvent("URL.Server", serverIp, Cat.SUCCESS, 'ip=' + serverIp + '&...');
    // 记录一个业务指标，记录支付次数
    Cat.logMetricForCount('PayCount');
    // 记录一个业务指标，记录支付金额
    Cat.logMetricForSum('PayAmount', amount);

    // 业务逻辑
    yourBusinessOperation();

    t.setStatus(Cat.SUCCESS); // 设置成功状态
  } catch(e) {
    t.setStatus(Cat.ERROR); // 设置失败状态
  }

  t.complete(); // 结束 Transaction
}

context.bindContext(doTransaction)();

远程调用示例

• client 端

var t = Cat.newTransaction('Call', 'bangactorservice_1.0.6_getRoomInfoById');
Cat.logEvent('Call.app', 'bangactorservice_1.0.6');

var attachments = Cat.logRemoteCallClient();

// 远程调用需要将 attachments 传递到服务端
doRpcClient(attachments);

t.setStatus(Cat.SUCCESS);
t.complete();

• server 端

var t = Cat.newTransaction('Service', 'bangactorservice_1.0.6_getRoomInfoById');
// 服务端拿到客户端传过来的 attachments 调用 logRemoteCallServer 方法就可以把 transaction 关联起来
Cat.logRemoteCallServer(attachments);
Cat.logEvent('Service.app', 'bangactorservice_1.0.6');

doRpcServer();

t.setStatus(Cat.SUCCESS);
t.complete();