From d5b2f029778e7e5169d5ca2a9336e4210a8a7c90 Mon Sep 17 00:00:00 2001 From: "terence.fan" Date: Fri, 28 Sep 2018 11:10:26 +0800 Subject: [PATCH] rename & relocate zh-CN.md --- lib/README.md | 31 +++--- lib/{_/zh-CN.md => README.zh-CN.md} | 27 ++--- lib/_/preparations.md | 2 +- lib/c/README.md | 8 +- lib/c/{docs/zh-CN.md => README.zh-CN.md} | 6 +- lib/c/docs/api.md | 6 +- lib/c/docs/api.zh-CN.md | 2 +- lib/cpp/README.md | 8 +- lib/cpp/{docs/zh-CN.md => README.zh-CN.md} | 8 +- lib/cpp/docs/api.md | 6 +- lib/cpp/docs/api.zh-CN.md | 4 +- lib/go/README.md | 24 ++--- lib/go/{docs/zh-CN.md => README.zh-CN.md} | 6 +- lib/go/VERSION | 2 +- lib/node.js/Makefile | 3 - lib/node.js/README.md | 43 +++----- lib/node.js/README.zh-CN.md | 98 +++++++++++++++++++ lib/node.js/examples/event.js | 6 +- lib/node.js/package-lock.json | 2 +- lib/node.js/package.json | 2 +- lib/python/README.md | 40 ++++---- lib/python/{docs/zh-CN.md => README.zh-CN.md} | 29 ++---- 22 files changed, 218 insertions(+), 145 deletions(-) rename lib/{_/zh-CN.md => README.zh-CN.md} (64%) rename lib/c/{docs/zh-CN.md => README.zh-CN.md} (89%) rename lib/cpp/{docs/zh-CN.md => README.zh-CN.md} (86%) rename lib/go/{docs/zh-CN.md => README.zh-CN.md} (96%) delete mode 100644 lib/node.js/Makefile create mode 100644 lib/node.js/README.zh-CN.md rename lib/python/{docs/zh-CN.md => README.zh-CN.md} (84%) diff --git a/lib/README.md b/lib/README.md index a7caa6d9d..ac95947c8 100644 --- a/lib/README.md +++ b/lib/README.md @@ -1,14 +1,17 @@ # Cat Client +[中文文档](./README.zh-CN.md) + ## Overview The following programming languages are supported: -* C -* C++ -* Python -* Go -* Node.js +* [Java](./java) +* [C](./c) +* [C++](./cpp) +* [Python](./python) +* [Go](./go) +* [Node.js](./node.js) And the following programming languages are in our plan: @@ -31,15 +34,15 @@ And the following programming languages are in our plan: * type - Represents a category of message, like `SQL`, `RPC` or `HTTP`. + Represents the category of a message, like `SQL`, `RPC` or `HTTP`. * name - Represents a specified action, for example + Represents a specified action, for example: - * If the **type** is `SQL`, the **name** may be `select from user where id = `, which is the base SQL. - * If the **type** is `RPC`, the **name** may be `QueryOrderByUserId(string, int)`, which is the signature of an api. - * If the **type** is `HTTP`, the **name** may be `/api/v8/{int}/orders`, which is the base uri. + * If the **type** is `SQL`, the **name** could be `select from user where id = `, which is the base SQL. + * If the **type** is `RPC`, the **name** could be `QueryOrderByUserId(string, int)`, which is the signature of an api. + * If the **type** is `HTTP`, the **name** could be `/api/v8/{int}/orders`, which is the base uri. > Detailed information should be recorded in the **data** field, like the parameters of an API. @@ -53,11 +56,11 @@ And the following programming languages are in our plan: Record the detailed information about a message. - * If the **type** is `SQL`, the **data** may be `id=75442432` - * If the **type** is `RPC`, the **data** may be `userType=dianping&userId=9987` - * If the **type** is `HTTP`, the **data** may be `orderId=75442432` + * If the **type** is `SQL`, the **data** could be `id=75442432` + * If the **type** is `RPC`, the **data** could be `userType=dianping&userId=9987` + * If the **type** is `HTTP`, the **data** could be `orderId=75442432` - `data` field may also contain `error stack trace` in some cases. (like represent an exception or an error) + `data` field may also contain `error stack traces` in some cases. (like represent an exception or an error) * timestamp diff --git a/lib/_/zh-CN.md b/lib/README.zh-CN.md similarity index 64% rename from lib/_/zh-CN.md rename to lib/README.zh-CN.md index 015deaa88..b5fcb7a34 100644 --- a/lib/_/zh-CN.md +++ b/lib/README.zh-CN.md @@ -1,14 +1,15 @@ # Cat Client -## Overview +## 总览 我们目前支持以下编程语言： -* C -* C++ -* Python -* Go -* Node.js +* [Java](./java/README.zh-CN.md) +* [C](./c/README.zh-CN.md) +* [C++](./cpp/README.zh-CN.md) +* [Python](./python/README.zh-CN.md) +* [Go](./go/README.zh-CN.md) +* [Node.js](./node.js/README.zh-CN.md) 以下编程语言在我们的支持计划中： @@ -37,9 +38,9 @@ 表示一个特定的行为，举例来说： - * 如果 **type** 是 `SQL`, **name** 可以是 `select from user where id = `, 表示一个 SQL 模版。 - * 如果 **type** 是 `RPC`, **name** 可以是 `QueryOrderByUserId(string, int)`, 表示一个 API 的函数签名。 - * 如果 **type** 是 `HTTP`, **name** 可以是 `/api/v8/{int}/orders`, 表示基础 URI。 + * 如果 **type** 是 `SQL`, **name** 可以是 `select from user where id = `, 表示一个 SQL 模版。 + * 如果 **type** 是 `RPC`, **name** 可以是 `QueryOrderByUserId(string, int)`, 表示一个 API 的函数签名。 + * 如果 **type** 是 `HTTP`, **name** 可以是 `/api/v8/{int}/orders`, 表示基础 URI。 > 更详细的信息建议在 **data** 字段中记录，比如 api 的参数 @@ -53,9 +54,9 @@ 记录一个消息的详细信息 - * 如果 **type** 是 `SQL`, **data** 可以是 `id=75442432` - * 如果 **type** 是 `RPC`, **data** 可以是 `userType=dianping&userId=9987` - * 如果 **type** 是 `HTTP`, **data** 可以是 `orderId=75442432` + * 如果 **type** 是 `SQL`, **data** 可以是 `id=75442432` + * 如果 **type** 是 `RPC`, **data** 可以是 `userType=dianping&userId=9987` + * 如果 **type** 是 `HTTP`, **data** 可以是 `orderId=75442432` 在一些情况下，`data` 字段会包含错误堆栈信息（比如代表一个 exception 或者 error） @@ -73,7 +74,7 @@ 会在 transaction 被完成时计算。 - > duration = currentTimestamp() - durationStart + > duration = currentTimestamp() - durationStart 你可以通过相关 API 在 transaction 被完成前指定 `duration` 的值，并且跳过计算过程。 diff --git a/lib/_/preparations.md b/lib/_/preparations.md index 96ad5dd82..eacbf9ae0 100644 --- a/lib/_/preparations.md +++ b/lib/_/preparations.md @@ -8,7 +8,7 @@ This directory is used for preserving debug logs, which can be very useful while debugging, **read and write** permission is also required. -3. Create `/data/appdatas/cat/client.xml` with following contents. +3. Create `/data/appdatas/cat/client.xml` with the following contents. ```xml diff --git a/lib/c/README.md b/lib/c/README.md index 147b83674..2994ef702 100644 --- a/lib/c/README.md +++ b/lib/c/README.md @@ -1,8 +1,8 @@ # Cat Client for C -[中文文档](./docs/zh-CN.md) +[中文文档](./README.zh-CN.md) -The cat client can be compiled and used on both Linux (both glibc and musl-libc) and OSX. +The `ccat` can be compiled and used on both Linux (both glibc and musl-libc) and OSX. The following Operating Systems are tested: @@ -47,7 +47,7 @@ gcc -lcatclient x.c ## Initialization -Some [preparations](../_/preparations.md) needs to be done before initialize `ccat`. +Some [preparations](../_/preparations.md) needs to be done before initializing `ccat`. With all the preparations have been done, it's easy to initialize `ccat` in your c codes. @@ -59,7 +59,7 @@ catClientInit("appkey"); > Only English characters (a-z, A-Z), numbers (0-9), underscore (\_) and dash (-) is allowed in appkey. -Note that `sampling`, built-in `heartbeat` and `binary` encoder is enabled by default, which you may want to disable it. We also offered an API to customize your initialization, please refer to our [apidoc](./docs/api.md). +Note that `sampling`, built-in `heartbeat` and `binary` encoder is enabled by default, which you may want to disable it. We also offered an API to customize your initialization, please refer to our [API doc](./docs/api.md). ## Documentation diff --git a/lib/c/docs/zh-CN.md b/lib/c/README.zh-CN.md similarity index 89% rename from lib/c/docs/zh-CN.md rename to lib/c/README.zh-CN.md index c4a7d10a7..40de17773 100644 --- a/lib/c/docs/zh-CN.md +++ b/lib/c/README.zh-CN.md @@ -1,6 +1,6 @@ # Cat Client for C -`ccat` 同时支持 linux (glibc 和 musl-libc) 和 osx 两个平台。 +`ccat` 同时支持 Linux (glibc 和 musl-libc) 和 OSX 两个平台。 下述列出的操作系统是经过测试可用的： @@ -12,7 +12,7 @@ * Ubuntu 16.04 LTS * Ubuntu 18.04 LTS -我们也提供了 c++ 版本的客户端，参考 [cppcat](../../cpp/docs/zh-CN.md) +我们也提供了 c++ 版本的客户端，参考 [cppcat](../cpp/README.zh-CN.md) ## 编译 @@ -62,4 +62,4 @@ catClientInit("appkey"); ## Documentation -[API 文档](./api.zh-CN.md) +[API 文档](./docs/api.zh-CN.md) diff --git a/lib/c/docs/api.md b/lib/c/docs/api.md index 9fd5bcf91..fe2e3e4db 100644 --- a/lib/c/docs/api.md +++ b/lib/c/docs/api.md @@ -1,4 +1,4 @@ -# cat c client +# Cat Client for C ## Quickstart @@ -268,7 +268,7 @@ void logMetricForCount(const char *name, int quantity); The metric will be sent every 1 second. -For example, if you called this API 3 times in one second (can be in different threads, we use a concurrent hash map to cache the value), only the aggregated value (summarized) will be reported to the server. +For example, if you have called this API 3 times in one second (can be in different threads, we use a concurrent hash map to cache the value), only the aggregated value (summarized) will be reported to the server. #### logMetricForDuration @@ -276,7 +276,7 @@ For example, if you called this API 3 times in one second (can be in different t void logMetricForDuration(const char *name, unsigned long long duration); ``` -Like `logMetricForCount`, the metrics reported in the same second will be aggregated, the only difference is `averaged` value is used instead of `summarized` value. +Like `logMetricForCount`, the metrics that have been logged in the same second will be aggregated, the only difference is `averaged` value is used instead of `summarized` value. ### Heartbeat diff --git a/lib/c/docs/api.zh-CN.md b/lib/c/docs/api.zh-CN.md index 28de0a20c..53b536bb8 100644 --- a/lib/c/docs/api.zh-CN.md +++ b/lib/c/docs/api.zh-CN.md @@ -1,4 +1,4 @@ -# cat c client +# Cat client for C ## 快速起步 diff --git a/lib/cpp/README.md b/lib/cpp/README.md index fd78478b7..fd22b29a9 100644 --- a/lib/cpp/README.md +++ b/lib/cpp/README.md @@ -1,8 +1,8 @@ # Cat Client for C++ -[中文文档](./docs/zh-CN.md) +[中文文档](./README.zh-CN.md) -The cat client can be compiled and used both on Linux (both glibc and musl-libc) and OSX. +The `cppcat` can be compiled and used both on Linux (both glibc and musl-libc) and OSX. The following Operating Systems are tested: @@ -53,7 +53,7 @@ g++ -lcatclient x.cpp ## Initialization -Some [preparations](../_/preparations.md) needs to be done before initialize `cppcat`. +Some [preparations](../_/preparations.md) needs to be done before initializing `cppcat`. With all the preparations have been done, it's easy to initialize `cppcat` in your c++ codes. @@ -65,7 +65,7 @@ cat::init("appkey"); > Only English characters (a-z, A-Z), numbers (0-9), underscore (\_) and dash (-) is allowed in appkey. -Note that `sampling`, built-in `heartbeat` and `binary` encoder is enabled by default, which you may want to disable it. We also offered an API to customize your initialization, please refer to our [apidoc](./docs/api.md). +Note that `sampling`, built-in `heartbeat` and `binary` encoder is enabled by default, which you may want to disable it. We also offered an API to customize your initialization, please refer to our [API doc](./docs/api.md). ## Documentation diff --git a/lib/cpp/docs/zh-CN.md b/lib/cpp/README.zh-CN.md similarity index 86% rename from lib/cpp/docs/zh-CN.md rename to lib/cpp/README.zh-CN.md index 5b1d504cb..63a73ae7a 100644 --- a/lib/cpp/docs/zh-CN.md +++ b/lib/cpp/README.zh-CN.md @@ -1,6 +1,6 @@ # Cat Client for C++ -`cppcat` 同时支持 linux (glibc 和 musl-libc) 和 osx 两个平台。 +`cppcat` 同时支持 Linux (glibc 和 musl-libc) 和 OSX 两个平台。 下述列出的操作系统是经过测试可用的： @@ -48,7 +48,7 @@ gcc -lcatclient x.cpp ## 初始化 -一些[准备工作](../../_/preparations.zh-CN.md)需要在初始化 `cppcat` 之前完成。 +一些[准备工作](../_/preparations.zh-CN.md)需要在初始化 `cppcat` 之前完成。 当你完成这些准备工作后，在你的 c++ 代码中初始化 `cppcat` 就很简单了。 @@ -60,8 +60,8 @@ cat::init("appkey"); > appkey 只能包含英文字母 (a-z, A-Z)、数字 (0-9)、下划线 (\_) 和中划线 (-) -注意，**采样**，内置**心跳**，**二进制**序列化在默认情况下是开启的，你可能会想要禁用他们。我们同时提供了一个 API 可以使你自定义启动参数，请参考 [API 文档](./api.zh-CN.md) +注意，**采样**，内置**心跳**，**二进制**序列化在默认情况下是开启的，你可能会想要禁用他们。我们同时提供了一个 API 可以使你自定义启动参数，请参考 [API 文档](./docs/api.zh-CN.md) ## Documentation -[API 文档](./api.zh-CN.md) +[API 文档](./docs/api.zh-CN.md) diff --git a/lib/cpp/docs/api.md b/lib/cpp/docs/api.md index d37ea79d2..72a145a8d 100644 --- a/lib/cpp/docs/api.md +++ b/lib/cpp/docs/api.md @@ -1,4 +1,4 @@ -# cat c++ client +# Cat Client for C++ ## Quickstart @@ -168,7 +168,7 @@ void logMetricForCount(const string& key, unsigned int count = 1); The metric will be sent every 1 second. -For example, if you called this API 3 times in one second (can be in different threads, we use a concurrent hash map to cache the value), only the aggregated value (summarized) will be reported to the server. +For example, if you have called this API 3 times in one second (can be in different threads, we use a concurrent hash map to cache the value), only the aggregated value (summarized) will be reported to the server. #### logMetricForDuration @@ -176,4 +176,4 @@ For example, if you called this API 3 times in one second (can be in different t void logMetricForDuration(const string& key, unsigned long ms); ``` -Like `logMetricForCount`, the metrics reported in the same second will be aggregated, the only difference is `averaged` value is used instead of `summarized` value. +Like `logMetricForCount`, the metrics that have been logged in the same second will be aggregated, the only difference is `averaged` value is used instead of `summarized` value. diff --git a/lib/cpp/docs/api.zh-CN.md b/lib/cpp/docs/api.zh-CN.md index 39d551812..8aab9b641 100644 --- a/lib/cpp/docs/api.zh-CN.md +++ b/lib/cpp/docs/api.zh-CN.md @@ -1,4 +1,4 @@ -# cat c++ client +# Cat Client for C++ ## Quickstart @@ -140,7 +140,7 @@ t.Complete(); 这里有一些你可能想要知道的： -1. 你可以调用 `addData` 和 `addKV` 多次，他们会被 `&` 连接起来。 +1. 你可以调用 `AddData` 多次，他们会被 `&` 连接起来。 2. 同时指定 `duration` 和 `durationStart` 是没有意义的，尽管我们在样例中这样做了。 3. 不要忘记完成 transaction！否则你会得到一个毁坏的消息树以及内存泄漏！ diff --git a/lib/go/README.md b/lib/go/README.md index 764c10e65..65f329391 100644 --- a/lib/go/README.md +++ b/lib/go/README.md @@ -1,12 +1,12 @@ # Cat Client for Go -[中文文档](./docs/zh-CN.md) +[中文文档](./README.zh-CN.md) -Gocat supports Go 1.8+ +`gocat` supports Go 1.8+ -Gocat is highly dependent on `ccat`. (through CGO) +`gocat` is highly dependent on `ccat`. (through CGO) -Since we using the thread local to storage the transaction stack in `ccat`, which is necessary to build a message tree. It's hard for us to let it work appropriately with goroutines. (Because a goroutine can be run in different threads, due to the MPG model) +Since we are using the thread local to storage the transaction stack in `ccat`, which is necessary to build a `message tree`. It's hard for us to let it work appropriately with goroutines. (Because a goroutine can be run in different threads, due to the MPG model) So we don't support `message tree` in this version. Don't worry, we are still working on it and have some great ideas at the moment. @@ -20,9 +20,9 @@ $ go get github.com/dianping/cat/lib/go/... ## Initialization -Some [preparations](../_/preparations.md) needs to be done before initialize `ccat`. +Some [preparations](../_/preparations.md) needs to be done before initializing `gocat`. -And then you can initialize `gocat` with following codes: +And then you can initialize `gocat` with the following codes: ```c import ( @@ -45,11 +45,11 @@ t := cat.NewTransaction(TTYPE, "test") defer t.Complete() ``` -We strongly recommend using `defer` keyword to make sure the transaction be completed, or it may cause problems. +We strongly recommend using `defer` keyword to make sure that the transaction completed, or it may cause problems. #### Transaction apis -We offered a list of APIs to modify the transaction. +We offered a series of APIs to modify the transaction. * AddData * SetStatus @@ -58,7 +58,7 @@ We offered a list of APIs to modify the transaction. * SetTimestamp * Complete -These APIs can be easily used as the following codes. +These APIs can be easily used with the following codes. ```go t := cat.NewTransaction(TTYPE, "test") @@ -113,13 +113,13 @@ cat.LogEvent("Event", "E4", "failed", "some debug info") #### LogError -Log an error with error stack trace. +Log an error with error stack traces. Error is a special event, `type = Exception` and `name = error` by default. `name` can be overwritten by the 2nd parameter. -`error stack trace` will be collected and add to `data` +`error stack traces` will be collected and added to `data`. ```go err := errors.New("error") @@ -133,7 +133,7 @@ cat.LogError(err, 'error-name') We do aggregate metrics every second. -For example, if you called count 3 times in the same second (with the same name), we will just summarise the value of them and reported once to the server. +For example, if you have called count 3 times in the same second (with the same name), we will just summarise the value of them and report once to the server. In the case of `duration`, we use `averaged` value instead of `summarised` value. diff --git a/lib/go/docs/zh-CN.md b/lib/go/README.zh-CN.md similarity index 96% rename from lib/go/docs/zh-CN.md rename to lib/go/README.zh-CN.md index 5cd8a2956..5cc3b8c7d 100644 --- a/lib/go/docs/zh-CN.md +++ b/lib/go/README.zh-CN.md @@ -1,8 +1,8 @@ # Cat Client for Go -Gocat 支持 Go 1.8 及以上版本。 +`gocat` 支持 Go 1.8 及以上版本。 -Gocat 高度依赖 `ccat`（基于 CGO 实现） +`gocat` 高度依赖 `ccat`（基于 CGO 实现） 鉴于我们在 `ccat` 中使用**线程空间**来存储 transaction 栈，并用于构建消息树，我们很难让它和 goroutine 共同工作。（因为 MPG 模型的关系，一个 goroutine 可能会在不同的线程中运行） @@ -71,7 +71,7 @@ t.SetDuration(time.Millisecond.Nanoseconds() * 1000) 在使用 Transaction 提供的 API 时，你可能需要注意以下几点： -1. 你可以调用 `AddData`，他们会被 `&` 连接起来。 +1. 你可以调用 `AddData` 多次，他们会被 `&` 连接起来。 2. 同时指定 `duration` 和 `durationStart` 是没有意义的，尽管我们在样例中这样做了。 3. 不要忘记完成 transaction！否则你会得到一个毁坏的消息树以及内存泄漏！ diff --git a/lib/go/VERSION b/lib/go/VERSION index 3eefcb9dd..4a36342fc 100644 --- a/lib/go/VERSION +++ b/lib/go/VERSION @@ -1 +1 @@ -1.0.0 +3.0.0 diff --git a/lib/node.js/Makefile b/lib/node.js/Makefile deleted file mode 100644 index 12d034a63..000000000 --- a/lib/node.js/Makefile +++ /dev/null @@ -1,3 +0,0 @@ -build: - node-gyp configure - node-gyp build diff --git a/lib/node.js/README.md b/lib/node.js/README.md index 535418898..81cfb5148 100644 --- a/lib/node.js/README.md +++ b/lib/node.js/README.md @@ -1,10 +1,10 @@ -# Cat client for Node.js +# Cat Client for Node.js `nodecat` supports node v8+. ## Requirements -The `nodecat` required `libcatclient.so` installed in `LD_LIBRARY_PATH`. +The `nodecat` required `libcatclient.so` to be installed in `LD_LIBRARY_PATH`. Please refer to [ccat installation](../c/README.md) for further information. @@ -18,31 +18,18 @@ npm install nodecat ## 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 `ccat`. -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. - -After you've done all things above, `nodecat` can be initialized with following codes: +And then you can initialize `nodecat` with the following codes: ```js var cat = require('nodecat') cat.init({ - appkey: 'your-appkey' + appkey: 'appkey' }) ``` -> Only English characters, numbers, underscore and dash is allowed in appkey. +> Only English characters (a-z, A-Z), numbers (0-9), underscore (\_) and dash (-) is allowed in appkey. ## Documentation @@ -55,14 +42,12 @@ setTimeout(() => t.complete(), 3000) #### Transaction apis -We offered a list of APIs to modify the transaction. +We offered a series of APIs to modify the transaction. * addData * setStatus * complete -> You can call `addData` several times, the added data will be connected by `&`. - Here is an exapmle: ```js @@ -73,6 +58,8 @@ t.setStatus(cat.STATUS.SUCCESS) setTimeout(() => t.complete(), 3000) ``` +> You can call `addData` several times, the added data will be connected by `&`. + ### Event #### logEvent @@ -83,30 +70,30 @@ Log an event. // Log a event with success status and empty data. cat.logEvent("Event", "E1") -// The third parameter (status) is optional, default by "0". +// The 3rd parameter (status) is optional, default is "0". // It can be any of string value. // The event will be treated as "problem" unless the given status == cat.STATUS.SUCCESS ("0") // which will be recorded in our problem report. cat.logEvent("Event", "E2", cat.STATUS.FAIL) cat.logEvent("Event", "E3", "failed") -// The fourth parameter (data) is optional, default by "". +// The 4th parameter (data) is optional, default is "". // It can be any of string value. cat.logEvent("Event", "E4", "failed", "some debug info") -// The fourth parameter (data) can also be an object +// The 4th parameter (data) can also be an object // In this case, the object will be dumped into json. cat.logEvent("Event", "E5", "failed", {a: 1, b: 2}) ``` #### logError -Log an error with error stack. +Log an error with error stack traces. Error is a special event, with `type = Exception` and `name` is given by the 1st parameter. -And error stacktrace will be added to `data`, which is always useful in debugging. +And the error stack traces will be added to `data`, which is always useful in debugging. ```js cat.logError('ErrorInTransaction', new Error()) -``` \ No newline at end of file +``` diff --git a/lib/node.js/README.zh-CN.md b/lib/node.js/README.zh-CN.md new file mode 100644 index 000000000..7a22a67da --- /dev/null +++ b/lib/node.js/README.zh-CN.md @@ -0,0 +1,98 @@ +# Cat Client for Node.js + +`nodecat` 支持 node v8 及以上版本。 + +## Requirements + +`nodecat` 需要 `libcatclient.so` 被安装在 `LD_LIBRARY_PATH` 目录下。 + +请参阅 [ccat 安装](../c/README.zh-CN.md) 以获取进一步的信息。 + +## Installation + +### via npm + +```bash +npm install nodecat +``` + +## Initialization + +一些[准备工作](../_/preparations.zh-CN.md)需要在初始化 `gocat` 之前完成。 + +然后你就可以通过下面的代码初始化 `nodecat` 了： + +```js +var cat = require('nodecat') + +cat.init({ + appkey: 'your-appkey' +}) +``` + +> appkey 只能包含英文字母 (a-z, A-Z)、数字 (0-9)、下划线 (\_) 和中划线 (-) + +## Documentation + +### Transaction + +```js +let t = cat.newTransaction('foo', 'bar') +setTimeout(() => t.complete(), 3000) +``` + +#### Transaction apis + +我们提供了一组 API 来修改 transaction 的属性。 + +* addData +* setStatus +* complete + +这些 API 可以很方便的通过如下代码使用： + +```js +let t = cat.newTransaction('foo', 'bar') +t.addData("key", "val") +t.addData("context") +t.setStatus(cat.STATUS.SUCCESS) +setTimeout(() => t.complete(), 3000) +``` + +> 你可以调用 `addData` 多次，他们会被 `&` 连接起来。 + +### Event + +#### logEvent + +```js +// 记录一个信息，默认成功并且没有 data +cat.logEvent("Event", "E1") + +// 第三个参数 (status) 是可选的，默认是 "0" +// 可以是任意字符串类型 +// 当传入的 status 不是 cat.STATUS.SUCCESS ("0") 时，event 会被作为 "problem" +// 并且会被记录到我们的 problem 报表中 +cat.logEvent("Event", "E2", cat.STATUS.FAIL) +cat.logEvent("Event", "E3", "failed") + +// 第四个参数 (data) 是可选的，默认是 "" +// 可以是任意字符串类型 +cat.logEvent("Event", "E4", "failed", "some debug info") + +// 第四个参数 (data) 也可以是一个 Object +// 在这个情况下，Object 会被序列化为 json 格式的字符串。 +cat.logEvent("Event", "E5", "failed", {a: 1, b: 2}) +``` + +#### logError + +记录一个带堆栈信息的错误 + +错误是一种特殊的 event，默认情况下 `type = Exception`，`name` 通过第一个参数指定。 + +错误堆栈会被收集并存放在 `data` 属性中，这通常对调试有很大帮助。 + +```js +cat.logError('ErrorInTransaction', new Error()) +``` diff --git a/lib/node.js/examples/event.js b/lib/node.js/examples/event.js index 61f1a4405..6dc54bd1a 100644 --- a/lib/node.js/examples/event.js +++ b/lib/node.js/examples/event.js @@ -8,18 +8,18 @@ for (var i = 0; i < 10; i++) { // Log a event with success status and empty data. cat.logEvent("Event", "E1") - // The third parameter (status) is optional, default by "0". + // The 3rd parameter (status) is optional, default is "0". // It can be any of string value. // The event will be treated as "problem" unless the given status == cat.STATUS.SUCCESS ("0") // which will be recorded in our problem report. cat.logEvent("Event", "E2", cat.STATUS.FAIL) cat.logEvent("Event", "E3", "failed") - // The fourth parameter (data) is optional, default by "". + // The 4th parameter (data) is optional, default is "". // It can be any of string value. cat.logEvent("Event", "E4", "failed", "some debug info") - // The fourth parameter (data) can also be an object + // The 4th parameter (data) can also be an object // In this case, the object will be dumped into json. cat.logEvent("Event", "E5", "failed", {a: 1, b: 2}) } diff --git a/lib/node.js/package-lock.json b/lib/node.js/package-lock.json index 1ba6da800..50e10fd5f 100644 --- a/lib/node.js/package-lock.json +++ b/lib/node.js/package-lock.json @@ -1,6 +1,6 @@ { "name": "nodecat", - "version": "1.0.0", + "version": "3.0.0", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/lib/node.js/package.json b/lib/node.js/package.json index 2584fd856..69862c65f 100644 --- a/lib/node.js/package.json +++ b/lib/node.js/package.json @@ -1,6 +1,6 @@ { "name": "nodecat", - "version": "1.0.0", + "version": "3.0.0", "description": "Cat client for Node.js.", "main": "index.js", "scripts": { diff --git a/lib/python/README.md b/lib/python/README.md index 75732b3bc..2c75dc627 100644 --- a/lib/python/README.md +++ b/lib/python/README.md @@ -1,8 +1,8 @@ -# Cat Client Python +# Cat Client for Python -[中文文档](./docs/zh-CN.md) +[中文文档](./README.zh-CN.md) -The pycat can be used both in python2 (>=2.6) and python3 (>=3.5) +The `pycat` can be used both in python2 (>=2.6) and python3 (>=3.5) ## Installation @@ -20,9 +20,9 @@ python setup.py install ## Initialization -Some [preparations](../_/preparations.md) needs to be done before initialize `pycat`. +Some [preparations](../_/preparations.md) needs to be done before initializing `pycat`. -With all the preparations have been done, it's easy to initialize `pycat` in your python codes. +And then you can initialize `pycat` with the following codes: ```python cat.init("appkey") @@ -32,11 +32,11 @@ cat.init("appkey") ### Coroutine Mode -Since we are using `ThreadLocal` to storage the transaction stack in `ccat`, which is neccessary to build message tree, and `pycat` is highly dependent on `ccat`. (with cffi) +Since we are using `ThreadLocal` to storage the transaction stack in `ccat`, which is neccessary to build the `message tree`, and `pycat` is highly dependent on `ccat`. (with cffi) -So we don't support message tree in `coroutine` modes, like `gevent`, `greenlet`. +So we don't support message tree in `coroutine` modes, like `gevent`, `greenlet` because different coroutines that in the same thread run alternately. -In these cases, you should use the following code to initialize `pycat` to disable message tree. +In these cases, you should use the following code to initialize `pycat`. ```python cat.init("appkey", logview=False) @@ -46,7 +46,7 @@ Then we will disable the context manager which is used for building `message tre ### Sampling -Sampling is enabled by default, you can disable it. +Sampling is enabled by default, you can disable it through the following codes. ```python cat.init("appkey", sampling=False) @@ -54,7 +54,7 @@ cat.init("appkey", sampling=False) ### Encoder -The default encoder is `binary encoder`, you can switch it to `text encoder`, which can be recognized by the earlier version of `cat server`. +The default encoder is `binary encoder`, you can switch it to `text encoder`, which can be recognized by the earlier version of the cat server. ```python cat.init("appkey", encoder=cat.ENCODER_TEXT) @@ -102,7 +102,7 @@ t = cat.Transaction("Trans", "t3") t.complete() ``` -To avoid of forgetting to complete the transaction, we strongly recommend to surround the transaction by a `try-finally` block, and complete the transaction in the `finally` code block. +To avoid of forgetting to complete the transaction, we strongly recommend you to surround the transaction by a `try-finally` block, and complete the transaction in the `finally` code block. ```python try: @@ -113,7 +113,7 @@ finally: We also provide `decorator` and `context manager` usages, which can complete the transaction automatically. -And we highly recommend to use the transaction in these ways. +And we highly recommend you to use the transaction in these ways. #### via decorator @@ -128,7 +128,7 @@ def test(): If something goes wrong in the decorated function, the status of the transaction will be set to `FAILED`, and whatever the function raised a exception or not, the transaction will be auto-completed. -The only problem is that you can't get the transaction object if you monitor a function via transaction decorator. +The only problem is that you can't get the transaction object if you monitor a function via decorator. #### via context manager @@ -148,7 +148,7 @@ Though it is a bit complex, you can get the transaction object :) ### Transaction apis -We offered a list of APIs to modify the transaction. +We offered a series of APIs to modify the transaction. * add\_data * set\_status @@ -157,7 +157,7 @@ We offered a list of APIs to modify the transaction. * set\_timestamp * complete -These APIs can be easily used like the following codes. +These APIs can be easily used with the following codes. ```python try: @@ -187,14 +187,14 @@ There is something you may want to know: # Log a event with success status and empty data. cat.log_event("Event", "E1") -# The third parameter (status) is optional, default is "0". +# The 3rd parameter (status) is optional, default is "0". # It can be any of string value. # The event will be treated as a "problem" unless the given status == cat.CAT_CUSSESS ("0") # which will be recorded in our problem report. cat.log_event("Event", "E2", cat.CAT_ERROR) cat.log_event("Event", "E3", "failed") -# The fourth parameter (data) is optional, default is "". +# The 4th parameter (data) is optional, default is "". # It can be any of string value. cat.log_event("Event", "E4", "failed", "some debug info") ``` @@ -205,7 +205,7 @@ Log an exception. Exception is a special event, with `type = Exception` and `name = exc.__class__.__name__` by default. -Due to an exception is usually in an except block, the error traces will be automatically collected and reported. +Due to an exception is usually in an except block, the error traces will be automatically collected and report. ```python try: @@ -229,7 +229,7 @@ cat.log_exception(e, "customized trace info") Log an error. -An error is a light exception, with `type = Exception` and name is given by the 1st parameter. +Error is a light exception, with `type = Exception` and name is given by the 1st parameter. ```python # Same as cat.log_event("Exception", "e1") @@ -258,6 +258,6 @@ cat.metric("metric2").duration(100) 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 report once to the server. In case of `duration`, we use `averaged` value instead of `summarised` value. diff --git a/lib/python/docs/zh-CN.md b/lib/python/README.zh-CN.md similarity index 84% rename from lib/python/docs/zh-CN.md rename to lib/python/README.zh-CN.md index 5c5d6c734..50bb3cedf 100644 --- a/lib/python/docs/zh-CN.md +++ b/lib/python/README.zh-CN.md @@ -1,6 +1,6 @@ # Cat Client for Python -pycat 同时支持 python2 (>=2.6) 和 python3 (>=3.5) +`pycat` 同时支持 python2 (>=2.6) 和 python3 (>=3.5) ## 安装 @@ -18,22 +18,9 @@ python setup.py install ## 初始化 -首先你需要创建 `/data/appdatas/cat` 目录，并拥有读写权限 (0644)。建议同时创建 `/data/applogs/cat` 目录用于存放日志，这将在排查问题时非常有用。 +一些[准备工作](../_/preparations.zh-CN.md)需要在初始化 `pycat` 之前完成。 -然后创建一个配置文件 `/data/appdatas/cat/client.xml`，内容如下： - -```xml - - - - - - -``` - -在复制粘贴文件内容后，不要忘记把 `` 改成你自己的哦！ - -所有准备工作都完成之后，初始化 pycat 就很容易了。 +然后你就可以通过下面的代码初始化 `pycat` 了： ```python cat.init("appkey") @@ -45,12 +32,12 @@ cat.init("appkey") 由于我们在 `ccat` 中使用 `ThreadLocal` 存储 Transaction 的栈，并用于构建消息树，同时 `pycat` 高度依赖 `ccat`。 -因此在协程模式下，如 `gevent`, `greenlet`，我们暂不提供消息树功能。 +因此在协程模式下，如 `gevent`, `greenlet`，由于同一个线程里的线程会交替执行，我们暂不提供消息树功能。 在这些情况下，你需要通过下述代码来关闭消息树功能。 ```python -cat.init("appkey", message_tree=False) +cat.init("appkey", logview=False) ``` 这样我们就会禁用 ccat 的上下文管理器，从而禁用消息树功能。 @@ -186,7 +173,7 @@ finally: 在使用 Transaction 提供的 API 时，你可能需要注意以下几点： -1. 你可以调用 `addData` 和 `addKV` 多次，他们会被 `&` 连接起来。 +1. 你可以调用 `add_data` 多次，他们会被 `&` 连接起来。 2. 同时指定 `duration` 和 `durationStart` 是没有意义的，尽管我们在样例中这样做了。 3. 不要忘记完成 transaction！否则你会得到一个毁坏的消息树以及内存泄漏！ @@ -198,14 +185,14 @@ finally: # Log a event with success status and empty data. cat.log_event("Event", "E1") -# The third parameter (status) is optional, default is "0". +# The 3rd parameter (status) is optional, default is "0". # It can be any of string value. # The event will be treated as a "problem" unless the given status == cat.CAT_CUSSESS ("0") # which will be recorded in our problem report. cat.log_event("Event", "E2", cat.CAT_ERROR) cat.log_event("Event", "E3", "failed") -# The fourth parameter (data) is optional, default is "". +# The 4th parameter (data) is optional, default is "". # It can be any of string value. cat.log_event("Event", "E4", "failed", "some debug info") ``` -- GitLab