SpringBoot集成Cat客户端

添加依赖

<dependency>
    <groupId>com.dianping.cat</groupId>
    <artifactId>cat-client</artifactId>
    <version>${cat.version}</version>
</dependency>

备注：本测试使用cat-client-3.0.1，cat-client-3.0.0版本jar下载不下来

准备工作

创建 /data/appdatas/cat 目录

确保你具有这个目录的读写权限。
创建 /data/applogs/cat 目录 (可选)

这个目录是用于存放运行时日志的，这将会对调试提供很大帮助，同样需要读写权限。

创建 /data/appdatas/cat/client.xml，内容如下

<?xml version="1.0" encoding="utf-8"?>
<config mode="client">
    <servers>
        <server ip="192.168.1.212" port="2280" http-port="8080"/>
        <server ip="192.168.1.213" port="2280" http-port="8080"/>
        <server ip="192.168.1.214" port="2280" http-port="8080"/>
    </servers>
</config>

2280是默认的CAT服务端接受数据的端口，不允许修改，http-port是Tomcat启动的端口，默认是8080，建议使用默认端口

初始化

然后你需要在你的项目中创建 src/main/resources/META-INF/app.properties 文件, 并添加如下内容:

app.name={appkey}

appkey 只能包含英文字母 (a-z, A-Z)、数字 (0-9)、下划线 (\_) 和中划线 (-)

这里的appkey 即cat中创建的项目名,如图中：xm-demo-cat

现在java的cat client会自动懒加载，已经没有必要手动初始化客户端。

开始测试

快速开始

Transaction t = Cat.newTransaction("URLTest", "pageName");

try {
    // 记录一个事件
    Cat.logEvent("URL.Server", "serverIp", Event.SUCCESS, "ip=${serverIp}");
    // 记录一个业务指标，衡量单位时间内的次数总和
    Cat.logMetricForCount("order.count");
    // 记录一个timer类业务指标，衡量单位时间内平均值
    Cat.logMetricForDuration("order.avg", 5);

    // 你的业务
    yourBusiness();

    t.setStatus(Transaction.SUCCESS);
} catch (Exception e) {
    t.setStatus(e);
    Cat.logError(e);
} finally {
    t.complete();
}

接口测试后，cat中出现监控数据，如下图：

1、Transaction

2、Event

Metric

接口列表

Transaction

为了避免忘记关闭 Transaction, 建议在 finally 代码块中执行 complete。

Transaction t = Cat.newTransaction("URL", "pageName");

try {
    yourBusiness();
    t.setStatus(Transaction.SUCCESS);
} catch (Exception e) {
    t.setStatus(e);
    Cat.logError(e);
} finally {
    t.complete();
}

我们提供了一系列 API 来对 Transaction 进行修改。

addData
setStatus
setDurationStart
setDurationInMillis
setTimestamp
complete

这些 API 使用很方便，参考如下代码：

Transaction t = Cat.newTransaction("URL", "pageName");

try {
    t.setDurationInMillis(1000);
    t.setTimestamp(System.currentTimeMillis());
    t.setDurationStart(System.currentTimeMillis() - 1000);
    t.addData("content");
    t.setStatus(Transaction.SUCCESS);
} catch (Exception e) {
    t.setStatus(e);
    Cat.logError(e);
} finally {
    t.complete();
}

在使用 Transaction API 时，你可能需要注意以下几点：

你可以调用 addData 多次，添加的数据会被 & 连接起来。
同时指定 duration 和 durationStart 是没有意义的，尽管我们在样例中这样做了。
不要忘记完成 transaction！否则你会得到一个毁坏的消息树以及内存泄漏！

Event

Cat.logEvent

记录一个事件。

# Log a event with success status and empty data.
Cat.logEvent("URL.Server", "serverIp");

# Log an event with given status and given data.
Cat.logEvent("URL.Server", "serverIp", Event.SUCCESS, "ip=${serverIp}");

Cat.logError

记录一个带有错误堆栈信息的 Error。

Error 是一种特殊的事件，它的 type 取决于传入的 Throwable e.

如果 e 是一个 Error, type 会被设置为 Error。
如果 e 是一个 RuntimeException, type 会被设置为 RuntimeException。
其他情况下，type 会被设置为 Exception。

同时错误堆栈信息会被收集并写入 data 属性中。

try {
    1 / 0;
} catch (Throwable e) {
    Cat.logError(e);
}

你可以向错误堆栈顶部添加你自己的错误消息，如下代码所示：

Cat.logError("error(X) := exception(X)", e);

Cat.logErrorWithCategory

尽管 name 默认会被设置为传入的 Throwable e 的类名，你仍然可以使用这个 API 来复写它。

Exception e = new Exception("syntax error");
Cat.logErrorWithCategory("custom-category", e);

就像 logError 一样，你也可以向错误堆栈顶部添加你自己的错误消息：

Cat.logErrorWithCategory("custom-category", "?- X = Y, Y = 2", e);

Metric

记录业务指标的总和或平均值。

# Counter
Cat.logMetricForCount("metric.key");
Cat.logMetricForCount("metric.key", 3);

# Duration
Cat.logMetricForDuration("metric.key", 5);

我们每秒会聚合 metric。

举例来说，如果你在同一秒调用 count 三次（相同的 name），我们会累加他们的值，并且一次性上报给服务端。

在 duration 的情况下，我们用平均值来取代累加值。