JarCastingCat Client for Java --因com.dianping.cat的maven仓库无法访问，所以使用此jar包同步相关代码
Cat Java 客户端支持 JDK 1.6 及以上版本
安装
通过 Maven 添加依赖
<dependency>
<groupId>com.alidaodao.app</groupId>
<artifactId>cat-client</artifactId>
<version>${cat.version}</version>
</dependency>
直接引入jar包
如果没有使用maven管理依赖，可以直接复制 jar/cat-client-3.0.0.jar 到项目 WEB_INF/lib 路径下。
初始化
一些准备工作需要在初始化 cat client 之前完成。
然后你需要在你的项目中创建 src/main/resources/META-INF/app.properties 文件, 并添加如下内容:
app.name={appkey}
appkey 只能包含英文字母 (a-z, A-Z)、数字 (0-9)、下划线 (_) 和中划线 (-)
现在java的cat client会自动懒加载，已经没有必要手动初始化客户端。
Quickstart
Transaction t = Cat.newTransaction("URL", "pageName");
try {
Cat.logEvent("URL.Server", "serverIp", Event.SUCCESS, "ip=${serverIp}");
Cat.logMetricForCount("metric.key");
Cat.logMetricForDuration("metric.key", 5);
yourBusiness();
t.setStatus(Transaction.SUCCESS);
} catch (Exception e) {
t.setStatus(e);
Cat.logError(e);
} finally {
t.complete();
}
API List
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 的情况下，我们用平均值来取代累加值。