better readme with fieldstat easy

2 files changed, 131 insertions, 131 deletions

diff --git a/fieldstat_easy.md b/fieldstat_easy.md
deleted file mode 100644
index 66b86e3..0000000
--- a/fieldstat_easy.md
+++ /dev/null
@@ -1,119 +0,0 @@
-
-# fieldstat easy
-
-## Description
-**Fieldstat easy** wraps the fieldstat to provide a simpler interface and multi-threaded support. For details, refer to [fieldstat](readme.md).
-
-Fieldstat easy support multi-threaded writing and output. The output of fieldstat easy is in json format, which can be easily parsed by other python.
-
-All the metrics in fieldstat easy are dynamic, which means that the metrics has no volume limit, and users can add any tags to the metrics as needed and at any time.
-
-## Example 
-### coding
-```
-#include "fieldstat_easy.h"
-
-const int N_THREADS = 3;
-struct fieldstat_tag global_tags[1];
-struct fieldstat_tag tmptag;
-tmptag.key = "app id";
-tmptag.type = TAG_INTEGER;
-tmptag.value_longlong = 1;
-global_tags[0] = tmptag;
-
-struct fieldstat_tag tag1 = {"direction", TAG_STRING, "incoming"};
-struct fieldstat_tag tag2 = {"direction", TAG_STRING, "outgoing"};
-
-struct fieldstat_easy *fse = fieldstat_easy_new(N_THREADS, global_tags, 1);
-int counter_id = fieldstat_easy_register_counter(fse, "incoming bytes");
-int hdr_id = fieldstat_easy_register_histogram(fse, "delay", 1, 10000, 1);
-int output_interval_seconds = 1;
-fieldstat_easy_enable_auto_output(fse, FILENAME, output_interval_seconds); // FILENAME is the same as the one you set in python.
-
-std::thread threads[N_THREADS];
-for (int thread_id = 0; thread_id < N_THREADS; thread_id++) {
-    threads[thread_id] = std::thread([fse, counter_id, hdr_id, thread_id]() {
-        while(1) {
-            fieldstat_easy_counter_incrby(fse, thread_id, counter_id, &tag1, 1, 100);
-            fieldstat_easy_counter_incrby(fse, thread_id, counter_id, &tag2, 1, 2);
-            fieldstat_easy_histogram_record(fse, thread_id, hdr_id, &tag1, 1, rand() % 10000);
-        }
-    });
-}
-sleep(1000);
-fieldstat_easy_free(fse);
-
-```
-
-### raw output
-```
-[
-    {
-        "name": "-",
-        "tags": {
-            "direction": "incoming",
-            "app id": 1
-        },
-        "fields": {
-            "bytes": 585167,
-            "delay": "HISTEwAAAUYAAAAAAAAAAQAAAAAAAAABAAAAAAAAJxA/8AAAAAAAAJABbHh8ZnZccHp2gAFUaIABdmaCAXx0YoQBdGyMAXhsggF6eowBggGCAfAB6AGWAvQB9AHyAdYB4AHoAeoB3gHEAcwBrgKKAtgB5gPQA7QD5APIA8wD4gO+A+YDxAO2A8ADwgPAA8QD5gOEB5wHhAfQB9gHvAfwB6QHuAe6B/QGxAecB7QHqAfeB/INsA+ODtIO2g2QDo4OrA7WDtYN/A7qDcQN9A6WDpYP3h7OHqwdnhyeHYge7B2EHaQesB7QHaId+B2MHaYejh3gOvI6jDuyOqI7qjqMOpo7mDqeOvI6iDuiOrQ7lDqKOpZztHDuc+x2onbkdoR0hnSAdZR03naWdK5z6nX8dZh1vugBvOcBqusB2OsBkOgB+OkB3OoBxOoB9ukB9uwBqOwBnuoB8OkBxusBsugB7OoBptMD5tEDpNUDivcBAAAAAAAAAA==",
-            "bytes_delta": 31689,
-            "delay_delta": "HISTEwAAAOgAAAAAAAAAAQAAAAAAAAABAAAAAAAAJxA/8AAAAAAAAAQEAQYKCgIEAggECgYECgQGBAYIDgoMAgQBCgQECAICEAIUDBIUEg4ECAwKDBQGFCAWFBYYFBIcIhogGhYiEhg6JDQ4NDw+GjouOC4oMC4ufGZidGhaYGBMXGJYYk5eXugBrAHYAdQB7AHeAcoB3AHAAfIBwAHYAdgBwgG+Ae4BzgOqA6QDsAOUA64DrAOMA4gD5gL4ArAD4AKYA44DtAOCBvgFkgaiBrIG1AasBswG0ga2BqAGpAaKBrYGpAamBvAM3AzWDI4NgA2mDKIMkg2uDIANiA3gDMQMlA2ODfIM2hikGf4XjA0AAAAAAAAA"
-        },
-        "timestamp_ms": 5507527913,
-        "timestamp_ms_delta": 1002
-    },
-    {
-        "name": "-",
-        "tags": {
-            "direction": "outgoing",
-            "app id": 1
-        },
-        "fields": {
-            "bytes": 5857,
-            "delay": "HISTEwAAAUYAAAAAAAAAAQAAAAAAAAABAAAAAAAAJxA/8AAAAAAAAJABbHh8ZnZccHp2gAFUaIABdmaCAXx0YoQBdGyMAXhsggF6eowBggGCAfAB6AGWAvQB9AHyAdYB4AHoAeoB3gHEAcwBrgKKAtgB5gPQA7QD5APIA8wD4gO+A+YDxAO2A8ADwgPAA8QD5gOEB5wHhAfQB9gHvAfwB6QHuAe6B/QGxAecB7QHqAfeB/INsA+ODtIO2g2QDo4OrA7WDtYN/A7qDcQN9A6WDpYP3h7OHqwdnhyeHYge7B2EHaQesB7QHaId+B2MHaYejh3gOvI6jDuyOqI7qjqMOpo7mDqeOvI6iDuiOrQ7lDqKOpZztHDuc+x2onbkdoR0hnSAdZR03naWdK5z6nX8dZh1vugBvOcBqusB2OsBkOgB+OkB3OoBxOoB9ukB9uwBqOwBnuoB8OkBxusBsugB7OoBptMD5tEDpNUDivcBAAAAAAAAAA==",
-            "bytes_delta": 31,
-            "delay_delta": "HISTEwAAAOgAAAAAAAAAAQAAAAAAAAABAAAAAAAAJxA/8AAAAAAAAAQEAQYKCgIEAggECgYECgQGBAYIDgoMAgQBCgQECAICEAIUDBIUEg4ECAwKDBQGFCAWFBYYFBIcIhogGhYiEhg6JDQ4NDw+GjouOC4oMC4ufGZidGhaYGBMXGJYYk5eXugBrAHYAdQB7AHeAcoB3AHAAfIBwAHYAdgBwgG+Ae4BzgOqA6QDsAOUA64DrAOMA4gD5gL4ArAD4AKYA44DtAOCBvgFkgaiBrIG1AasBswG0ga2BqAGpAaKBrYGpAamBvAM3AzWDI4NgA2mDKIMkg2uDIANiA3gDMQMlA2ODfIM2hikGf4XjA0AAAAAAAAA"
-        },
-        "timestamp_ms": 5507527913,
-        "timestamp_ms_delta": 1002
-    }****
-]
-```
-
-Another way to output is to use the `fieldstat_easy_output` function, the output of which is a c-string in json format. The output format is *different* from the above. `fieldstat_easy_output` is stateless, and will only output accumulated data.
-
-Explaination of the output format:
- - `name` Always `-`. Just omit it.
- - `tags` The tags of the fields. It contains the global tags and the tags of the metrics. The tags of the metrics are the same as the arguments of `fieldstat_easy_counter_incrby` and `fieldstat_easy_histogram_record`.
- - `fields` The fields of the metrics. The fields of the counter (`bytes` in example) are of integer type, and the fields of the histogram (`delay` in example) are of string type(in base64 format). Thoses with key ending with `_delta` are metrics recording the values of the current output interval. While the value of the fields is the value of all time.
-
-The output histogram is a base64 encoded string. You can decode it with the following command.
-
-```
-// C language
-#include "hdr_histogram.h"
-#include "metrics/histogram_encoder.h"
-
-char *buf = "HISTEwAAAUYAAAAAAAAAAQAAAAAAAAABAAAAAAAAJxA/8AAAAAAAAJABbHh8ZnZccHp2gAFUaIABdmaCAXx0YoQBdGyMAXhsggF6eowBggGCAfAB6AGWAvQB9AHyAdYB4AHoAeoB3gHEAcwBrgKKAtgB5gPQA7QD5APIA8wD4gO+A+YDxAO2A8ADwgPAA8QD5gOEB5wHhAfQB9gHvAfwB6QHuAe6B/QGxAecB7QHqAfeB/INsA+ODtIO2g2QDo4OrA7WDtYN/A7qDcQN9A6WDpYP3h7OHqwdnhyeHYge7B2EHaQesB7QHaId+B2MHaYejh3gOvI6jDuyOqI7qjqMOpo7mDqeOvI6iDuiOrQ7lDqKOpZztHDuc+x2onbkdoR0hnSAdZR03naWdK5z6nX8dZh1vugBvOcBqusB2OsBkOgB+OkB3OoBxOoB9ukB9uwBqOwBnuoB8OkBxusBsugB7OoBptMD5tEDpNUDivcBAAAAAAAAAA=="
-
-struct hdr_histogram *hdr = histogram_decode_from_b64(buf, strlen(buf));
-(void)hdr_percentiles_print(hdr, stdout, 5, 1.0, CLASSIC);
-hdr_close(hdr);
-```
-
-```
-# python language
-from fieldstat_exporter import FieldstatAPI
-
-c_hist  = FieldstatAPI.libfieldstat.fieldstat_histogram_base64_decode(value.encode('utf-8'))
-sum_value = FieldstatAPI.libfieldstat.fieldstat_histogram_value_sum(c_hist)
-FieldstatAPI.libfieldstat.fieldstat_histogram_free(c_hist) # need to free memory, because it's a C binding
-```
-
-### prometheus 
-
-
-### output to file
-
-
diff --git a/readme.md b/readme.md
index 88e0e33..c7c2d90 100644
--- a/readme.md
+++ b/readme.md
@@ -1,4 +1,4 @@
-#Fieldstat 4.0 
+# Fieldstat 4.0 
 
 ## design 
 Field Stat is a library for outputting and statistics of running states. Compared to the previous version, fieldstat3.0, this version provides support for new functionalities. The following are the concepts used in this program:
@@ -8,8 +8,9 @@ Field Stat is a library for outputting and statistics of running states. Compare
 - Cell: A cube is composed of multiple cells. A cell is a data set tagged with specific tags.
 - Metric: Each metric corresponds to a column of data in the database. Currently, there are three types of metric statistics: counter, Hyper Log Log, and Histogram.
 
-Compared to version 3.0, version 4.0 introduces the concepts of cube and cell. Cell registration is dynamic, allowing for real-time statistics on sessions. The concept of field has been removed (a combination of tag information and metric)。In version 4.0, tags and metrics are managed independently. This change simplifies the interface usage and improves the speed of batch statistics for the same tag.
-Version 4.0 no longer supports multithreading. In version 3.0, the metric of type "counter" could be shared and operated on by multiple threads. However, in version 4.0, each instance is written by only one thread. The fieldstat version 4.0 provides support for distributed statistics through methods like serialize and merge. It is the responsibility of the caller to aggregate statistics from different instances.
+Compared to version 3.0, version 4.0 introduces the concepts of cube. The concept of field has been removed (a combination of tag information and metric)。In version 4.0, tags and metrics are managed independently and dynamically. This change simplifies the interface usage and improves the speed of batch statistics for the same tag. Cube is a collection of metrics for the same purpose, and is also the unit of metric management. 
+
+Version 4.0 no longer supports multithreading. In version 3.0, the metric of type "counter" could be shared and operated on by multiple threads. However, in version 4.0, each instance is written by only one thread. The fieldstat version 4.0 provides support for distributed statistics through methods like serialize and merge. It is the responsibility of the caller to aggregate statistics from different instances. For simplified multi-threaded support, refer to [fieldstat easy](#Fieldstat-easy).
 
 ### sampling mode
 
@@ -30,6 +31,9 @@ Outputs the distribution of numerical values for events, such as latency or file
 Uses statistical techniques to estimate the number of elements in a set that contains a large number of values. For example, it can be used to estimate the number of unique client IP addresses in a set of network flows.
 
 ## Usage
+### installation 
+Download fieldstat4 rpm from https://repo.geedge.net/pulp/content/ and install rpm package.
+
 ### Statistic
 ```
 #include "fieldstat.h"
@@ -189,27 +193,25 @@ Merging Heavy Keeper is slower the coping it, it is why the execution time is un
 #### export a cell
 I add a instance with 100 cubes, on each of which I register 10 metrics. The max cell number of each cube is 1000, and call the metric operation on every added cell. So there are 100 * 10 * 1000 cells in total. After exporting the instance, calculate the average time spent on each cells.
 
-## Fieldstat exporter
+
+# Fieldstat exporter
 Fieldstat exporter provides exporter functions for fieldstat4, including prometheus exporter and local exporter. 
 
-### prometheus exporter
+## prometheus exporter
 The prometheus exporter reads the fieldstat4 json file and enables the prometheus endpoint. The default port is 8080.
 
-### local exporter
+## local exporter
 The local exporter reads the fieldstat4 json file and outputs it to the screen.
 
-### Installation and Usage
-Download fieldstat4 rpm from https://repo.geedge.net/pulp/content/ and  install rpm package.
-
 
-#### List of rpm files
+### List of rpm files
     ...
     |-- bin
         |-- fieldstat_exporter
     |-- lib
         |-- ibfieldstat4.a
         |-- libfieldstat4.so
-#### Service configuration
+### Service configuration
 The following is the prometheus exporter systemd service example file.
 ```systemd
 [Unit]
@@ -227,7 +229,7 @@ PrivateTmp=True
 [Install]
 WantedBy=multi-user.target
 ```
-### Command Line
+## Command Line
 Fieldstat exporter includes prometheus including prometheus and local subcommands.
 ```txt
 [root@localhost bin]# ./fieldstat_exporter --help
@@ -321,3 +323,120 @@ args|default value
 --display-hist|False
 --display-counter|False
 -m, --match-tags|""
+
+# fieldstat easy
+
+## Description
+**Fieldstat easy** wraps the fieldstat to provide a simpler interface and multi-threaded support. For details refer to [fieldstat](#Fieldstat-4.0). For the usage of prometheus exporter and file exporter, refer to [fieldstat exporter](#Fieldstat-exporter).
+
+Fieldstat easy support multi-threaded writing and output. The output of fieldstat easy is in json format, which can be easily parsed by other python.
+
+All the metrics in fieldstat easy are dynamic, which means that the metrics has no volume limit, and users can add any tags to the metrics as needed and at any time. Tags, which denote the attributes of values, can be viewed as the keys to the item in table.
+
+## Example 
+### coding
+```
+#include "fieldstat_easy.h"
+
+const int N_THREADS = 3;
+struct fieldstat_tag global_tags[1];
+struct fieldstat_tag tmptag;
+tmptag.key = "app id";
+tmptag.type = TAG_INTEGER;
+tmptag.value_longlong = 1;
+global_tags[0] = tmptag;
+
+struct fieldstat_tag tag1 = {"direction", TAG_STRING, "incoming"};
+struct fieldstat_tag tag2 = {"direction", TAG_STRING, "outgoing"};
+
+struct fieldstat_easy *fse = fieldstat_easy_new(N_THREADS, global_tags, 1);
+int counter_id = fieldstat_easy_register_counter(fse, "incoming bytes");
+int hdr_id = fieldstat_easy_register_histogram(fse, 
+                                               "delay", 
+                                               1,      // min trackable value, no less than 1. The value less than this value will still be recorded, with an unpromising precision.
+                                               10000, // max trackable value, the value larger than this value will be recorded as the max value.
+                                               1); // precision, value less than 10 ^ precision will be recorded keeping exact precision. The larger recorded value is, the less precise of its count is.
+int output_interval_seconds = 1;
+fieldstat_easy_enable_auto_output(fse, FILENAME, output_interval_seconds); // FILENAME is the same as the one you set in python.
+
+std::thread threads[N_THREADS];
+for (int thread_id = 0; thread_id < N_THREADS; thread_id++) {
+    threads[thread_id] = std::thread([fse, counter_id, hdr_id, thread_id]() {
+        while(1) {
+            fieldstat_easy_counter_incrby(fse, thread_id, counter_id, &tag1, 1, 100);
+            fieldstat_easy_counter_incrby(fse, thread_id, counter_id, &tag2, 1, 2);
+            fieldstat_easy_histogram_record(fse, thread_id, hdr_id, &tag1, 1, rand() % 10000);
+        }
+    });
+}
+sleep(1000);
+fieldstat_easy_free(fse);
+
+```
+
+### raw output
+```
+[
+    {
+        "name": "-",
+        "tags": {
+            "direction": "incoming",
+            "app id": 1
+        },
+        "fields": {
+            "bytes": 585167,
+            "delay": "HISTEwAAAUYAAAAAAAAAAQAAAAAAAAABAAAAAAAAJxA/8AAAAAAAAJABbHh8ZnZccHp2gAFUaIABdmaCAXx0YoQBdGyMAXhsggF6eowBggGCAfAB6AGWAvQB9AHyAdYB4AHoAeoB3gHEAcwBrgKKAtgB5gPQA7QD5APIA8wD4gO+A+YDxAO2A8ADwgPAA8QD5gOEB5wHhAfQB9gHvAfwB6QHuAe6B/QGxAecB7QHqAfeB/INsA+ODtIO2g2QDo4OrA7WDtYN/A7qDcQN9A6WDpYP3h7OHqwdnhyeHYge7B2EHaQesB7QHaId+B2MHaYejh3gOvI6jDuyOqI7qjqMOpo7mDqeOvI6iDuiOrQ7lDqKOpZztHDuc+x2onbkdoR0hnSAdZR03naWdK5z6nX8dZh1vugBvOcBqusB2OsBkOgB+OkB3OoBxOoB9ukB9uwBqOwBnuoB8OkBxusBsugB7OoBptMD5tEDpNUDivcBAAAAAAAAAA==",
+            "bytes_delta": 31689,
+            "delay_delta": "HISTEwAAAOgAAAAAAAAAAQAAAAAAAAABAAAAAAAAJxA/8AAAAAAAAAQEAQYKCgIEAggECgYECgQGBAYIDgoMAgQBCgQECAICEAIUDBIUEg4ECAwKDBQGFCAWFBYYFBIcIhogGhYiEhg6JDQ4NDw+GjouOC4oMC4ufGZidGhaYGBMXGJYYk5eXugBrAHYAdQB7AHeAcoB3AHAAfIBwAHYAdgBwgG+Ae4BzgOqA6QDsAOUA64DrAOMA4gD5gL4ArAD4AKYA44DtAOCBvgFkgaiBrIG1AasBswG0ga2BqAGpAaKBrYGpAamBvAM3AzWDI4NgA2mDKIMkg2uDIANiA3gDMQMlA2ODfIM2hikGf4XjA0AAAAAAAAA"
+        },
+        "timestamp_ms": 5507527913,
+        "timestamp_ms_delta": 1002
+    },
+    {
+        "name": "-",
+        "tags": {
+            "direction": "outgoing",
+            "app id": 1
+        },
+        "fields": {
+            "bytes": 5857,
+            "delay": "HISTEwAAAUYAAAAAAAAAAQAAAAAAAAABAAAAAAAAJxA/8AAAAAAAAJABbHh8ZnZccHp2gAFUaIABdmaCAXx0YoQBdGyMAXhsggF6eowBggGCAfAB6AGWAvQB9AHyAdYB4AHoAeoB3gHEAcwBrgKKAtgB5gPQA7QD5APIA8wD4gO+A+YDxAO2A8ADwgPAA8QD5gOEB5wHhAfQB9gHvAfwB6QHuAe6B/QGxAecB7QHqAfeB/INsA+ODtIO2g2QDo4OrA7WDtYN/A7qDcQN9A6WDpYP3h7OHqwdnhyeHYge7B2EHaQesB7QHaId+B2MHaYejh3gOvI6jDuyOqI7qjqMOpo7mDqeOvI6iDuiOrQ7lDqKOpZztHDuc+x2onbkdoR0hnSAdZR03naWdK5z6nX8dZh1vugBvOcBqusB2OsBkOgB+OkB3OoBxOoB9ukB9uwBqOwBnuoB8OkBxusBsugB7OoBptMD5tEDpNUDivcBAAAAAAAAAA==",
+            "bytes_delta": 31,
+        },
+        "timestamp_ms": 5507527913,
+        "timestamp_ms_delta": 1002
+    }****
+]
+```
+
+Another way to output is to use the `fieldstat_easy_output` function, the output of which is a c-string in json format. The output format is *different* from the above. `fieldstat_easy_output` is stateless, and will only output accumulated data.
+
+Explaination of the output format:
+ - `name` Always `-`. Just omit it.
+ - `tags` The tags of the fields. It contains the global tags and the tags of the metrics. The tags of the metrics are the same as the arguments of `fieldstat_easy_counter_incrby` and `fieldstat_easy_histogram_record`.
+ - `fields` The fields of the metrics. The fields of the counter (`bytes` in example) are of integer type, and the fields of the histogram (`delay` in example) are of string type(in base64 format). Those with key ending with `_delta` are metrics recording the values of the current output interval, while the value of the fields is the value of all time. For example, when the metric is to record packet sum, time interval set to 1, the field "sum_delta" records speed.
+
+The output histogram is a base64 encoded string. For the formatted output, use python command lines.
+
+Or you can decode it with the following code snippet:
+
+```
+// C language
+#include "hdr_histogram.h"
+#include "metrics/histogram_encoder.h"
+
+char *buf = "HISTEwAAAUYAAAAAAAAAAQAAAAAAAAABAAAAAAAAJxA/8AAAAAAAAJABbHh8ZnZccHp2gAFUaIABdmaCAXx0YoQBdGyMAXhsggF6eowBggGCAfAB6AGWAvQB9AHyAdYB4AHoAeoB3gHEAcwBrgKKAtgB5gPQA7QD5APIA8wD4gO+A+YDxAO2A8ADwgPAA8QD5gOEB5wHhAfQB9gHvAfwB6QHuAe6B/QGxAecB7QHqAfeB/INsA+ODtIO2g2QDo4OrA7WDtYN/A7qDcQN9A6WDpYP3h7OHqwdnhyeHYge7B2EHaQesB7QHaId+B2MHaYejh3gOvI6jDuyOqI7qjqMOpo7mDqeOvI6iDuiOrQ7lDqKOpZztHDuc+x2onbkdoR0hnSAdZR03naWdK5z6nX8dZh1vugBvOcBqusB2OsBkOgB+OkB3OoBxOoB9ukB9uwBqOwBnuoB8OkBxusBsugB7OoBptMD5tEDpNUDivcBAAAAAAAAAA=="
+
+struct hdr_histogram *hdr = histogram_decode_from_b64(buf, strlen(buf));
+(void)hdr_percentiles_print(hdr, stdout, 5, 1.0, CLASSIC);
+hdr_close(hdr);
+```
+
+```
+# python language
+from fieldstat_exporter import FieldstatAPI
+
+c_hist  = FieldstatAPI.libfieldstat.fieldstat_histogram_base64_decode(buf.encode('utf-8'))
+sum_value = FieldstatAPI.libfieldstat.fieldstat_histogram_value_sum(c_hist)
+FieldstatAPI.libfieldstat.fieldstat_histogram_free(c_hist) # need to free memory, because it's a C binding
+```