各种其它工具使用¶
DataKit 内置很多不同的小工具，便于大家日常使用。可通过如下命令来查看 DataKit 的命令行帮助：
注意：因不同平台的差异，具体帮助内容会有差别。
如果要查看具体某个命令如何使用（比如 dql），可以用如下命令：
$ datakit dql --help
DQL used to query data. If no option specified, query interactively.
Usage:
datakit dql [flags]
Flags:
--auto-json pretty output string if field/tag value is JSON
--csv string Specify the directory
-F, --force overwrite csv if file exists
-h, --help help for dql
-H, --host string specify datakit host to query
-J, --json output in JSON format
--log string log path (default "/dev/null")
-R, --run string run single DQL
-T, --token string run query for specific token(workspace)
-V, --verbose verbosity mode
DataKit 调试命令¶
调试黑名单¶
为了调试某条数据是否会被中心配置的黑名单过滤，我们可以用如下命令：
$ datakit debug --filter=/usr/local/datakit/data/.pull --data=/path/to/lineproto.data
Dropped
ddtrace,http_url=/webproxy/api/online_status,service=web_front f1=1i 1691755988000000000
By 7th rule(cost 1.017708ms) from category "tracing":
{ service = 'web_front' and ( http_url in [ '/webproxy/api/online_status' ] )}
PS > datakit.exe debug --filter 'C:\Program Files\datakit\data\.pull' --data '\path\to\lineproto.data'
Dropped
ddtrace,http_url=/webproxy/api/online_status,service=web_front f1=1i 1691755988000000000
By 7th rule(cost 1.017708ms) from category "tracing":
{ service = 'web_front' and ( http_url in [ '/webproxy/api/online_status' ] )}
此处输出表明，文件 lineproto.data 中的这条数据，被位于 .pull 文件中 tracing 所在分类的第 7 条（从 1 开始计数）规则匹配。一旦匹配，则该条数据将被丢弃。
使用 glob 规则获取文件路径¶
在日志采集中，支持以 glob 规则配置日志路径。
通过使用 DataKit 调试 glob 规则。需要提供一个配置文件，该文件的每一行都是一个 glob 语句。
配置文件示例如下：
完整命令示例如下：
$ datakit debug --glob-conf glob-config
============= glob paths ============
/tmp/log-test/*.log
/tmp/log-test/**/*.log
========== found the files ==========
/tmp/log-test/1.log
/tmp/log-test/logfwd.log
/tmp/log-test/123/1.log
/tmp/log-test/123/2.log
正则表达式匹配文本¶
在日志采集中，支持配置 正则表达式实现多行日志采集。
通过使用 DataKit 调试正则表达式规则。需要提供一个配置文件，该文件的第一行是正则表达式，剩余内容是被匹配的文本（可以是多行）。
配置文件示例如下：
$ cat regex-config
^\d{4}-\d{2}-\d{2}
2020-10-23 06:41:56,688 INFO demo.py 1.0
2020-10-23 06:54:20,164 ERROR /usr/local/lib/python3.6/dist-packages/flask/app.py Exception on /0 [GET]
Traceback (most recent call last):
File "/usr/local/lib/python3.6/dist-packages/flask/app.py", line 2447, in wsgi_app
response = self.full_dispatch_request()
ZeroDivisionError: division by zero
2020-10-23 06:41:56,688 INFO demo.py 5.0
完整命令示例如下：
$ datakit debug --regex-conf regex-config
============= regex rule ============
^\d{4}-\d{2}-\d{2}
========== matching results ==========
Ok: 2020-10-23 06:41:56,688 INFO demo.py 1.0
Ok: 2020-10-23 06:54:20,164 ERROR /usr/local/lib/python3.6/dist-packages/flask/app.py Exception on /0 [GET]
Fail: Traceback (most recent call last):
Fail: File "/usr/local/lib/python3.6/dist-packages/flask/app.py", line 2447, in wsgi_app
Fail: response = self.full_dispatch_request()
Fail: ZeroDivisionError: division by zero
Ok: 2020-10-23 06:41:56,688 INFO demo.py 5.0
查看 DataKit 运行情况¶
monitor 用法参见这里
检查采集器配置是否正确¶
编辑完采集器的配置文件后，可能某些配置有误（如配置文件格式错误），通过如下命令可检查是否正确：
查看工作空间信息¶
为便于大家在服务端查看工作空间信息，DataKit 提供如下命令查看：
datakit tool --workspace-info
{
"token": {
"ws_uuid": "wksp_2dc431d6693711eb8ff97aeee04b54af",
"bill_state": "normal",
"ver_type": "pay",
"token": "tkn_2dc438b6693711eb8ff97aeee04b54af",
"db_uuid": "ifdb_c0fss9qc8kg4gj9bjjag",
"status": 0,
"creator": "",
"expire_at": -1,
"create_at": 0,
"update_at": 0,
"delete_at": 0
},
"data_usage": {
"data_metric": 96966,
"data_logging": 3253,
"data_tracing": 2868,
"data_rum": 0,
"is_over_usage": false
}
}
调试 KV 文件¶
采集器的配置文件使用 KV 模板进行配置的时候，如果需要调试，可以通过如下命令来进行调试。
datakit tool --parse-kv-file conf.d/host/cpu.conf --kv-file data/.kv
[[inputs.cpu]]
## Collect interval, default is 10 seconds. (optional)
interval = '10s'
## Collect CPU usage per core, default is false. (optional)
percpu = false
## Setting disable_temperature_collect to false will collect cpu temperature stats for linux. (deprecated)
# disable_temperature_collect = false
## Enable to collect core temperature data.
enable_temperature = true
## Enable gets average load information every five seconds.
enable_load5s = true
[inputs.cpu.tags]
kv = "cpu_kv_value3"
查看云属性数据¶
如果安装 DataKit 所在的机器是一台云服务器（目前支持 aliyun/tencent/aws/hwcloud/azure 这几种），可通过如下命令查看部分云属性数据，如（标记为 - 表示该字段无效）：
datakit tool --show-cloud-info aws
cloud_provider: aws
description: -
instance_charge_type: -
instance_id: i-09b37dc1xxxxxxxxx
instance_name: -
instance_network_type: -
instance_status: -
instance_type: t2.nano
private_ip: 172.31.22.123
region: cn-northwest-1
security_group_id: launch-wizard-1
zone_id: cnnw1-az2
解析行协议数据¶
通过如下命令可解析行协议数据：
可以以 JSON 形式输出：
datakit tool --parse-lp /path/to/file --json
{
"measurements": { # 指标集列表
"testing": {
"points": 7,
"time_series": 6
},
"testing_module": {
"points": 195,
"time_series": 195
}
},
"point": 202, # 总点数
"time_serial": 201 # 总时间线数
}
数据录制和回放¶
数据导入主要用于录入已有的采集数据，再做演示或测试的时候，可以不用额外采集。
开启数据录制¶
在 datakit.conf 中，可开启数据录制功能。开启之后，DataKit 会将数据录制到指定的目录，以便于后续导入：
[recorder]
enabled = true
path = "/path/to/recorder" # 绝对路径，默认在 <DataKit 安装目录>/recorder 目录下
encoding = "v2" # 采用 protobuf-JSON 格式（xxx.pbjson），也可以选择 v1（xxx.lp），采用行协议形式（前者更便于阅读，且数据类型支持更全）
duration = "10m" # 录制时长，从 DataKit 启动后开始计时
inputs = ["cpu", "mem"] # 录制指定采集器的数据（以 monitor 中具体 feed 的名字为准），为空则表示录制所有采集器数据
categories = ["logging", "metric"] # 录制类型，为空则表示录制所有数据类型
录制开始后，目录结构大致如下（此处展示的是时序数据的 pbjson 格式）：
[ 416] /usr/local/datakit/recorder/
├── [ 64] custom_object
├── [ 64] dynamic_dw
├── [ 64] keyevent
├── [ 64] logging
├── [ 64] network
├── [ 64] object
├── [ 64] profiling
├── [ 64] rum
├── [ 64] security
├── [ 64] tracing
└── [1.9K] metric
├── [1.2K] cpu.1698217783322857000.pbjson
├── [1.2K] cpu.1698217793321744000.pbjson
├── [1.2K] cpu.1698217803322683000.pbjson
├── [1.2K] cpu.1698217813322834000.pbjson
└── [1.2K] cpu.1698218363360258000.pbjson
12 directories, 59 files
Warning
- 数据录制完成后，记得关闭该功能（
enable = false），否则每次 DataKit 启动都会启动录制，可能会消耗大量磁盘 - 采集器名字不完全等同于采集器配置中的名字（
[[inputs.some-name]]），而是 monitor *Inputs Info* 面板中第一列中显示的名字。部分采集器的名字可能这样：logging/。此处其存放的数据目录为 */usr/local/datakit/recorder/logging/logging-some-pod-name.1705636073033197000.pbjson*，此处将采集器名字中的/替换成了-`（避免多一层目录结构）
数据回放¶
DataKit 录制完数据后，我们可以将该目录中的数据用 Git 或其它方式保存（一定要确保好已有的目录结构），然后，通过如下命令可以将这些数据导入到观测云：
$ datakit import -P /usr/local/datakit/recorder -D https://openway.guance.com?token=tkn_xxxxxxxxx
> Uploading "/usr/local/datakit/recorder/metric/cpu.1698217783322857000.pbjson"(1 points) on metric...
+1h53m6.137855s ~ 2023-10-25 15:09:43.321559 +0800 CST
> Uploading "/usr/local/datakit/recorder/metric/cpu.1698217793321744000.pbjson"(1 points) on metric...
+1h52m56.137881s ~ 2023-10-25 15:09:53.321533 +0800 CST
> Uploading "/usr/local/datakit/recorder/metric/cpu.1698217803322683000.pbjson"(1 points) on metric...
+1h52m46.137991s ~ 2023-10-25 15:10:03.321423 +0800 CST
...
Total upload 75 kB bytes ok
虽然录制的数据中带了绝对时间戳（纳秒），播放的时候，DataKit 会自动将这些数据平移到当前时间（保留各个数据点之间的相对时间间隔），让它看起来像是新采集的数据一样。
通过如下命令可以获取更多数据导入的帮助说明：
$ datakit import --help
Import used to play recorded history data to 观测云.
Usage:
datakit import [flags]
Flags:
-D, --dataway strings dataway list
-h, --help help for import
--log string log path (default "/dev/null")
-P, --path string point data path (default "/usr/local/datakit/recorder")
Warning
对 RUM 数据而言，如果回放的目标工作空间没有对应的 APP ID，则数据无法写入，可以在目标工作空间新建一个应用，将 APP ID 改成和录制数据中的一致，或者替换已有的录制数据中 APP ID 为目标工作空间中对应 RUM 应用的 APP ID。
其它¶
Telegraf 集成¶
注意：建议在使用 Telegraf 之前，先确 DataKit 是否能满足期望的数据采集。如果 DataKit 已经支持，不建议用 Telegraf 来采集，这可能会导致数据冲突，从而造成使用上的困扰。
安装 Telegraf 集成
启动 Telegraf
关于 Telegraf 的使用事项，参见这里。
Security Checker 集成¶
安装 Security Checker
安装成功后会自动运行，Security Checker 具体使用，参见这里
DataKit eBPF 集成¶
安装 DataKit eBPF 采集器，当前只支持 linux/amd64 | linux/arm64 平台，采集器使用说明见 DataKit eBPF 采集器
如若提示 open /usr/local/datakit/externals/datakit-ebpf: text file busy，停止 DataKit 服务后再执行该命令
Warning
该命令在 Version-1.5.6 已经被移除。新版本默认就内置了 eBPF 集成。
DataKit 更新 IP 数据库文件¶
- 可直接使用如下命令安装/更新 IP 地理信息库（此处可选择另一个 IP 地址库
geolite2，只需把iploc换成geolite2即可）：
- 更新完 IP 地理信息库后，修改 datakit.conf 配置：
-
重启 DataKit 生效
-
测试 IP 库是否生效
datakit tool --ipinfo 1.2.3.4
ip: 1.2.3.4
city: Brisbane
province: Queensland
country: AU
isp: unknown
如果安装失败，其输出如下：
-
修改 datakit.yaml，打开 4 处带
---iploc-start和---iploc-end中间注释。 -
重新安装 DataKit：
- 进入容器，测试 IP 库是否生效
datakit tool --ipinfo 1.2.3.4
ip: 1.2.3.4
city: Brisbane
province: Queensland
country: AU
isp: unknown
如果安装失败，其输出如下：
- helm 部署添加
--set iploc.enable
helm install datakit datakit/datakit -n datakit \
--set datakit.dataway_url="https://openway.guance.com?token=<YOUR-TOKEN>" \
--set iploc.enable true \
--create-namespace
关于 helm 的部署事项，参见这里。
- 进入容器，测试 IP 库是否生效
datakit tool --ipinfo 1.2.3.4
ip: 1.2.3.4
city: Brisbane
province: Queensland
country: AU
isp: unknown
如果安装失败，其输出如下：
DataKit 自动命令补全¶
新版本补全基于 Cobra 命令树生成，支持
bash、zsh、fish和powershell。安装或升级 DataKit 不会自动启用 shell completion，如需使用命令补全，请在安装完成后手动执行datakit completion <shell>。注意：
datakit completion适用于 DataKit Version-2.1.0 及以后版本。更早版本请以对应版本文档中的命令写法为准。
在使用 DataKit 命令行的过程中，因为命令参数较多，这里提供了自动补全功能。
常见使用方式如下：
- 显式按 bash 安装：
datakit completion bash --force - 显式按 zsh 安装：
datakit completion zsh --force - 显式按 fish 安装：
datakit completion fish --force - 显式按 powershell 安装：
datakit completion powershell --force - 自动识别当前 shell 并安装：
datakit completion --force - 只输出脚本不安装：
datakit completion bash --print
建议显式指定 shell 类型，尤其是在通过 sudo 执行时。datakit completion --force 依赖当前环境中的 SHELL 变量自动识别 shell；如果 sudo 或其他受限环境未保留该变量，自动识别会失败。
主流 Linux 环境通常都支持命令补全。以 bash 为例，如果宿主机或容器内尚未安装补全支持，可额外安装如下软件包：
- Ubuntu：
apt install bash-completion - CentOS:
yum install bash-completion bash-completion-extras
指定 shell 后，datakit completion <shell> 会：
- 将补全脚本安装到标准路径
- 输出实际安装路径以及如何立即生效
例如：
$ datakit completion bash --force
completion for bash installed to /usr/share/bash-completion/completions/datakit
reload your shell or run: source /usr/share/bash-completion/completions/datakit
如果当前运行在 Docker 容器中，则补全会安装到容器文件系统内的对应路径，输出中也会明确提示这一点。
bash 配置¶
执行：
如果安装到系统 completion 目录，通常重新打开 shell 后即可生效。如果需要在当前 shell 立即生效，可执行命令输出中的 source 提示。
zsh 配置¶
执行：
zsh 补全默认会将脚本安装到 ~/.zfunc/_datakit。如果当前 zsh 尚未加载该目录，需要先将其加入 fpath 并重新执行 compinit：
如需每次启动 zsh 自动加载，可将上述配置加入 ~/.zshrc，并确保 fpath 配置位于 compinit 之前。也可以直接复制 datakit completion zsh --force 输出的命令完成写入和加载。
fish 配置¶
执行：
fish 补全默认安装到 ~/.config/fish/completions/datakit.fish，通常重新打开 fish 后即可生效。
PowerShell 配置¶
执行：
PowerShell 补全默认会生成独立的补全脚本，不会修改或覆盖用户的 Microsoft.PowerShell_profile.ps1。如需当前会话立即生效，可执行命令输出中的 dot-source 提示；如需每次启动 PowerShell 自动加载，可自行将该 dot-source 语句加入 profile。
补全使用示例：
$ datakit <tab> # 输入 \tab 即可提示如下命令
check completion debug dql import install
monitor pipeline run service tool version
$ datakit dql <tab> # 输入 \tab 即可提示如下选项
--auto-json --csv -F,--force --host -J,--json --log -R,--run -T,--token -V,--verbose
以下提及的所有命令，均可使用这一方式来操作。
只输出自动补全脚本¶
如果需要先审阅脚本内容，或者自行处理安装路径，可以使用 --print：
如需显式指定安装路径，可使用 --path：