Skip to content

Latest commit

 

History

History

point

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
gogopb
gogopb
 
 
pb
pb
 
 
test
test
 
 
Makefile
Makefile
 
 
README.md
README.md
 
 
any.go
any.go
 
 
any_test.go
any_test.go
 
 
category.go
category.go
 
 
category_test.go
category_test.go
 
 
check.go
check.go
 
 
check_test.go
check_test.go
 
 
cloc.sh
cloc.sh
 
 
decode.go
decode.go
 
 
decode_test.go
decode_test.go
 
 
easybatch.go
easybatch.go
 
 
easybatch_test.go
easybatch_test.go
 
 
easyproto.go
easyproto.go
 
 
easyproto_test.go
easyproto_test.go
 
 
enc.go
enc.go
 
 
encode.go
encode.go
 
 
encode_test.go
encode_test.go
 
 
encode_v2.go
encode_v2.go
 
 
env.go
env.go
 
 
env_test.go
env_test.go
 
 
equal.go
equal.go
 
 
equal_test.go
equal_test.go
 
 
err.go
err.go
 
 
init.go
init.go
 
 
json.go
json.go
 
 
json_test.go
json_test.go
 
 
key.go
key.go
 
 
kvs.go
kvs.go
 
 
kvs_test.go
kvs_test.go
 
 
lp.go
lp.go
 
 
lp_test.go
lp_test.go
 
 
new_point.go
new_point.go
 
 
new_point_test.go
new_point_test.go
 
 
option.go
option.go
 
 
p8s_point.go
p8s_point.go
 
 
p8s_point_test.go
p8s_point_test.go
 
 
pb.sh
pb.sh
 
 
pbpoint_test.go
pbpoint_test.go
 
 
point.go
point.go
 
 
point.pb.go
point.pb.go
 
 
point.proto
point.proto
 
 
point_test.go
point_test.go
 
 
ptpool.go
ptpool.go
 
 
ptpool_test.go
ptpool_test.go
 
 
rand.go
rand.go
 
 
rand_deprecated.go
rand_deprecated.go
 
 
rand_test.go
rand_test.go
 
 
set.go
set.go
 
 
set_test.go
set_test.go
 
 
sort.go
sort.go
 
 
sort_test.go
sort_test.go
 
 
specs.go
specs.go
 
 
val.go
val.go
 
 
val_test.go
val_test.go
 
 

README.md

DataKit 采集的数据结构定义

Point

Point 是 DataKit 中最常用的一种数据表示形式，目前 Point 有两种表现形式：

  1. 行协议
  2. Protobuf

由于行协议表达能力有限，后面会逐渐迁移到 Protobuf，同时中心仍然长期支持行协议写入（不同的 API 版本）。除此之外，行协议和 Protobuf 之间并无实质性的差异，效率上而言（非极端情况）：

  • 编码体积上，Protobuf 和航协议相当（随机出来的数据点）
  • 编码效率上，Protobuf 在效率（X10）和内存占用（X8）上，都较行协议更好
  • 解码效率上，Protobuf 也更好（X5）

以上测试，参见 TestEncodePayloadSize/BenchmarkEncode/BenchmarkDecode。 可参考如下结果：

$ CGO_CFLAGS=-Wno-undef-prefix go test -run XXX -test.benchmem -test.v -bench BenchmarkEncode
goos: darwin
goarch: arm64
pkg: github.com/GuanceCloud/cliutils/point
BenchmarkEncode
BenchmarkEncode/encode-json
BenchmarkEncode/encode-json-10         	      97	  10421921 ns/op	 7656217 B/op	   60287 allocs/op
BenchmarkEncode/encode-lp
BenchmarkEncode/encode-lp-10           	     243	   4906325 ns/op	 8676728 B/op	   41045 allocs/op
BenchmarkEncode/v1-encode-pb
BenchmarkEncode/v1-encode-pb-10        	    2685	    431512 ns/op	 1115020 B/op	      16 allocs/op
BenchmarkEncode/v2-encode-pb-PBSize()
BenchmarkEncode/v2-encode-pb-PBSize()-10         	    2158	    549952 ns/op	      17 B/op	       0 allocs/op
BenchmarkEncode/v2-encode-pb-Size()
BenchmarkEncode/v2-encode-pb-Size()-10           	    3211	    368438 ns/op	       5 B/op	       0 allocs/op
BenchmarkEncode/v2-encode-lp
BenchmarkEncode/v2-encode-lp-10                  	     268	   4411220 ns/op	 5260352 B/op	   39069 allocs/op
PASS
ok  	github.com/GuanceCloud/cliutils/point	8.625s

v2 的 encode 效率比 v1 要慢一些（~0.80X），因为在编码过程中要实时计算 point 的大小（目的是不超过总 buffer 大小）。但如果只是错略计算大小，则比 v1 （v1 内部要动态分配内存）要快一些（~1.17X）。

Point 的约束 {#restrictions}

Point 构建函数：

pt := NewPoint(name []byte, kvs KVs, opts... Option)

由于 Point 最终需要写入后端存储，故而受到后端存储的各种限制，但原则上采集端仍然做尽量少的限制，以保证数据采集的多样性和完整性。目前 Point 限制如下（本次放开/新加的约束，粗体表示）：

  1. 概念上，仍旧区分 tag 和 field。但在底层数据结构上，它们的类型一致，都是 key-value，只是在特定的 key-value 上，会标注其是否为 tag（IsTag）。可以简单理解为 tag/field 都是 key。field 概念不再重要，在这些 key-value 对中，tag 只是更特化的一种 key-value，非 tag 的 key-value 都可以视为 field。

  2. kvs 本质上是一个数组结构，以增加顺序排列

  3. 同一个 point 中，tag 和 field 之间不允许出现同名的 key。这一限制主要用来确保 DQL 查询时字段的唯一性。如果 tag/field 中出现同名 key，后出现的 key 将不再生效。

  4. tag/field key 以及 value 目前不做协议上的限制，这一限制可以在应用层（比如 datakit/kodo）通过 Option 配置来控制

  5. tag/field key/value 的内容均有几个方面的限制：

    • tag key 和 value 中均不允许出现换行字符，如果出现，SDK 会将其替换成空格。如字符串 "abc\ndef" 会被替换成 "abc def"。该限制无法通过 Option 控制。
    • Point 可以没有任何 key（即可以没有 tag 和 field）。对于这样的 point，在上传过程中，自动忽略，但不会影响其它正常 point 的处理。
    • tag key 和 value 均不允许以反斜杠 \ 结尾，如果出现，SDK 会将其移除掉。如字符串 "abc\" 会被替换成 "abc"。该限制无法通过 Option 控制。
    • 对日志类数据（非时序数据）而言，tag/field 的 key 中不允许出现 . 字符，如果出现，SDK 会将其替换成 _，如 key "abc.def" 会被替换成 "abc_def"。该限制可以通过 Option 控制。(注：这一限制主要因后端使用 ES 作为存储所致，如果不用 ES 可以移除这一限制)
    • tag/field 个数、 各个 tag/field key/value 长度（此处特指字符串长度）均可以通过 Option 设置。
    • 某些特定的数据类型（T/L/R/O/...），可以禁用某些 key（这里的 key 是带类型的，比如对象上不允许出现 key 为 class 的字段，一旦出现这些 key，最终的 Point 数据中，这些 key 将被自动移除掉。
      • 所有在构建点的过程中，如果出现自动调整（比如移除某些字段），均会在最终的 point 结构中出现对应的 warning 信息（通过 point.Pretty() 可以查看）

  6. 构建 point 过程中出现的 warning/debug 信息，如果用 PB 结构上报，会一并上传到中心（kodo），中心在写入存储的时候，可以不用理会这些信息，主要是调试用

  7. tag value 目前只支持 string 值

  8. field value 目前支持:

    • int8/int16/int32/int64 表示有符号整数
    • uint8/uint16/uint32/uint64 表示无符号整数
    • float64：浮点数，暂无限制
    • bool：暂无限制
    • []byte：字节流，可以存放二进制数据
    • string：暂无限制
    • []any：数组类型，数组元素必须是基础类型（int/uint/float/string/bool），且数组内类型一致。