The java cat client supports JDK 1.6+
<dependency>
<groupId>com.dianping.cat</groupId>
<artifactId>cat-client</artifactId>
<version>${cat.version}</version>
</dependency>
If you don't use maven to manage dependencies, you can directly copy jar/cat-client-3.0.0.jar to the WEB_INF/lib path of your project.
Some preparations needs to be done before initializing cat-client
.
Then you have to create the src/main/resources/META-INF/app.properties
file in your project with the following contents:
app.name={appkey}
Only English characters (a-z, A-Z), numbers (0-9), underscore (_) and dash (-) are allowed in appkey.
- This file is used to configure the address of the server.
- client_cache.xml is the route cache file,if route error occurs,delete client_cache.xml and restart the server
<?xml version="1.0" encoding="utf-8"?>
<config mode="client">
<servers>
<server ip="10.1.1.1" port="2280" http-port="8080"/>
<server ip="10.1.1.2" port="2280" http-port="8080"/>
<server ip="10.1.1.3" port="2280" http-port="8080"/>
</servers>
</config>
2280 is the default port for the CAT server, modification is not allowed,http-port is the port that tomcat starts, the default is 8080, it is recommended to use the default port
Since java cat client will be lazily initialized, it's not necessary to initialize it manually.
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();
}
To avoid forgetting to complete the Transaction, it's better to surround the Transaction by a try-catch-finally block.
Transaction t = Cat.newTransaction("URL", "pageName");
try {
yourBusiness();
t.setStatus(Transaction.SUCCESS);
} catch (Exception e) {
t.setStatus(e);
Cat.logError(e);
} finally {
t.complete();
}
We offered a series of APIs to modify the Transaction.
- addData
- setStatus
- setDurationStart
- setDurationInMillis
- setTimestamp
- complete
These APIs can be easily used with the following codes.
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();
}
There is something you have to know about the transaction APIs:
- You can call
addData
several times, the added data will be connected by&
. - It's meaningless to specify
duration
anddurationStart
in the same transaction, although we did so in the example :) - Never forget to complete the transaction! Or you will get corrupted message trees and memory leaks!
Log an event.
# Log an 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", "failed", "ip=${serverIp}");
Log an error with error stack info.
Error is a special event, the type of it depend on the class of the given Throwable e
.
- If
e
is an instanceofError
, thetype
will be set toError
. - Else if
e
is an instanceofRuntimeException
, thetype
will be set toRuntimeException
. - The
type
will be set toException
in the other cases.
name
will be set to the e.getClass().getName()
by default.
And the stack info will be built and set to data
.
try {
1 / 0;
} catch (Exception e) {
Cat.logError(e);
}
You can append your own error message to the top of the stack info like this:
Cat.logError("error(X) := exception(X)", e);
Though name
has been set to the classname of the given throwable e
by default, you can use this API to overwrite it.
Exception e = new Exception("syntax error");
Cat.logErrorWithCategory("custom-category", e);
Like logError
, you can also append your own error message to the top of the stack info.
Exception e = new Exception("syntax error");
Cat.logErrorWithCategory("custom-category", "?- X = Y, Y = 2", e);
# Counter
Cat.logMetricForCount("metric.key");
Cat.logMetricForCount("metric.key", 3);
# Duration
Cat.logMetricForDuration("metric.key", 5);
We do aggregation every second.
For example, if you have called count 3 times in one second (with the same name), we will just summarize the value of them and report once to the server.
In the case of duration
, we use averaged
value instead of summarized
value.
Please refer to integration for further information.