From af3c9f9ac7a7e23167ad8b62f48449f884db719a Mon Sep 17 00:00:00 2001 From: Terence Date: Fri, 28 Sep 2018 17:53:32 +0800 Subject: [PATCH] Update README.md --- lib/java/README.md | 111 +++++++++++++++++++++++++-------------------- 1 file changed, 63 insertions(+), 48 deletions(-) diff --git a/lib/java/README.md b/lib/java/README.md index fb861cdd2..7119efdbd 100644 --- a/lib/java/README.md +++ b/lib/java/README.md @@ -2,7 +2,7 @@ [中文文档](./doc/zh-CN.md) -The java cat supports JDK 1.6+ +The java cat client supports JDK 1.6+ ## Installation @@ -18,24 +18,9 @@ The java cat supports JDK 1.6+ ## Initialization -First of all, you have to create `/data/appdatas/cat` directory, read and write permission is required (0644).`/data/applogs/cat` is also required if you'd like to preserve a debug log, it can be very useful while debugging. +Some [preparations](../_/preparations.md) needs to be done before initializing `cat-client`. -And create a config file `/data/appdatas/cat/client.xml` with the following contents. - -```xml - - - - - - -``` - -> Don't forget to change the `` to your own after you copy and paste the contents. - -With all the preparations have done, you must configure the project under your module. The unified project name is placed in the directory specified by the module as a file. - -You have to create `src/main/resources/META-INF/app.properties` file, add the following: +And then you have to create the `src/main/resources/META-INF/app.properties` file in your project with the following contents: ``` app.name={appkey} @@ -43,6 +28,8 @@ app.name={appkey} > Only English characters (a-z, A-Z), numbers (0-9), underscore (\_) and dash (-) is allowed in appkey. +Due to java cat client will be lazy initialized, it's not necessary to initialize it manually. + ## Quickstart ``` @@ -68,8 +55,6 @@ try { ### Transaction -log the execution of a transaction - > To avoid of forgetting to complete the Transaction, it's better to surround the Transaction by a try-catch-finally block. ``` @@ -86,13 +71,16 @@ try { } ``` -we offered a list of APIs to modify the Transaction. +We offered a series of APIs to modify the Transaction. +* addData +* setStatus +* setDurationStart * setDurationInMillis * setTimestamp -* addData +* complete -These APIs can be easily used like the following codes. +These APIs can be easily used with the following codes. ``` Transaction t = Cat.newTransaction("URL", "pageName"); @@ -111,46 +99,74 @@ try { } ``` -There are something you have to know about the Transaction APIs: +There is something you have to know about the transaction APIs: -1. `Duration` will be calculated while you complete the Transaction. (currentTimestamp - durationStart) -2. Although `durationStart` is as same as `timestamp` by default, you can overwrite it. -3. `durationStart` and `timestamp` are different, the first one represents the start time of the Transaction, and the second one only means created time of a message. (Transaction is just a kind of message) -4. `durationStart` won't work when you specified the `duration`. -5. You can call `addData` several times, the added data will be connected by `&`. +1. You can call `addData` several times, the added data will be connected by `&`. +2. It's meaningless to specify `duration` and `durationStart` in the same transaction, although we do it in the example :) +3. Never forget to complete the transaction! Or you will get corrupted message trees and memory leaks! ### Event #### Cat.logEvent -log the occurrence of an event. +Log an event. ``` -# Log a event with success status and empty data. +# Log an event with success status and empty data. Cat.logEvent("URL.Server", "serverIp"); -# Log a event with success status and additional data. -Cat.logEvent("URL.Server", "serverIp", Event.SUCCESS, "ip=${serverIp}"); +# Log an event with given status and given data. +Cat.logEvent("URL.Server", "serverIp", "failed", "ip=${serverIp}"); ``` #### Cat.logError -log exceptions that occur in the application. +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`. + +1. If `e` is an instanceof `Error`, the `type` will be set to `Error` +2. Else if `e` is an instanceof `RuntimeException`, the `type` will be set to `RuntimeException` +3. The `type` will be set to `Exception` 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`. ``` -# Error traces will be collected when you use it in an except block. 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: + +``` +try { + 1 / 0; +} catch (Exception e) { + Cat.logError("error(X) := exception(X)", e); +} +``` -# customize your own error traces through the 1nd parameter which is optional. -Cat.logError("this is my error stack info", e) +#### Cat.logErrorWithCategory + +Though `name` has been set to the classname of the given `throwable e` by default, you can use this api to overwrite it. + +```java +Exception e = new Exception("syntax error"); +Cat.logErrorWithCategory("custom-category", e); ``` -### Metric +Like `logError`, you can also append your own error message to the top of the stack info. -log the sum or average of the business indicators +```java +Exception e = new Exception("syntax error"); +Cat.logErrorWithCategory("custom-category", "?- X = Y, Y = 2", e); +``` + +### Metric ``` # Counter @@ -163,7 +179,7 @@ Cat.logMetricForDuration("metric.key", 5); We do aggregate every seconds. -For example, if you called count 3 times in one second (with the same name), we will just summarised the value of them and reported once to the server. +For example, if you have called count 3 times in one second (with the same name), we will just summarised the value of them and reported once to the server. In case of `duration`, we use `averaged` value instead of `summarised` value. @@ -171,16 +187,15 @@ In case of `duration`, we use `averaged` value instead of `summarised` value. ### Log component integration -[log4j](./../../integration/log4j/README.md) -[log4j2](./../../integration/log4j2/README.md) -[logback](./../../integration/logback/README.md) +[log4j](../../integration/log4j/README.md) +[log4j2](../../integration/log4j2/README.md) +[logback](../../integration/logback/README.md) ### URL monitoring integration -[URL monitoring integration with web.xml](./../../integration/URL/README.md) -[URL monitoring integration with springboot](./../../integration/spring-boot/README.md) - -### More integration solutions +[URL monitoring integration with web.xml](../../integration/URL/README.md) +[URL monitoring integration with springboot](../../integration/spring-boot/README.md) -more integration solutions refer to the content in the root integration folder. +### Other integration solutions +Please refer to [integration](../../integration) for futhur information. -- GitLab