故障排查 | ThingsBoard PE Edge

故障排查工具与技巧
- MessagePack处理日志
日志
- 查看日志
- 启用特定日志
指标
Prometheus指标
Edge随机断开与云端连接
- 如何应用
监控消息统计
- 统计监控的遥测键
  - Uplink
  - Downlink
获取帮助

故障排查工具与技巧

MessagePack处理日志

若要记录最慢与调用最频繁的规则节点日志，请在日志配置中加入以下 logger：

<logger name="org.thingsboard.server.service.queue.TbMsgPackProcessingContext" level="DEBUG" />

配置后，可在日志中查看如下信息：

2021-03-24 17:01:21,023 [tb-rule-engine-consumer-24-thread-3] DEBUG o.t.s.s.q.TbMsgPackProcessingContext - Top Rule Nodes by max execution time:
2021-03-24 17:01:21,024 [tb-rule-engine-consumer-24-thread-3] DEBUG o.t.s.s.q.TbMsgPackProcessingContext - [Main][3f740670-8cc0-11eb-bcd9-d343878c0c7f] max execution time: 1102. [RuleChain: Thermostat|RuleNode: Device Profile Node(3f740670-8cc0-11eb-bcd9-d343878c0c7f)]
2021-03-24 17:01:21,024 [tb-rule-engine-consumer-24-thread-3] DEBUG o.t.s.s.q.TbMsgPackProcessingContext - [Main][3f6debf0-8cc0-11eb-bcd9-d343878c0c7f] max execution time: 1. [RuleChain: Thermostat|RuleNode: Message Type Switch(3f6debf0-8cc0-11eb-bcd9-d343878c0c7f)]
2021-03-24 17:01:21,024 [tb-rule-engine-consumer-24-thread-3] INFO  o.t.s.s.q.TbMsgPackProcessingContext - Top Rule Nodes by avg execution time:
2021-03-24 17:01:21,024 [tb-rule-engine-consumer-24-thread-3] INFO  o.t.s.s.q.TbMsgPackProcessingContext - [Main][3f740670-8cc0-11eb-bcd9-d343878c0c7f] avg execution time: 604.0. [RuleChain: Thermostat|RuleNode: Device Profile Node(3f740670-8cc0-11eb-bcd9-d343878c0c7f)]
2021-03-24 17:01:21,025 [tb-rule-engine-consumer-24-thread-3] INFO  o.t.s.s.q.TbMsgPackProcessingContext - [Main][3f6debf0-8cc0-11eb-bcd9-d343878c0c7f] avg execution time: 1.0. [RuleChain: Thermostat|RuleNode: Message Type Switch(3f6debf0-8cc0-11eb-bcd9-d343878c0c7f)]
2021-03-24 17:01:21,025 [tb-rule-engine-consumer-24-thread-3] INFO  o.t.s.s.q.TbMsgPackProcessingContext - Top Rule Nodes by execution count:
2021-03-24 17:01:21,025 [tb-rule-engine-consumer-24-thread-3] INFO  o.t.s.s.q.TbMsgPackProcessingContext - [Main][3f740670-8cc0-11eb-bcd9-d343878c0c7f] execution count: 2. [RuleChain: Thermostat|RuleNode: Device Profile Node(3f740670-8cc0-11eb-bcd9-d343878c0c7f)]
2021-03-24 17:01:21,028 [tb-rule-engine-consumer-24-thread-3] INFO  o.t.s.s.q.TbMsgPackProcessingContext - [Main][3f6debf0-8cc0-11eb-bcd9-d343878c0c7f] execution count: 1. [RuleChain: Thermostat|RuleNode: Message Type Switch(3f6debf0-8cc0-11eb-bcd9-d343878c0c7f)]

日志

查看日志

无论采用何种部署方式，ThingsBoard Edge日志均存放在以下目录：

/var/log/tb-edge

不同部署工具查看日志的方式不同：

Standalone Deployment

Docker-Compose Deployment

在运行时查看最新日志：

tail -f /var/log/tb-edge/tb-edge.log

可使用 grep 命令仅显示包含指定字符串的输出。例如，可用以下命令检查服务端是否存在错误：

cat /var/log/tb-edge/tb-edge.log | grep ERROR

在运行时查看最新日志：

docker compose logs -f tb-edge

可使用 grep 命令仅显示包含指定字符串的输出。例如，可用以下命令检查后端是否存在错误：

docker compose logs tb-edge | grep ERROR

提示： 可将日志重定向到文件，然后用任意文本编辑器分析：

docker compose logs -f tb-edge > tb-edge.log

注意： 可随时登录 ThingsBoard Edge 容器并在其中查看日志：

docker ps
docker exec -it NAME_OF_THE_CONTAINER bash

启用特定日志

ThingsBoard支持按需启用或禁用系统特定部分的日志。

可通过修改 logback.xml 实现。该文件与日志本身存放在同一目录：

/usr/share/tb-edge/conf

logback.xml 配置示例：

<!DOCTYPE configuration>
<configuration scan="true" scanPeriod="10 seconds">

    <appender name="fileLogAppender"
              class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>/var/log/tb-edge/tb-edge.log</file>
        <rollingPolicy
                class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>/var/log/tb-edge/tb-edge.%d{yyyy-MM-dd}.%i.log</fileNamePattern>
            <maxFileSize>100MB</maxFileSize>
            <maxHistory>30</maxHistory>
            <totalSizeCap>3GB</totalSizeCap>
        </rollingPolicy>
        <encoder>
            <pattern>%d{ISO8601} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <logger name="org.thingsboard.server" level="INFO" />
    <logger name="org.thingsboard.js.api" level="TRACE" />
    <logger name="com.microsoft.azure.servicebus.primitives.CoreMessageReceiver" level="OFF" />

    <root level="INFO">
        <appender-ref ref="fileLogAppender"/>
    </root>
</configuration>

在配置文件的故障排查场景中，最有价值的是 logger 配置。通过它，您可以按类或按类组启用/禁用日志。

在上面的示例中，默认日志级别为 INFO（即日志仅包含常规信息、警告和错误）。但对 org.thingsboard.js.api 包，我们将日志级别设置为 TRACE，以输出最详细的调试信息。

您也可以完全关闭系统中某些部分的日志。示例中，我们将 com.microsoft.azure.servicebus.primitives.CoreMessageReceiver 类的日志级别设为 OFF。

若要为系统的特定部分启用/禁用日志，请添加对应的 <logger> 配置并等待最多10秒生效。

不同部署方式更新日志配置的方法不同：

Standalone Deployment

Docker-Compose Deployment

对于独立部署，需更新 /usr/share/tb-edge/conf/logback.xml 以更改日志配置。

对于 docker-compose 部署，我们将 /config 目录映射到您本地系统的 ./tb-edge/conf 目录。因此，要更改日志配置，需更新 ./tb-edge/conf/logback.xml 文件。

指标

可在配置文件中设置以下环境变量以启用Prometheus指标：

将 METRICS_ENABLED 设为 true
将 METRICS_ENDPOINTS_EXPOSE 设为 prometheus

指标路径为：https://<yourhostname>/actuator/prometheus，可由Prometheus抓取（无需认证）。

Prometheus指标

Spring Boot Actuator 可通过 Prometheus 暴露部分内部状态指标。

ThingsBoard 推送至 Prometheus 的统计项如下：

tb-edge指标：

attributes_queue_${index_of_queue}（statsNames - totalMsgs, failedMsgs, successfulMsgs）：表示属性写入数据库的统计。
注意：为提高性能，使用多个队列（线程）持久化属性。
ruleEngine_${name_of_queue}（statsNames - totalMsgs, failedMsgs, successfulMsgs, tmpFailed, failedIterations, successfulIterations, timeoutMsgs, tmpTimeout）：表示规则引擎中的消息处理统计，按队列（如Main、HighPriority、SequentialByOriginator等）持久化。部分指标说明：
- tmpFailed：失败并稍后重试的消息数。
- tmpTimeout：超时并稍后重试的消息数。
- timeoutMsgs：超时被丢弃的消息数。
- failedIterations：至少有一条消息未成功处理的消息包处理迭代数。
ruleEngine_${name_of_queue}_seconds（针对每个 tenantId）：表示各队列处理消息的耗时统计。
core（statsNames - totalMsgs, toDevRpc, coreNfs, sessionEvents, subInfo, subToAttr, subToRpc, deviceState, getAttr, claimDevice, subMsgs）：表示内部系统消息的处理统计。部分指标说明：
- toDevRpc：Transport服务处理过的RPC响应数。
- sessionEvents：Transport服务的会话事件数。
- subInfo：Transport服务的订阅信息数。
- subToAttr：Transport服务对属性更新的订阅数。
- subToRpc：Transport服务对RPC的订阅数。
- getAttr：Transport服务的”获取属性”请求数。
- claimDevice：Transport服务的设备认领数。
- deviceState：设备状态变更处理数。
- subMsgs：已处理的订阅消息数。
- coreNfs：已处理的特定”系统”消息数。
jsInvoke（statsNames - requests, responses, failures）：表示JS执行器总请求数、成功数与失败数。
attributes_cache（results - hit, miss）：表示命中缓存与未命中缓存的属性请求数。

transport指标：

transport（statsNames - totalMsgs, failedMsgs, successfulMsgs）：表示Transport从Core接收的请求数。
ruleEngine_producer（statsNames - totalMsgs, failedMsgs, successfulMsgs）：表示从Transport推送到规则引擎的消息数。
core_producer（statsNames - totalMsgs, failedMsgs, successfulMsgs）：表示从Transport推送到ThingsBoard节点设备actor的消息数。
transport_producer（statsNames - totalMsgs, failedMsgs, successfulMsgs）：表示从Transport到Core的请求数。

PostgreSQL相关指标：

ts_latest_queue_${index_of_queue}（statsNames - totalMsgs, failedMsgs, successfulMsgs）：表示最新遥测写入数据库的统计。
注意：为提高性能，使用多个队列（线程）。
ts_queue_${index_of_queue}（statsNames - totalMsgs, failedMsgs, successfulMsgs）：表示遥测写入数据库的统计。
注意：为提高性能，使用多个队列（线程）。

Edge随机断开与云端连接

若Edge实例无明显原因反复断开，数秒内又重连，最可能的原因是 Edge与云端之间的网络不稳定。可能由带宽不足或网络间歇性丢包导致。

一种做法是使用外部工具诊断网络并解决发现的问题。

若无法排查网络，可增大部分超时调整Edge与云端之间的gRPC连接参数。有助于在临时网络波动时减少意外断开。

在ThingsBoard Server（云端）：

EDGES_RPC_CLIENT_MAX_KEEP_ALIVE_TIME_SEC：客户端keepalive ping之间的最小允许间隔。防止客户端发送过于频繁的ping，避免对服务器造成负担；滥用可能成为拒绝服务攻击向量。若客户端在此间隔内发送更频繁的ping，服务器可终止连接。默认1秒。
EDGES_RPC_KEEP_ALIVE_TIME_SEC：连接无活动（无读操作）多长时间后，服务器向客户端发送keepalive ping。用于确认连接仍存活，并防止中间网络设备因空闲而断开连接。服务器主动检查客户端是否仍响应的方式。默认10秒。
EDGES_RPC_KEEP_ALIVE_TIMEOUT_SEC：服务器等待keepalive ping响应的最长时间。若在此时间内未收到确认，服务器将认为连接已断开并可能关闭。该超时用于检测无响应客户端。
默认5秒。

更多关于Cloud侧Edge参数的说明请参见此处

在ThingsBoard Edge（gRPC客户端）：

CLOUD_RPC_KEEP_ALIVE_TIME_SEC：客户端在空闲（无读操作）多少秒后向服务器发送keepalive ping。该设置对保持空闲期连接存活、防止服务器因超时关闭连接至关重要。用于定期探测服务器是否仍响应，并通过可能因空闲而断连的网络设备（如NAT、负载均衡器）维持连接。默认10秒。
CLOUD_RPC_KEEP_ALIVE_TIMEOUT_SEC：客户端等待keepalive ping响应的最长时长。若在此时间内未收到确认，客户端将认为连接已断开或不可达。该超时用于检测服务器或网络故障。若服务器在此时间内无响应，客户端将视为连接丢失，可能会尝试重连或执行其他恢复操作。默认5秒。

更多关于Edge侧Cloud连接配置的说明请参见此处

警告：
gRPC不建议在无调用场景下启用keepalive，并建议客户端不要将keepalive间隔设置得远低于 1分钟。

可扩展部署的安全起始建议：

网络不稳定时不要缩短超时： 若日志中出现ping-ack超时，请增大 *_KEEP_ALIVE_TIMEOUT_SEC。
客户端间隔应≥服务器最小值： 若您希望限制过于频繁的客户端探测，请先提高服务器阈值，再同步调整客户端配置。
间隔应小于链路上最短NAT/LB空闲超时： 以避免连接进入空闲被回收（例如中间设备60秒断开，可设置为25~55秒）。

如何应用

Docker

Ubuntu

服务器

在进行任何更改前先停止当前运行的 ThingsBoard 容器。然后编辑 docker compose 文件：

nano docker-compose.yml

在 YAML 文件的 “environment” 块中添加以下内容：

    environment:
      - EDGES_RPC_CLIENT_MAX_KEEP_ALIVE_TIME_SEC=1
      - EDGES_RPC_KEEP_ALIVE_TIME_SEC=30
      - EDGES_RPC_KEEP_ALIVE_TIMEOUT_SEC=25

Edge

在进行任何更改前先停止当前运行的 TB Edge 容器。然后编辑 docker compose 文件：

nano docker-compose.yml

在 YAML 文件的 “environment” 块中添加以下内容：

    environment:
      - CLOUD_RPC_KEEP_ALIVE_TIME_SEC=30
      - CLOUD_RPC_KEEP_ALIVE_TIMEOUT_SEC=25

完成所有更改后，启动 ThingsBoard 和 TB Edge Docker 容器。

服务器

编辑 ThingsBoard 配置文件：

sudo nano /etc/thingsboard/conf/thingsboard.conf

在配置文件中添加以下内容：

export EDGES_RPC_CLIENT_MAX_KEEP_ALIVE_TIME_SEC=1
export EDGES_RPC_KEEP_ALIVE_TIME_SEC=30
export EDGES_RPC_KEEP_ALIVE_TIMEOUT_SEC=25

Edge

然后编辑 ThingsBoard Edge 配置文件：

sudo nano /etc/tb-edge/conf/tb-edge.conf

在配置文件中添加以下内容：

export CLOUD_RPC_KEEP_ALIVE_TIME_SEC=30
export CLOUD_RPC_KEEP_ALIVE_TIMEOUT_SEC=25

完成所有更改后，重启 ThingsBoard 和 TB Edge 服务。

监控消息统计

*自 TB Edge 版本 4.2 起可用*

为诊断和解决Cloud与Edge间消息传递问题，可监控 uplink（Edge → Cloud）和 downlink（Cloud → Edge）消息流。

下载预配置的 Edge仪表板。
将仪表板导入云端：
- 进入 仪表板 部分。
- 点击 ”+” 按钮，选择 “导入仪表板”，浏览本地 .json 文件并点击 “导入” 完成。

统计监控的遥测键

ThingsBoard Edge暴露一组遥测键，用于监控Edge与Cloud间的消息统计。

Uplink

uplinkMsgsAdded：加入队列的消息数。
uplinkMsgsPushed：成功发送到Cloud的消息数。
uplinkMsgsPermanentlyFailed：永久失败的消息数。
uplinkMsgsTmpFailed：暂时失败的消息数（如因网络问题）。
uplinkMsgsLag：队列中剩余的消息数（滞后量）。

Downlink

downlinkMsgsAdded：加入队列的消息数。
downlinkMsgsPushed：成功发送到Cloud的消息数。
downlinkMsgsPermanentlyFailed：永久失败的消息数。
downlinkMsgsTmpFailed：暂时失败的消息数（如因网络问题）。
downlinkMsgsLag：队列中剩余的消息数（滞后量）。

获取帮助

社区聊天

通过Gitter频道可直接联系工程师团队，并与社区分享您的想法。

Stack Overflow

ThingsBoard团队会持续关注带有thingsboard标签的问题。如果现有问题无法解决您的场景，欢迎提交新问题。

如果以上指南仍未解决您的问题，欢迎联系ThingsBoard团队。

联系我们