用Markdown格式重写readme。

3 files changed, 160 insertions, 30 deletions

diff --git a/inc/field_stat2.h b/inc/field_stat2.h
index 90f3a76..e9af975 100644
--- a/inc/field_stat2.h
+++ b/inc/field_stat2.h
@@ -47,7 +47,7 @@ enum FS_option
 	APP_NAME,			//VALUE is a const char*, MUST end with '\0', SIZE= strlen(string+'\0')+1. DEFAULT is "?".
 	STATS_SERVER_IP, 	//VALUE is a const char*, MUST end with '\0', SIZE= strlen(string+'\0')+1. No DEFAULT.
 	STATS_SERVER_PORT, 	//VALUE is a unsigned short or a signed int, host order, SIZE= sizeof(unsigned short) or sizeof(int). No DEFAULT.
-	STATS_FORMAT,		//VALUE is an interger, SIZE=sizeof(int), DEFAULT:1.
+	STATS_FORMAT,		//VALUE is enum stats_output_format, STATSD or INFLUX_LINE, SIZE=sizeof(int), DEFAULT:STATSD.
 	MAX_STAT_FIELD_NUM,		//VALUE is an interger, SIZE=sizeof(int), DEFAULT:1024.
 	HISTOGRAM_GLOBAL_BINS	//VALUE is a const char*, define a histogram bins for default field, SIZE = strlen(string+'\0')+1. DEFAULT: "0.5,0.8,0.9,0.95,0.99“.
 };
diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..99a9ce7
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,159 @@
+# Field Stat 2简介
+
+Field Stat是一个运行状态输出与统计库。
+
+## 本地显示风格(style)
+
+​	输出到屏幕或文件，可选择输出瞬时值 `FS_CALC_SPEED`或累计值`FS_CALC_CURRENT`。
+
+### 域（Field ）
+
+​	`FS_STYLE_FIELD` 同时输出累计值(sum)和瞬时值(speed/s，1秒内的变化值)
+
+```
+	  field_00	  field_01
+sum	         0	    184300
+speed/s	     0	     92150
+```
+
+​	函数接口 
+
+```c
+field_ids[i]=FS_register(handle, FS_STYLE_FIELD, FS_CALC_CURRENT, "field_01");
+```
+
+### 状态（Status）
+
+​	`FS_STYLE_STATUS` 输出累计值或瞬时值
+
+```c
+status_00:  100  status_01: 10
+```
+
+​	函数接口 
+
+```
+status_ids[i]=FS_register(handle, FS_STYLE_STATUS, FS_CALC_CURRENT, "status_01");
+```
+
+### 表格 （Line&Column）
+
+ `FS_STYLE_LINE`和`FS_STYLE_COLUMN `输出累计值或瞬时值。
+
+```
+___________________________________________________________________________________
+			 column_0	  column_1	  column_3	  column_4	  column_5	      c0/c1
+line_0       2.76e+04	  5.53e+04	  1.11e+05	  1.38e+05	  1.66e+05	   5.00e-01	
+line_1       2.76e+04	  5.53e+04	  1.11e+05	  1.38e+05	  1.66e+05	   5.00e-01	
+line_2       2.76e+04	  5.53e+04	  1.11e+05	  1.38e+05	  1.66e+05	   5.00e-01	
+line_3       2.76e+04	  5.53e+04	  1.11e+05	  1.38e+05	  1.66e+05	   5.00e-01	
+line_4       2.76e+04	  5.53e+04	  1.11e+05	  1.38e+05	  1.66e+05	   5.00e-01	
+line_5       2.76e+04	  5.53e+04	  1.11e+05	  1.38e+05	  1.66e+05	   5.00e-01	
+line_6       2.76e+04	  5.53e+04	  1.11e+05	  1.38e+05	  1.66e+05	   5.00e-01
+```
+
+​	函数接口 API
+
+```
+line_ids[i]=FS_register(handle, FS_STYLE_LINE, FS_CALC_CURRENT, "line_0");
+column_ids[i]=FS_register(handle, FS_STYLE_COLUMN, FS_CALC_SPEED,"column_0");
+```
+
+
+
+### 分布图 (Histogram)
+
+​	`FS_STYLE_HISTOGRAM` 输出事件的数值分布，如延迟，文件长度等。
+
+```
+histogram	 50%   80%   95%   MAX   MIN    AVG   STDDEV   CNT
+ssl_up(ms)	   0     0     0     0     0    0.00    0.00     0
+peek_sni(ms)   0     0     0     0     0    0.00    0.00     0
+ssl_down(ms)   0     0     0     0     0    0.00    0.00     0
+ask_kyr(ms)	   0     0     0     0     0    0.00    0.00     0
+```
+
+​	默认输出 50%，80.00%，90%，95%和99%的比例， 可以通过 `FS_set_para` 函数的`HISTOGRAM_GLOBAL_BINS`选项修改。
+
+​	缩写定义：
+
+- MAX 最大值
+
+- MIN 最小值
+
+- AVG 平均值
+
+- STDDEV 标准差
+
+- CNT 计数
+
+  函数接口 
+
+```
+fs_metric_sql_exec=FS_register_histogram(g_info.fs_handle,	//Field Stat句柄
+										FS_CALC_CURRENT,	//输出累计值或瞬时值
+                                        "sql_exec(us)",		//统计项名称，字符串
+                                        1,					//可追踪的最小值
+                                        1000000,			//可追踪的最大值
+                                        2);					//精度，即小数点后几位，范围1~4
+```
+
+
+
+## 远程输出
+
+​	可以输出为[StatsD](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/statsd)格式或 [InfluxDB Inline Protocol](https://docs.influxdata.com/influxdb/v1.7/write_protocols/line_protocol_tutorial/)格式，通过UDP协议发送给聚合器，如telegraf。	聚合器接收并聚合后，写入时序数据库，如InfluxDB，然后通过图形界面展示，如Grafana。
+
+StatsD 输出counter和histogram两种metric，metric name命名遵循
+
+- Field和Status： ` [APP_NAME]field_name:value` 
+- Column和Line：`[APP_NAME]line#column:value`
+
+Influx Line命名规则为
+
+```
+measurement, tag, key1=value1, key2=value2
+line，app_name=APPNAME column1=value,column2=value
+```
+
+​	可以通过 `FS_set_para`函数 的`STATS_SERVER_IP ` 、`STATS_SERVER_PORT`选项，设置服务器的IP和端口。通过`STATS_FORMAT`选项设置输出格式为`FS_OUTPUT_STATSD`或`FS_OUTPUT_INFLUX_LINE`。
+
+​	服务端搭建流程参见[《【StatsD监控】基于Telegraf+InfluxDB+grafana展示（非Docker方案）》](https://blog.csdn.net/littlefang/article/details/78473161)。聚合Histogram建议修改telegraf.conf的以下配置项：
+
+`percentiles = [50, 60, 80, 90, 95, 99]`
+
+## 使用建议
+
+### 命名建议
+
+​	在命名时，遵循按照以下规则：
+
+1. 带上单位，如bytes或kb，微秒us或毫秒ms等。
+2. 除若干单词首字母组成的缩写外，不要大写。如Kernel Network Interface 可以缩写为KNI，packet缩写为pkt，而不是PKT
+3.  一般不要超过10个字节，不然本地刷新不美观。
+   - htable->htab, read->rd，write->wr，send ->tx，receive->rx
+   - send packets，可缩写为tx_pkts，send bytes可缩写为tx_bytes
+
+### 显示字段数量
+
+​	Status和Field每行固定展示8个统计值。Column和Histogram取决于注册数量，建议Column一般不超过8个，Histogram的bins不超过5个。
+
+​	通过`FS_set_para`函数的 `ID_INVISBLE`不显示的字段，可以节约屏幕空间；通过 `FS_register_ratio`计算两个统计字段的比值。
+
+### 本地结果查看
+
+​	在shell执行`watch -d cat 日志文件`，观察实时的输出结果。
+
+### 记录事件耗时
+
+​	应使用clock_gettime函数获得事件的耗时，[永远不要用gettimeofday计算时间](https://blog.habets.se/2010/09/gettimeofday-should-never-be-used-to-measure-time.html)。
+
+​	也可使用field_stat2.h中提供的简单封装。
+
+```
+struct timespec start;
+record_time_start(&start);
+//do something
+long eplapses=record_time_elapse_us(&start);
+```
+
diff --git a/readme.txt b/readme.txt
deleted file mode 100644
index 7ffae39..0000000
--- a/readme.txt
+++ /dev/null
@@ -1,29 +0,0 @@
-ʹ�÷����μ�test/fs2_test.cpp��
-����ִ��"watch -d cat ��־�ļ�"����۲���������
-============================================================Tue Jun 19 10:02:10 2018============================================================
-status_00: 0         	status_01: 10        	status_02: 20        	status_03: 30        	rt_reg_00: 0         	rt_reg_01: 920500    	
-rt_reg_02: 1840000   	rt_reg_03: 2758500   	rt_reg_04: 3676000   	rt_reg_05: 4592500   	rt_reg_06: 5508000   	rt_reg_07: 6422500   	
-rt_reg_08: 7336000   	rt_reg_09: 8248500   	rt_reg_10: 9160000   	rt_reg_11: 10070500  	rt_reg_12: 10980000  	rt_reg_13: 11888500  	
-rt_reg_14: 12796000  	rt_reg_15: 13702500  	rt_reg_16: 14608000  	rt_reg_17: 15512500  	rt_reg_18: 16416000  	rt_reg_19: 17318500  	
-rt_reg_20: 18220000  	rt_reg_21: 19120500  	rt_reg_22: 20020000  	rt_reg_23: 20918500  	rt_reg_24: 21816000  	rt_reg_25: 22712500  	
-rt_reg_26: 23608000  	rt_reg_27: 24502500  	rt_reg_28: 25396000  	rt_reg_29: 26288500  	rt_reg_30: 27180000  	rt_reg_31: 28070500  	
-________________________________________________________________________________________________________________________________________________
-	  field_00	  field_01	  field_02	  field_03	  field_04	  field_05	  field_06	  field_07	
-sum	         0	    184300	    368600	    552900	    737200	    921500	   1105800	   1290100	
-speed/s	         0	     92150	    184300	    276450	    368600	    460750	    552900	    645050	
-	  field_08	
-sum	   1474400	
-speed/s	    737200	
-________________________________________________________________________________________________________________________________________________
-			  column_0	  column_1	  column_3	  column_4	  column_5	  column_6	  column_7	     c0/c1
-line_0              	  2.76e+04	  5.53e+04	  1.11e+05	  1.38e+05	  1.66e+05	  1.94e+05	  2.21e+05	  5.00e-01	
-line_1              	  2.76e+04	  5.53e+04	  1.11e+05	  1.38e+05	  1.66e+05	  1.94e+05	  2.21e+05	  5.00e-01	
-line_2              	  2.76e+04	  5.53e+04	  1.11e+05	  1.38e+05	  1.66e+05	  1.94e+05	  2.21e+05	  5.00e-01	
-line_3              	  2.76e+04	  5.53e+04	  1.11e+05	  1.38e+05	  1.66e+05	  1.94e+05	  2.21e+05	  5.00e-01	
-line_4              	  2.76e+04	  5.53e+04	  1.11e+05	  1.38e+05	  1.66e+05	  1.94e+05	  2.21e+05	  5.00e-01	
-line_5              	  2.76e+04	  5.53e+04	  1.11e+05	  1.38e+05	  1.66e+05	  1.94e+05	  2.21e+05	  5.00e-01	
-line_6              	  2.76e+04	  5.53e+04	  1.11e+05	  1.38e+05	  1.66e+05	  1.94e+05	  2.21e+05	  5.00e-01
-
-����fieldstat����ʾ���������һ�㲻Ҫ����10���ֽڣ���Ȼ����ˢ�²����ۡ�����дʱ�����鰴�����¹���
-1. field�����������ɵ�������ĸ��ɵ���д�⣬��Ҫ��д����Kernel Network Interface ������дΪKNI��packet��дΪpkt��������PKT
-2. htable->htab, read->rd��write->wr��send ->tx��receive->rx����send packets������дΪtx_pkts��send bytes����дΪtx_bytes
\ No newline at end of file