@@ -3,24 +3,27 @@ sidebar_position: 3
33---
44
55# 添加规则
6+
67> 只有** 项目管理员** 和** 组织管理员** 有权添加和编辑规则，其他权限角色仅能查看规则内容
78
89## 数据格式要求
10+
911平台规则仅对特定格式的数据生效，这类数据需包含消息、时间戳、主题、消息类型，属于流数据。
1012
1113文件要求：
14+
1215- 后缀必须为：.log、.mcap、.bag
1316- 目前支持的 log 时间戳格式如下：
1417
15- | 时间戳类型 | 时间戳格式 | 示例 |
16- | --- | --- | --- |
17- | 常规文件中的时间戳 | %m%d %H:%M:%S.%f | 0212 12:12:12.548513 |
18- | | %b %d %H:%M:%S | Dec 12 12:12:12 |
19- | | %Y-%m-%d %H:%M:%S.%f | 2023-02-12 12:12:12.548513 |
20- | | %H:%M:%S.%f | 12:12:12.548513 |
21- | 特殊 * 文件名/文件第一行中的时间戳 * （用于文件中时间戳未全部包含年、月、日、时、分、秒的情况） | %Y-%m-%d %H:%M:%S | 2023-02-12 12:12:12 |
22- | | %Y/%m/%d %H:%M:%S | 2023/02/12 12:12:12 |
23- | | %Y%m%d%H | 2023021212 |
18+ | 时间戳类型 | 时间戳格式 | 示例 |
19+ | -------------------------------------------------------------------------------------------- | -------------------- | ----------------------- --- |
20+ | 常规文件中的时间戳 | %m%d %H:%M:%S.%f | 0212 12:12:12.548513 |
21+ | | %b %d %H:%M:%S | Dec 12 12:12:12 |
22+ | | %Y-%m-%d %H:%M:%S.%f | 2023-02-12 12:12:12.548513 |
23+ | | %H:%M:%S.%f | 12:12:12.548513 |
24+ | 特殊 _ 文件名/文件第一行中的时间戳 _ （用于文件中时间戳未全部包含年、月、日、时、分、秒的情况） | %Y-%m-%d %H:%M:%S | 2023-02-12 12:12:12 |
25+ | | %Y/%m/%d %H:%M:%S | 2023/02/12 12:12:12 |
26+ | | %Y%m%d%H | 2023021212 |
2427
2528若有其他格式的时间戳需要支持，请联系我们。
2629
@@ -29,16 +32,19 @@ sidebar_position: 3
2932规则组是规则的集合，用于对规则进行分类管理。
3033
3134### 添加规则组
35+
3236在项目中，进入「数采&诊断规则」分页，点击【添加规则组】，添加成功后，可在该规则组内添加具体规则。
3337
3438![ 添加规则组] ( ./img/add-rule_1.png )
3539
3640### 启用规则组
41+
3742新添加的规则组默认为「关闭」状态，若要对项目设备进行数据监听，需手动开启。
3843
3944![ 启用规则组] ( ./img/add-rule_2.png )
4045
4146### 管理规则组
47+
4248在【更多】操作中，支持对规则组进行：重命名、删除。
4349
4450![ 管理规则组] ( ./img/add-rule_3.png )
@@ -48,14 +54,17 @@ sidebar_position: 3
4854规则是规则组中的单个规则，用于定义触发数据采集与诊断的条件，以及触发后的操作。
4955
5056### 添加规则
57+
5158在规则组中，可点击【创建空白规则】或【从规则模板创建】添加新规则。
5259
5360![ 添加规则] ( ./img/add-rule_4.png )
5461
5562### 规则内容
63+
5664规则主要包含：基础信息、事件监听条件、触发操作。
5765
5866#### 基础信息
67+
5968为规则命名，规则名称用于区分不同规则，方便后续管理和识别。
6069
6170![ 基础信息] ( ./img/add-rule_5.png )
@@ -67,12 +76,14 @@ sidebar_position: 3
6776![ 设备事件监听] ( ./img/add-rule_6.png )
6877
6978##### 关注的话题
79+
7080- 关注的话题：缩小规则匹配范围，提高规则诊断的性能、速度和准确度
7181- 话题的选项来源：在组织的数采客户端配置中设置，详见[ 「数采客户端-存储设置」] ( https://docs.coscene.cn/docs/recipes/device/device-collector#%E8%A7%84%E5%88%99%E8%A7%A6%E5%8F%91%E8%AF%9D%E9%A2%98topic )
7282- 话题的类型：支持消息类型为` std_msgs/string ` 的话题
7383- 若需监听设备中日志类型的文件，请选择` /external_log `
7484
7585##### 匹配事件码表
86+
7687- 事件码表定义事件的 code 值、事件名称、等级、解决方案等信息。其中：
7788 - 事件码表：支持 JSON 或 CSV 文件
7889 - 事件码表必须包含 code 列，作为事件的唯一标识符；其他列的表头需为英文，内容可自定义，用于后续内容引用
@@ -81,9 +92,11 @@ sidebar_position: 3
8192![ 事件码表] ( ./img/add-rule_7.png )
8293
8394##### 事件匹配条件
95+
8496> 根据设备消息字段与值的匹配关系，判断是否触发事件。若触发，则执行后续操作。
8597
8698事件匹配条件包含：消息字段、逻辑关系、值。其中：
99+
87100- 消息字段：填写需要监听的字段，如 msg.data（若监听 log 文件，则填写为 msg.message）
88101- 逻辑关系：选择「包含」或「等于」关系
89102- 值：填写需要匹配的具体值，默认引用事件码表中的 code（即当检测到 code 列中任一行的内容时，都会触发规则），点击【切换】图标可直接输入值
@@ -94,6 +107,7 @@ sidebar_position: 3
94107** 示例 1：判断 log 文件中是否出现某些 code**
95108
96109监听 log 文件中是否出现事件码表 code 列的值，按以下步骤操作：
110+
971111 . 关注的话题：选择 ` /external_log `
981122 . 事件码表：上传 csv 文件，其中 code 列输入需要匹配的内容
991133 . 事件匹配条件：msg.message 包含 事件码表 code 列任一行的值
@@ -105,6 +119,7 @@ sidebar_position: 3
105119** 示例 2：判断 log 文件中是否出现某个关键词**
106120
107121监听 log 文件中是否出现关键词 DeviceError，按以下步骤操作：
122+
1081231 . 关注的话题：选择 ` /external_log `
1091242 . 事件匹配条件：msg.message 包含 DeviceError
110125
@@ -115,6 +130,7 @@ sidebar_position: 3
115130** 示例 3：判断 bag 文件中是否出现某些 code**
116131
117132监听 bag 文件的 ` /error_code ` 话题（消息类型为 std_msgs/string）中的 msg.data 消息字段，判断是否出现事件码表 code 列的值，按以下步骤操作：
133+
1181341 . 事件码表：上传 csv 文件，其中 code 列输入需要匹配的内容
1191352 . 事件匹配条件：msg.data 包含 事件码表 code 列任一行的值
120136
@@ -125,6 +141,7 @@ sidebar_position: 3
125141** 示例 4：判断 bag 文件中是否出现某个关键词**
126142
127143监听 bag 文件的 ` /error_code ` 话题（消息类型为 std_msgs/string）中的 msg.data 消息字段，判断有否出现关键词 DeviceError，按以下步骤操作：
144+
1281451 . 事件匹配条件：msg.data 包含 DeviceError
129146
130147![ bag 中出现 关键词] ( ./img/add-rule_12.png )
@@ -134,20 +151,25 @@ sidebar_position: 3
134151注意：如有多个条件需同时满足，请使用【+并且】。
135152
136153##### 事件去重时长
154+
137155> 若新事件（同一事件）在上次合并事件后的设定时间内发生，则与原事件合并。每次新事件发生时，都重置时间，直到超出时间窗口都无新事件发生时，完成合并。
156+
138157- 支持范围：1 秒 ~ 86400 秒（1 天）
139158
140159![ 事件去重时长] ( ./img/add-rule_13.png )
141160
142161#### 触发操作
162+
143163触发操作是指规则条件满足后触发后的操作，支持采集数据、诊断数据。
144164
145165##### 采集数据
166+
146167> 设备端触发规则后，将自动创建采集任务，采集对应时间的设备数据并保存到记录。
147168
148169![ 采集数据] ( ./img/add-rule_14.png )
149170
150171采集数据模块中包含：上传文件的时间范围、记录信息、采集限制、更多设置。其中：
172+
151173- 上传文件的时间范围
152174 - 定义需要采集触发时间点前后多长时间范围的文件，采集目录的设置参考[ 数采客户端-存储设置] ( https://docs.coscene.cn/docs/recipes/device/device-collector#%E5%AD%98%E5%82%A8%E8%AE%BE%E7%BD%AEmod )
153175- 记录信息
@@ -170,12 +192,14 @@ sidebar_position: 3
170192![ 任务关联记录] ( ./img/add-rule_16.png )
171193
172194##### 诊断数据
195+
173196> - 从设备端采集数据保存到记录后，自动在规则触发时间点创建一刻
174197> - 手动创建的记录可通过调用「数据诊断」动作自动标记关键时间点。「数据诊断」动作会聚合项目中勾选了「自动诊断」模块的所有规则，对记录中的文件进行规则匹配。
175198
176199![ 诊断数据] ( ./img/add-rule_17.png )
177200
178201诊断数据模块中包含：一刻信息、任务信息。其中：
202+
179203- 一刻信息
180204 - 定义触发时间点的一刻名称、描述、属性值等，支持使用变量（如：` {scope.code} ` ，详见下文）
181205- 任务信息
@@ -186,22 +210,25 @@ sidebar_position: 3
186210![ 自动诊断的一刻] ( ./img/add-rule_18.png )
187211
188212### 规则变量
213+
189214规则支持使用变量，详见下表：
190215
191- | 变量名 | 含义 | 效果示例 |
192- | --- | --- | --- |
193- | ` {scope.code} ` | 事件码表中 code 列的值 | ` ERROR-CODE-001 ` |
194- | ` {scope.solution} ` | 事件码表中 solution 列的值 | ` 尝试重启设备 ` |
195- | ` {msg} ` | 触发规则的消息内容 | ` {"timestamp": {"sec": 123456, "nsec": 789}, "message": "demo log message", "file": "demo.log", "level": 2} ` |
196- | ` {topic} ` | 触发规则的话题 | ` /error_code ` |
197- | ` {ts} ` | 触发规则时的时间戳 | ` 1738915780.123 ` |
216+ | 变量名 | 含义 | 效果示例 |
217+ | ------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------- --- |
218+ | ` {scope.code} ` | 事件码表中 code 列的值 | ` ERROR-CODE-001 ` |
219+ | ` {scope.solution} ` | 事件码表中 solution 列的值 | ` 尝试重启设备 ` |
220+ | ` {msg} ` | 触发规则的消息内容 | ` {"timestamp": {"sec": 123456, "nsec": 789}, "message": "demo log message", "file": "demo.log", "level": 2} ` |
221+ | ` {topic} ` | 触发规则的话题 | ` /error_code ` |
222+ | ` {ts} ` | 触发规则时的时间戳 | ` 1738915780.123 ` |
198223
199224### 调试规则
200225
201226#### 前提条件
227+
202228准备一条记录，在记录中有可供调试的文件，即可触发规则的 mcap、bag 或 log 文件。
203229
204230#### 调试步骤
231+
2052321 . 在规则详情中点击【调试】按钮，选择预准备的记录
206233
207234![ 调试步骤1] ( ./img/add-rule_19.png )
0 commit comments