故障排查

KaiwuDB 集群

KaiwuDB 提供日志、监控方案、核心转储功能，用于收集问题诊断数据，定位和分析问题。

日志：KaiwuDB 支持通过日志记录各模块程序的运行状态，并将日志输出到日志文件。
监控：KaiwuDB 支持使用 KaiwuDB 监控平台、Prometheusopen in new window 和 Grafanaopen in new window 查看集群节点状态、监控集群指标。更多详细信息，参见数据库监控概述。
核心转储功能：在某些情况下，KaiwuDB 可能会因为严重的错误而崩溃或终止运行。如果开启核心转储功能，当进程发生严重错误时，系统生成 core 文件，用于诊断问题，找到解决方法。KaiwuDB 支持在启动脚本、执行会话或者在系统层面配置 ulimit，开启核心转储功能。
配置示例：
```
ulimit -c
echo '{KWDB_CORE_PATH}/core.%e.%p' > /proc/sys/kernel/core_pattern
```
注意
一般情况下，core 文件较大。建议将其存储到单独的硬盘分区。

功能问题

查询数据时，如果系统返回错误结果或者某个功能无法正常工作，用户可以通过错误码、日志和监控信息来定位和分析问题。

查阅错误码参考手册，根据建议措施尝试解决问题。
进入用户数据目录下的 log 子目录，查看已有日志信息，汇总问题发生的时间、背景信息及错误信息。
通过 KaiwuDB 监控平台、Grafana 查看 KaiwuDB 集群及各个节点的监控指标。
如果仍无法定位或解决问题，联系open in new window KaiwuDB 技术支持人员并提供详细的错误日志和问题报告来定位和解决问题。

性能问题

如果 KaiwuDB 系统响应时间变慢，性能下降，可以通过 KaiwuDB 监控平台、Grafana 监控系统、日志找出性能瓶颈。

通过 KaiwuDB 监控平台概览页面、Grafana 概览指标模板确认网络是否存在问题。
通过 KaiwuDB 监控平台硬件页面、Grafana 硬件指标模板查看 CPU 使用率、内存使用率以及已用空间和可用空间有无告警。
如果仍无法定位或解决问题，联系open in new window KaiwuDB 技术支持人员并提供详细的性能报告来定位和解决问题。

稳定性问题

如果 KaiwuDB 系统出现系统崩溃、服务中断等稳定性问题，可以通过 KaiwuDB 监控平台、Grafana 监控系统、日志、core 文件来定位和分析问题。

通过 KaiwuDB 监控平台、Grafana 查看 CPU、内存、磁盘 I/O、网络流量等，定位可能导致系统不稳定的因素。
查看故障日志中的 call stack 信息和 core 文件，收集系统崩溃的时间、范围、持续时间等信息。
注意
默认情况下，禁用核心转储功能。用户可以在启动脚本、执行会话或者在系统层面配置 ulimit 或者编辑 ulimit 配置文件，开启核心转储功能。
如果仍无法定位或解决问题，联系open in new window KaiwuDB 技术支持人员并提供详细的系统状态数据和日志文件来定位和解决问题。

健壮性问题

如果 KaiwuDB 因断电或者其他因素导致服务中断后无法重启，或有些查询不一致或文件访问失败，可能是因为底层数据库系统文件被破坏导致，可以通过以下两种方式排查分析：

离线检查：
- 现象：数据库服务无法启动；
- 检查方式：通过 kwbase debug tsdb 子命令行方式检查时序数据文件，找到数据文件问题原因，结果输出到控制台；可通过 --help 查看命令参数及其使用方法。
在线检查：
- 现象：kwbae 程序还在运行中，但有些数据查询结果不一致或者文件访问失败；
- 检查步骤：（1）开启集群参数 ts.run_ldb_command.enabled
```
set cluster setting ts.run_ldb_command.enabled=true;
```
（2）在 --store 目录下的 tsdb 目录下新建文件 tsdb_data_check.cmd ⽂件，在文件中输入需要执行的 kwbase debug tsdb 命令。（3）kwbase 的质量检测线程，每5秒钟执行一次文件中的执行命令，质量检查完毕后，会将 tsdb_data_check.cmd 文件删除，并将检查结果输出到 TsEngine 日志中。

检测的是存储引擎存储的时序数据，可检测的文件类型包含：WAL数据、元数据、分区 metric 数据、tag数据。具体包含如下：

文件类型	存储目录	具体文件
WAL相关⽂件	tsdb/wal	.cur、.meta
tag相关⽂件	tsdb/schema/xxx（table_id）/tag	.tag.et（entity_id索引）、.tag.ht (primarykey 索引)、*.tag.mt_1（版本元数据）
	tsdb/schema/xxx（table_id）/tag/tag_version_1/	.tag.header（头⽂件bitmap）、.tag.hps（hashpoint值）、.tag.rinfo（⾏状态信息）、.tag.mt（元数据信息）、*.tag.pt（pirmarykey、entity_id）
元数据相关文件	tsdb/schema/xxx（table_id）/metric	*.bt_1（metric版本元数据）
	tsdb/vg_xxx/	TSVERSION-xxx、CURRENT
分区 metric 相关文件	tsdb/vg_xxx/dbxxxxx_+xxxxxxxxxxxxx/	partition_del.item、agg.ver-xxx、count.stat-xxx、last.ver-xxx、block.ver-xxx、header.b.ver-xxx、header.e.ver-xxx

kwbase debug tsbs命令说明：

命令	参数	说明	必选项
`- TSDB Tool`	`--db_path`	时序存储引擎的根⽬录	必选
`tag_check`	检查 tag 表的数据质量
	`--table_id`	表 ID，`0`代表全部表	必选
	`--hashpoint_num`	副本 `hashpoint` 数量，输⼊后⽤于检测 primarykey 对应的 `hashpoint` 值是否正确	可选
`partition_check`	检测分区中的数据质量
	`--db_id`	数据库 ID，`0` 代表全部库	必选
	`--partition_begin`	过滤分区，开始时间	可选
	`--partition_end`	过滤分区，结束时间	可选
	`--vgroup_id`	虚拟组 ID，`0` 表⽰所有的 vgroup	必选
	`--print_pkey`	打印失败的 tag 记录时，同时打印出对应的 primarykey ⼗六进制字符串.	可选
`tag_print`	打印 TAG 信息
	`--table_id`	表ID，`0` 表⽰所有的表	必选
	`--primary_key`	primarykey 的16进制字符串，类型1	可选
	`--tag_rownum`	tag 记录版本以及第⼏条记录，类型2	可选
	`--osn`	操作的 `OSN`，tag 记录中有该 `OSN` 时间点操作记录的会被打印出来，类型3	可选
	`--vgroup_id`	虚拟组 ID，类型4	可选
	`--entity_id`	设备 ID.，类型4	可选
	`--print_pkey`	同时打印出对应的primarykey⼗六进制字符串
`metric_print`	打印分区中设备的统计信息
	`--table_id`	表 ID，0 表⽰所有的表	必选
	`--db_id`	数据库ID，0 表⽰所有的数据库	必选
	`--partition_begin`	过滤分区，开始时间	可选
	`--partition_end`	过滤分区，结束时间	可选
	`--vgroup_id`	虚拟组 ID	必选
	`--entity_id`	设备 ID	必选
`wal_check`	检查 WAL 数据
`meta_print`	打印表某个版本的schema信息
	`--table_id`	表ID，`0` 表⽰所有的表	必选
	`--table_version`	表的某个版本ID	必选

::: 说明 --primary_key 、--tag_rownum 、--osn 、--vgroup_id 、--entity_id 必须传入一类 :::

命令示例：

# 检查某个表的 tag 记录数据质量是否正常
kwbase debug tsdb tag_check --db_path=/var/lib/kaiwudb/tsdb --table_id=<table id>

# 根据 primarykey 打印 tag 记录状态信息，primary_key 来自 TsEngine.log
kwbase debug tsdb tag_print --db_path=/var/lib/kaiwudb/tsdb --table_id=<table id> --primary_key=<primary key for tag>

#根据 entity_id 打印 tag 记录状态信息，entity_id 来自 TsEngine.log
kwbase debug tsdb print_tag --db_path=/var/lib/kaiwudb/tsdb --table_id=<table id> --hashpoint_num=<hashpoint number> --vgroup_id=<vgroup id> --entity_id=<entity id>

# 根据tag rownum打印tag记录状态信息，tag_rownum 来自 TsEngine.log
kwbase debug tsdb print_tag --db_path=/var/lib/kaiwudb/tsdb --table_id=<table id> --hashpoint_num=<hashpoint number> --tag_rownum=<primary key for tag>

# 检查某个分区数据的状态信息：在 TsEngine.log 中发现某个分区访问失败，或者 count 统计信息不正确，或者需要检测编码/压缩实际使⽤算法与⽤⼾配置是否⼀致。
kwbase debug tsdb partition_check --db_path=/var/lib/kaiwudb/tsdb --partition_id=<partition_id> --db_id=<db id> --vgroup_id=<vgroup id>

# 某个 entity 的统计信息：在 TsEngine.log 中发现某个分区访问失败，或者 count 统计信息不正确。
kwbase debug tsdb metric_print --db_path=/var/lib/kaiwudb/tsdb --entity_id=<entity id> --vgroup_id=<vgroup id> --table_id=<table id>

资源使用问题

KaiwuDB 支持通过启动参数--max-ts-memory控制时序内存使用限额。KaiwuDB 提供两种方式查看数据库当前时序各模块内存使用情况：

通过curl -s 'https://{host}:{port}/_status/tsmemory' 查看，port为数据库启动命令中http端口，默认8080;
日志为INFO级别下，可以在日志文件中通过关键字“Memory usage”查看内存总使用情况；

注意

安全模式启动数据，使用https，非安全模式启动数据库，使用http;
在内存使用达到限额时，可能会导致写入速率变慢或者查询超时，如果某节点持续超限，可能会影响节点间数据同步，建议尽快排查内存使用情况，根据实际情况调整限额或者扩容；

应用开发

KaiwuDB JDBC

KaiwuDB 支持使用日志记录功能来帮助解决 KaiwuDB JDBC 驱动程序在应用程序使用时遇到的问题。KaiwuDB JDBC 驱动程序使用 java.util.logging 日志 API，其根记录器是 com.kaiwudb。

用户可以采用以下任一方式开启日志：

使用连接属性启动日志
使用 logging.properties 属性配置文件开启日志

使用连接属性启动日志

KaiwuDB JDBC 驱动程序支持使用连接属性启用日志记录。连接属性使用 loggerLevel 和 loggerFile 参数定义日志的级别和输出文件名。

jdbc:kaiwudb://127.0.0.1:26257/defaultdb?loggerLevel=DEBUG     //只配置loggerLevel
jdbc:kaiwudb://127.0.0.1:26257/defaultdb?loggerLevel=Trace&loggerFile=kaiwudb-jdbc.log  //同时配置loggerLevel和loggerFile

参数说明：

loggerLevel：驱动程序的级别，支持 OFF、DEBUG 和 TRACE 取值。这些值与 java.util.logging.Logger 的等级对应关系如下：
LoggerLevel java.util.logging 描述
OFF OFF 不启用日志。
DEBUG FINE 一般的消息跟踪。
TRACE FINEST 非常详细的跟踪，包括调试问题所需的所有详细信息。
loggerFile：Logger 的输出文件名。
- 如果指定输出文件名，Logger 使用 java.util.logging.FileHandler 将日志写入指定的文件。
- 如未指定输出文件名，或者 java.util.logging.FileHandler 参数无法创建文件，则使用 java.util.logging.Consolehandler 输出日志。java.util.logging.Consolehandler参数需要与 loggerLevel 一起使用。

LoggerLevel	java.util.logging	描述
OFF	OFF	不启用日志。
DEBUG	FINE	一般的消息跟踪。
TRACE	FINEST	非常详细的跟踪，包括调试问题所需的所有详细信息。

使用 logging.properties 文件开启日志

默认情况下，Java 日志框架将其日志配置存储到一个名为 logging.properties 的文件中。用户可以在 Java 安装目录的 lib 文件夹中安装全局配置文件。

logging.properties 文件日志设置的示例如下：

// 指定处理程序，处理程勋在 VM 启动时安装
handlers= java.util.logging.FileHandler

// 默认的全局日志级别
.level = OFF

// 默认文件输出在用户的主目录中
java.util.logging.FileHandler.pattern = %h/kaiwudb-jdbc%u.log
java.util.logging.FileHandler.limit = 5000000
java.util.logging.FileHandler.count = 20
java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.FileHandler.level =FINEST
java.util.logging.SimpleFormatter.format = %1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS %4$s %2$s %5$s%6$s%n

// 特性属性
com.kaiwudb.level=FINEST

用户也可以在启动 Java 程序时，通过配置 java.util.logging.config.file 参数来使用单独的日志配置文件。

java -jar -Djava.util.logging.config.file=logging.properties run.jar

数据读写

Kafka Connect

当 Kafka Connect 出现故障，无法正常工作时，用户可以从以下方面进行故障排查：

查看 Kafka Connect 日志文件：默认情况下，Kafka Connect 的日志文件位于 Kafka 安装目录的 logs 文件夹下。在该文件夹中，用户找到名为 connect.log 的日志文件，查找相关的故障记录。
确认连接器配置：通常情况下，连接器的配置文件位于 Kafka Connect 安装目录下的 config 文件夹下。主要的连接器配置文件是 connect-distributed.properties（分布式模式）或 connect-standalone.properties（独立模式）。用户可以打开相应的配置文件，检查各个连接器的配置属性。
检查 Kafka 集群状态：用户可以通过访问 Kafka 的 Zookeeper 节点来检查 Kafka 集群状态。连接到 Zookeeper 服务器并使用 Zookeeper 命令行工具，在 Zookeeper 的 shell 提示符下，输入 ls /brokers/ids 命令，可以列出所有 Kafka 代理 ID。用户还可以使用 Kafka 的管理工具，如 kafka-topics.sh 和 kafka-consumer-groups.sh 来验证主题和 Consumer Group 的状态。
检查源系统和目标系统：如果问题涉及到特定的源系统或目标系统（如数据库或文件系统），确保这些系统正常运行并且与 Kafka Connect 所在的主机可以正常通信。确认是否正确配置与源系统或目标系统进行连接的参数，如 URL、用户名和密码等。
验证数据格式和转换：检查连接器配置文件中的 key.converter 和 value.converter 属性，确定使用的数据转换器。转换器配置文件位于 Kafka Connect 安装目录下的 config 文件夹下。打开相应的转换器配置文件，检查数据转换器配置是否正确，并确保转换器能够处理源数据和目标数据的格式。
重启 Kafka Connect 进程：在排除其他问题后，尝试重新启动 Kafka Connect 进程可以解决一些常见问题。停止 Kafka Connect 进程，并使用启动脚本或命令来重新启动。
使用 Kafka Connect 工具：
- connect-distributed.sh：运行 connect-distributed.sh config 或 connect-distributed.properties命令，启动分布式模式的 Kafka Connect，并在日志中查看详细信息。
- connector-plugins.sh：运行 connector-plugins.sh list 命令，获取当前已加载的连接器和转换器的信息。

告警通知问题

Broker长时间不可达：每次Push最多阻塞5s后失败、写WARNING日志；下次指标越界再触发。
错误配置（如broker格式非法）：解析失败返回错误，不影响其它通道。
用户误启用MQTT但未配置：默认值tcp://192.168.13.8:1883与ylkj/msg/push/s2p/kaiwu，若Broker不存在会持续失败，需运维干预。
告警未到达：检查alert.mqtt.enabled=true；SHOW LICENSE未到期；Broker可达；订阅Topic匹配；服务日志是否有mqtt publish failed、mqtt publish、alert MQTT dispatcher started。
TLS握手失败：检查CA证书格式（PEM）、broker是否真启用TLS。

# 故障排查

# KaiwuDB 集群

# 功能问题

# 性能问题

# 稳定性问题

# 健壮性问题

# 资源使用问题

# 应用开发

# KaiwuDB JDBC

# 使用连接属性启动日志

# 使用 logging.properties 文件开启日志

# 数据读写

# Kafka Connect

# 告警通知问题