diff --git a/docs/2-get-started/1-quick-start.md b/docs/2-get-started/1-quick-start.md index 1c606bdbd..e0b2a7e3b 100644 --- a/docs/2-get-started/1-quick-start.md +++ b/docs/2-get-started/1-quick-start.md @@ -266,9 +266,9 @@ sidebar_position: 1 ![device-collect](./img/device-collect_1.png) - 选择需要采集的时间范围、采集路径、采集名称与记录名称，开始采集 + 选择需要采集的时间范围、采集路径、采集名称与记录名称，开始采集(或切换为按文件路径直接采集指定文件) - ![device-collect](./img/device-collect_2.png) + ![device-collect](./img/device-collect-time.png) - **采集时间范围** - 时间判断依据：文件的创建时间与最后修改时间 diff --git a/docs/2-get-started/img/device-collect-time.png b/docs/2-get-started/img/device-collect-time.png new file mode 100644 index 000000000..ab47d3b10 Binary files /dev/null and b/docs/2-get-started/img/device-collect-time.png differ diff --git a/docs/device/5-device-collect.md b/docs/device/5-device-collect.md index aeb5f75d9..ee82c9fa6 100644 --- a/docs/device/5-device-collect.md +++ b/docs/device/5-device-collect.md @@ -26,22 +26,32 @@ sidebar_position: 5 ![device-collect](./img/device-collect_1.png) -2. 选择需要采集的时间范围、采集路径、采集名称与记录名称，开始采集 - - ![device-collect](./img/device-collect_2.png) - - - **采集时间范围** - - 时间判断依据：文件的创建时间与最后修改时间 - - 注：部分文件系统可能无法获取文件创建时间，仅根据最后修改时间判断文件是否在时间范围内 - - **时间范围采集路径** - - 输入需要根据时间范围进行采集的绝对文件路径，如：`/home/bag/`，系统将采集该路径下（包括子文件夹）所有符合时间范围的文件 - - 建议在[组织设备配置](./4-device-collector.md#数据收集器设置collector)中，将该路径设置为默认采集路径`collect_dirs`，以便后续无需手动输入 - - **具体附加文件路径** - - 输入需要额外采集的绝对文件路径(文件夹/文件)，与时间范围无关，如：`/home/map/`、`/home/device/config.yaml`，系统将采集整个文件夹中的文件或指定的文件 - - 建议在[组织设备配置](./4-device-collector.md#数据收集器设置collector)中，将该路径设置为默认采集路径`additional_files`，以便后续无需手动输入 - - **采集名称&记录名称** - - 采集名称：用于标识该次采集 - - 记录名称：用于标识该次采集将数据保存到的记录 +2. 根据需要，选择按时间段采集/按文件路径采集 + + - **按时间段采集** + + 选择需要采集的时间范围与采集路径 + + ![device-collect](./img/device-collect-time.png) + + - **采集时间范围** + - 时间判断依据：文件的创建时间与最后修改时间 + - 注：部分文件系统可能无法获取文件创建时间，仅根据最后修改时间判断文件是否在时间范围内 + - **时间范围采集路径** + - 输入需要根据时间范围进行采集的绝对文件路径，如：`/home/bag/`，系统将采集该路径下（包括子文件夹）所有符合时间范围的文件 + - 建议在[组织设备配置](./4-device-collector.md#数据收集器设置collector)中，将该路径设置为默认采集路径`collect_dirs`，以便后续无需手动输入 + - **具体附加文件路径** + - 输入需要额外采集的绝对文件路径(文件夹/文件)，与时间范围无关，如：`/home/map/`、`/home/device/config.yaml`，系统将采集整个文件夹中的文件或指定的文件 + - 建议在[组织设备配置](./4-device-collector.md#数据收集器设置collector)中，将该路径设置为默认采集路径`additional_files`，以便后续无需手动输入 + - **采集名称&记录名称** + - 采集名称：用于标识该次采集 + - 记录名称：用于标识该次采集将数据保存到的记录 + + - **按文件路径采集** + + 输入需要采集的绝对文件路径(文件夹/文件)，如：`/home/map/`、`/home/device/config.yaml`，系统将采集整个文件夹中的文件或指定的文件 + + ![device-collect](./img/device-collect-path.png) 3. 采集过程中，可在设备执行历史中查看采集进度 diff --git a/docs/device/img/device-collect-path.png b/docs/device/img/device-collect-path.png new file mode 100644 index 000000000..2f2c64f3a Binary files /dev/null and b/docs/device/img/device-collect-path.png differ diff --git a/docs/device/img/device-collect-time.png b/docs/device/img/device-collect-time.png new file mode 100644 index 000000000..ab47d3b10 Binary files /dev/null and b/docs/device/img/device-collect-time.png differ diff --git a/docs/use-case/data-diagnosis/3-add-rule.md b/docs/use-case/data-diagnosis/3-add-rule.md index 71ee99afe..509e2fd7a 100644 --- a/docs/use-case/data-diagnosis/3-add-rule.md +++ b/docs/use-case/data-diagnosis/3-add-rule.md @@ -3,6 +3,7 @@ sidebar_position: 3 --- # 添加规则 + > 权限：仅**项目管理员**和**组织管理员**可管理规则，其他角色仅能查看规则内容 在项目设备的规则&定位页面，可添加规则，实现项目设备数据的自动监听与采集。 @@ -26,6 +27,7 @@ sidebar_position: 3 若有其他格式的时间戳需要支持的，请联系我们。 ## 添加规则 + 规则组是规则的集合，用于对规则进行分类管理。规则用于定义触发数据采集的条件以及触发后的操作。 在项目的「设备-规则&定位」页面，点击【添加规则组】 @@ -41,6 +43,7 @@ sidebar_position: 3 ![rule-info](./img/rule-info.png) ## 事件检测 + 检测新生成的文件/数据，当内容符合事件匹配条件时，触发事件上报。处理的内容如下： - 设备监听目录 `listen_dirs` 中的文件，详见[设备配置](../../device/4-device-collector.md) @@ -52,6 +55,7 @@ sidebar_position: 3 ![设备事件监听](./img/device-event-monitoring.png) ### 关注的话题 + > 建议将设备上的错误码统一发到一个 topic，如 /error_code topic，以便于实现标准化的错误码采集 系统默认提供了两个话题，分别是： @@ -61,13 +65,14 @@ sidebar_position: 3 若需配置更多选项，可点击【查看设备配置】前往组织的[设备配置](../../device/4-device-collector.md)中设置 - ![rule-topic](./img/rule-topic.png) +![rule-topic](./img/rule-topic.png) ### 匹配事件码表 + 在事件码表中，可定义事件的 code 值、事件名称、等级、解决方案等信息，用于在事件与一刻中展示对应的信息 - ![事件码表](./img/rule-eventlist.png) - ![预览事件码表](./img/errorcode-list.png) +![事件码表](./img/rule-eventlist.png) +![预览事件码表](./img/errorcode-list.png) - 事件码表必须包含 code 列，作为事件的唯一标识符，可根据实际情况增加或删除列 - 注：表头名称需为英文，且无空格 @@ -75,11 +80,12 @@ sidebar_position: 3 - 若要修改表内容，可先下载到本地电脑，删除规则中的原表后再上传修改后的表格 ### 规则触发条件 + 根据设备消息字段与某个值的匹配关系判断事件是否触发。 假设存在 topic `/error_status`（消息类型为 `std_msgs/string`），示例如下： - ![errortopic](./img/errortopic.png) +![errortopic](./img/errortopic.png) - 若要检测 `data` 字段中是否出现事件码表中的 code 值，即 `1001~1005`： - 填写：msg.data 包含 事件码表 code 列任一行的值 @@ -105,6 +111,7 @@ sidebar_position: 3 ![rule-simple-log](./img/rule-simple-log.png) ### 事件去重时长 + 若新事件（同一事件）在上次合并事件后的设定时间内发生，则与原事件合并。每次新事件发生时，都重置时间，直到超出时间窗口都无新事件发生时，完成合并。 - 支持范围设置在 1 秒 \~ 86400 秒（1 天）之间 @@ -112,14 +119,16 @@ sidebar_position: 3 ![事件去重设置](./img/event-deduplication.png) ## 触发操作 + 触发操作是指规则条件满足后执行的操作，包括采集数据、关键时刻定位。 ### 采集数据 + 设备端触发规则后，将自动采集对应时间的数据，并保存到记录。 该模块主要定义：上传文件时间范围、记录信息、采集限制、更多设置 - rule-collect-setting +rule-collect-setting - **上传文件的时间范围** - 定义需要采集触发时间点前后多长时间范围的文件。（数据采集目录的设置详见[设备配置](../../device/4-device-collector.md)） @@ -134,24 +143,26 @@ sidebar_position: 3 - 筛选文件范围： - 默认情况下，所有在指定时间范围内的数据采集目录中的文件都会被上传 - 支持利用[文件通配符](https://www.malikbrowne.com/blog/a-beginners-guide-glob-patterns/)设置上传白名单，对既定的文件上传清单进行二次筛选，仅上传在白名单中的文件，以减少设备流量开支 - - 具体附加文件：添加需要额外上传的设备文件绝对路径，一般为地图、配置文件等非实时产生的设备文件 + - 具体附加文件：添加需要额外上传的设备文件/文件夹绝对路径，一般为地图、配置文件等非实时产生的设备文件 规则触发的自动采集示例： - ![采集数据配置1](./img/data-collection-1.png) +![采集数据配置1](./img/data-collection-1.png) 采集数据自动上传至记录示例： - ![采集数据配置2](./img/data-collection-2.png) +![采集数据配置2](./img/data-collection-2.png) ### 关键时刻定位 + 设备或记录触发规则后，在记录中自动创建一刻，标记关键时间点 + - 从设备端采集数据保存到记录后，自动在规则触发时间点创建一刻 - 手动创建的记录可通过调用「数据定位」动作自动标记关键时间点。「数据定位」动作会聚合项目中勾选了「关键时刻定位」模块的所有规则，对记录中的文件进行规则匹配。 该模块主要定义：一刻信息、任务信息 -diagnosis-settings +diagnosis-settings - **一刻信息** - 定义触发时间点的一刻名称、描述、属性值等，支持使用代码变量（如：`{scope.code}`，详见下文） @@ -163,6 +174,7 @@ sidebar_position: 3 ![auto-record-3](./img/auto-record-3.png) ## 规则变量 + 在规则的触发操作中，支持使用变量或表达式来获取触发时的相关数据值。 以如下信息为例： @@ -171,20 +183,30 @@ sidebar_position: 3 ![errorcode-list](./img/errorcode-list.png) -- 触发事件为： +- 触发事件为 `/error_status` topic 中的消息： + + ``` + { + "code": "1001", + "message": "定位丢失", + "tags": ["定位问题", "版本:v1.0", "其他标签"], + "files": ["/home/coscene/20250808_1.bag", "/home/coscene/20250808_2.bag"] + } - ![errortopic](./img/errortopic.png) + ``` 规则变量书写规范见下表： -| 变量名 | 含义 | 示例 | -| --- | --- | --- | -| `{scope.code}` | 触发事件在事件码表中的 `code` 值 | `{scope.code}` 为 `1002` | -| `{scope.name}` | 触发事件在事件码表中对应行的 `name` 值 | `{scope.name}` 为 `目标点不可达！请协助` | -| `{msg}` | 触发规则的消息内容 | `{msg}` 为 `data:{"code": "1002", "message": "目标点不可达！请协助"}` | -| `{topic}` | 触发规则的话题 | `{topic}` 为 `/error_status` | -| `{ts}` | 触发规则时的时间戳 | `{ts}` 为 `1751436062.133` | -| `timestamp(ts).format("%Y-%m-%d %H:%M:%S", "America/New_York")` | 将时间戳转为格式为 `%Y-%m-%d %H:%M:%S`的纽约时区（西五区）时间 | `2025-02-07 03:09:40` | +| 变量名 | 含义 | 示例 | +| -------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------- | +| `{scope.code}` | 触发事件在事件码表中的 `code` 值 | `{scope.code}` 为 `1001` | +| `{scope.name}` | 触发事件在事件码表中对应行的 `name` 值 | `{scope.name}` 为 `定位丢失` | +| `{msg}` | 触发规则的消息内容 | `{msg}` 为整条消息的内容 | +| `{msg.tags}` | 触发规则的消息中的 `tags` 字段值 | `{msg.tags}` 为`"定位问题","版本:v1.0","其他标签"` | +| `{msg.files}` | 触发规则的消息中的 `files` 字段值 | `{msg.files}` 为`"/home/coscene/20250808_1.bag","/home/coscene/20250808_2.bag"` | +| `{topic}` | 触发规则的话题 | `{topic}` 为 `/error_status` | +| `{ts}` | 触发规则时的时间戳 | `{ts}` 为 `1751436062.133` | +| `{timestamp(ts).format("%Y-%m-%d %H:%M:%S", "Asia/Shanghai")}` | 将时间戳转为格式为 `%Y-%m-%d %H:%M:%S`的上海时区时间 | `2025-07-02 14:01:02` | **注意：** @@ -192,6 +214,39 @@ sidebar_position: 3 - 在非规则条件中使用变量或表达式时，例如记录名称，记录描述等，请用 `{}` 包裹。 - 表达式的语法遵循 [CEL 语法](https://github.com/google/cel-spec/blob/master/doc/langdef.md) +规则变量的使用示例如下： + +1. **记录名称：** + - 输入：错误码:`{scope.code} @ {timestamp(ts).format("%Y-%m-%d %H:%M:%S", "Asia/Shanghai")}` + - 输出：错误码:1001 @ 2025-07-02 14:01:02 + +2. **记录描述** + - 输入：`{msg.message}` + - 输出：定位丢失 + +3. **记录标签** + - 输入：`{msg.tags}` + - 若输入的消息字段类型为**数组/单个 string**，则可自动将其内容解析为记录标签 + - 输出：定位问题，版本:v1.0，其他标签 + +4. **更多设置-具体附加文件** + - 输入：`{msg.files}` + - 若输入的消息字段类型为**数组**，则可自动将其中的文件清单解析为附加文件进行上传 + - 若仅需上传消息中定义的文件清单`{msg.files}`，则无需在「组织-设备-设备配置」页面中设置采集路径 `collect_dirs` + - 输出：/home/coscene/20250808_1.bag,/home/coscene/20250808_2.bag + +5. **一刻名称** + - 输入：`{scope.code}-{scope.name}` + - 输出：1001-定位丢失 + +6. **一刻属性** + - 输入： + - 属性名称输入：错误等级 + - 属性值输入：`{scope.level}` + - 输出： + - 属性名称：错误等级 + - 属性值：P1 + ### 自定义函数 除了 [CEL 语法](https://github.com/google/cel-spec/blob/master/doc/langdef.md) 支持的函数，还额外支持了以下函数(以下定义参照 CEL) @@ -223,6 +278,6 @@ sidebar_position: 3 - 时区支持 `UTC`、`Asia/Shanghai`、`America/New_York` 等 IANA 规范的时区，[了解更多](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) ## 后续操作 + - [调试并启用规则](./4-manage-rule-group.md) - [添加设备](../../device/2-create-device.md) - diff --git a/i18n/en/docusaurus-plugin-content-docs/current/2-get-started/1-quick-start.md b/i18n/en/docusaurus-plugin-content-docs/current/2-get-started/1-quick-start.md index 45cfcee8d..3900893f3 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/2-get-started/1-quick-start.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/2-get-started/1-quick-start.md @@ -203,9 +203,9 @@ Devices can establish connections with real devices as data collection targets. ![create-collection-task](./img/device-collect_1.png) - Choose the time range, collection path, collection name, and record name to begin data collection. + Choose the time range, collection path, collection name, and record name to begin data collection.(Or switch to collecting specified files directly by file path) - ![create-collection-task](./img/device-collect_2.png) + ![create-collection-task](./img/device-collect-time.png) - Time Range for Collection - Time basis: file creation time and last modified time diff --git a/i18n/en/docusaurus-plugin-content-docs/current/2-get-started/img/device-collect-time.png b/i18n/en/docusaurus-plugin-content-docs/current/2-get-started/img/device-collect-time.png new file mode 100644 index 000000000..eca1996f9 Binary files /dev/null and b/i18n/en/docusaurus-plugin-content-docs/current/2-get-started/img/device-collect-time.png differ diff --git a/i18n/en/docusaurus-plugin-content-docs/current/device/5-device-collect.md b/i18n/en/docusaurus-plugin-content-docs/current/device/5-device-collect.md index 8843ecffd..06717bbc3 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/device/5-device-collect.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/device/5-device-collect.md @@ -29,24 +29,32 @@ Collect existing files from devices including logs, images, and configurations. ![pro-device](./img/pro-device.png) ![device-collect](./img/device-collect_1.png) -2. Configure parameters: - - ![device-collect](./img/device-collect_2.png) - - - **Time Range** - - Based on file creation/modification timestamps (Note: Some filesystems may not provide creation time) - - - **Collection Path** - - Absolute path (e.g., `/home/bag/`) - - Recommend pre-configuring in [Device configuration](./4-device-collector.md#collection-rule-format-details) - - - **Additional Files** - - Paths to collect regardless of time (files/directories) - - Pre-configure in [Device configuration](./4-device-collector.md#collection-rule-format-details) - - - **Naming Convention** - - Collection Name: Identifier for collection job - - Record Name: Target storage record +2. Depending on your needs, choose to collect data by time range or by file path. + + - **Collect by time range** + + ![device-collect](./img/device-collect-time.png) + + - **Time Range** + - Based on file creation/modification timestamps (Note: Some filesystems may not provide creation time) + + - **Collection Path** + - Absolute path (e.g., `/home/bag/`) + - Recommend pre-configuring in [Device configuration](./4-device-collector.md#collection-rule-format-details) + + - **Additional Files** + - Paths to collect regardless of time (files/directories) + - Pre-configure in [Device configuration](./4-device-collector.md#collection-rule-format-details) + + - **Naming Convention** + - Collection Name: Identifier for collection job + - Record Name: Target storage record + + - **Collect by file path** + + Enter the absolute file path to be collected (folder/file), for example: `/home/map/` or `/home/device/config.yaml`. The system will collect all files in the folder or the specified file. + + ![device-collect](./img/device-collect-path.png) 3. During the collection process, you can view the progress in the device execution history. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/device/img/device-collect-path.png b/i18n/en/docusaurus-plugin-content-docs/current/device/img/device-collect-path.png new file mode 100644 index 000000000..21d59309a Binary files /dev/null and b/i18n/en/docusaurus-plugin-content-docs/current/device/img/device-collect-path.png differ diff --git a/i18n/en/docusaurus-plugin-content-docs/current/device/img/device-collect-time.png b/i18n/en/docusaurus-plugin-content-docs/current/device/img/device-collect-time.png new file mode 100644 index 000000000..eca1996f9 Binary files /dev/null and b/i18n/en/docusaurus-plugin-content-docs/current/device/img/device-collect-time.png differ diff --git a/i18n/en/docusaurus-plugin-content-docs/current/use-case/data-diagnosis/3-add-rule.md b/i18n/en/docusaurus-plugin-content-docs/current/use-case/data-diagnosis/3-add-rule.md index df950be97..f709b0ba7 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/use-case/data-diagnosis/3-add-rule.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/use-case/data-diagnosis/3-add-rule.md @@ -3,6 +3,7 @@ sidebar_position: 3 --- # Add Rule + > **Permissions**: Only **Project Admins** and **Organization Admins** can manage rules. Other roles can only view rule content. On the "Rules & matching" page of project devices, you can add rules to automatically monitor and collect data from project devices. @@ -45,13 +46,12 @@ Rules consist of **Basic info**, **Event detection**, and **Trigger action**: Monitor newly generated files/data. If the content matches the event condition, an event is triggered and reported. Handled content includes: -* Files in the device's `listen_dirs`, see [Device Configuration](../../device/4-device-collector.md) -* Messages from a specific device-side topic - - * Requires installation and activation of the ROS suite, see [Add Device](../../device/2-create-device.md) -* Files within a record +- Files in the device's `listen_dirs`, see [Device Configuration](../../device/4-device-collector.md) +- Messages from a specific device-side topic + - Requires installation and activation of the ROS suite, see [Add Device](../../device/2-create-device.md) - * Requires using the **Data matching** action within the record to detect events +- Files within a record + - Requires using the **Data matching** action within the record to detect events ![Device Event Monitoring](./img/device-event-monitoring.png) @@ -61,8 +61,8 @@ Monitor newly generated files/data. If the content matches the event condition, The system provides two default topics: -* `/error_status`: For use with the **Error code collection rule** template, see [Get Started with Rule Collection](./2-get-started.md) -* `/external_log`: For handling `.log` files that meet certain conditions +- `/error_status`: For use with the **Error code collection rule** template, see [Get Started with Rule Collection](./2-get-started.md) +- `/external_log`: For handling `.log` files that meet certain conditions To configure more options, click **View device configuration** to go to the [Device Configuration](../../device/4-device-collector.md) page. @@ -75,11 +75,10 @@ The event code table defines event `code`, name, severity, and resolution, used ![Event Code Table](./img/rule-eventlist.png) ![Preview Code Table](./img/errorcode-list.png) -* The code table **must contain a `code` column** as the event's unique identifier. Other columns are optional. - -* After uploading the table (supports JSON or CSV), you can preview, download, or delete it. +- The code table **must contain a `code` column** as the event's unique identifier. Other columns are optional. - * To modify, download the original, delete it from the rule, and upload the modified file. +- After uploading the table (supports JSON or CSV), you can preview, download, or delete it. + - To modify, download the original, delete it from the rule, and upload the modified file. ### Rule Trigger Conditions @@ -89,30 +88,26 @@ Assume topic `/error_status` with message type `std_msgs/String`, for example: ![errortopic](./img/errortopic.png) -* To detect if `data` contains any value from the event code table: - - * Input: `msg.data contains the value of the code column` +- To detect if `data` contains any value from the event code table: + - Input: `msg.data contains the value of the code column` ![rule-simple](./img/rule-simple.png) -* To detect if `data` equals a specific code `1001`: - - * Switch to fixed value input - * Input: `msg.data equals 1001` +- To detect if `data` equals a specific code `1001`: + - Switch to fixed value input + - Input: `msg.data equals 1001` ![rule-simple-value](./img/rule-simple-value.png) -* If `data` is an array and needs to check for any match with the code column: +- If `data` is an array and needs to check for any match with the code column: + - Switch to code mode + - Input: `msg.data.exists(x, x.code.contains(scope.code))` - * Switch to code mode - * Input: `msg.data.exists(x, x.code.contains(scope.code))` + ![rule-code_1](./img/rule-code_1.png) + ![rule-code_2](./img/rule-code_2.png) - ![rule-code\_1](./img/rule-code_1.png) - ![rule-code\_2](./img/rule-code_2.png) - -* To detect if a log contains keyword `error 1`: - - * Input: `msg.message contains error 1` and select `/external_log` as the monitored topic +- To detect if a log contains keyword `error 1`: + - Input: `msg.message contains error 1` and select `/external_log` as the monitored topic ![rule-simple-log](./img/rule-simple-log.png) @@ -120,7 +115,7 @@ Assume topic `/error_status` with message type `std_msgs/String`, for example: If a new event (of the same type) occurs within a set time since the last event merge, it will be merged. The timer resets with each new occurrence, and final merge completes after no further events occur within the window. -* Supported range: 1 to 86400 seconds (1 day) +- Supported range: 1 to 86400 seconds (1 day) ![Event Deduplication](./img/event-deduplication.png) @@ -136,26 +131,24 @@ This module defines: file time range, record info, collection limits, and more s rule-collect-setting -* **Upload Time Range** - - * Defines how much time before and after the trigger time to collect files. -* **Record Info** +- **Upload Time Range** + - Defines how much time before and after the trigger time to collect files. - * Set record name, description, and labels. Name/description can use variables (e.g., `{scope.code}`, see below). - * The tag `uploaded` is automatically added once data is uploaded. -* **Collection Limits** +- **Record Info** + - Set record name, description, and labels. Name/description can use variables (e.g., `{scope.code}`, see below). + - The tag `uploaded` is automatically added once data is uploaded. - * Define max number of uploads per day per device or across all devices for repeated events. - * Recommended to set limits to avoid excessive uploads. -* **More Settings** +- **Collection Limits** + - Define max number of uploads per day per device or across all devices for repeated events. + - Recommended to set limits to avoid excessive uploads. - * File Filtering: +- **More Settings** + - File Filtering: + - By default, all files in the data directory during the time window are uploaded. + - Use [glob pattern](https://www.malikbrowne.com/blog/a-beginners-guide-glob-patterns/) to whitelist specific files. - * By default, all files in the data directory during the time window are uploaded. - * Use [glob pattern](https://www.malikbrowne.com/blog/a-beginners-guide-glob-patterns/) to whitelist specific files. - * Additional Files: - - * Specify absolute paths of extra files to upload (e.g., maps, config files). + - Additional Files: + - Specify absolute paths of extra files/folder to upload (e.g., maps, config files). Data collection example: @@ -169,19 +162,18 @@ Data auto-uploaded to record example: After rule is triggered, a **Moment** is automatically created in the record to mark a critical time point. -* After collecting data into a record, a Moment is created at the trigger timestamp. -* For manually created records, invoking the **Data matching** action will match against rules marked with **Key moment identification**. +- After collecting data into a record, a Moment is created at the trigger timestamp. +- For manually created records, invoking the **Data matching** action will match against rules marked with **Key moment identification**. This module defines: Moment Info and Task Info diagnosis-settings -* **Moment Info** - - * Define name, description, and attributes of the moment. Supports variables (e.g., `{scope.code}`). -* **Task Info** +- **Moment Info** + - Define name, description, and attributes of the moment. Supports variables (e.g., `{scope.code}`). - * Configure task creation, assignee, and [syncing to ticket systems](../../3-collaboration/integration/1-jira-integration.md). +- **Task Info** + - Configure task creation, assignee, and [syncing to ticket systems](../../3-collaboration/integration/1-jira-integration.md). Auto-created moment example: @@ -193,54 +185,94 @@ You can use variables/expressions in rule actions to reference values at the tim Example: -* Event Code Table: +- Event Code Table: ![errorcode-list](./img/errorcode-list.png) -* Triggered Event: +- The triggered event is a message from the `/error_status` topic: - ![errortopic](./img/errortopic.png) + ``` + { + "code": "1001", + "message": "Positioning lost", + "label": ["Positioning issue","Version:v1.0","Other tags"], + "files": ["/home/coscene/20250808_1.bag","/home/coscene/20250808_2.bag"] + } + ``` Variable reference table: -| Variable | Meaning | Example | -| --------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------ | -| `{scope.code}` | The `code` of the event from the event code table | `1002` | -| `{scope.name}` | The `name` of the corresponding event | `Target unreachable! Please assist.` | -| `{msg}` | The triggered message content | `data:{"code": "1002", "message": "Target unreachable! Please assist."}` | -| `{topic}` | The triggered topic | `/error_status` | -| `{ts}` | The trigger timestamp | `1751436062.133` | -| `timestamp(ts).format("%Y-%m-%d %H:%M:%S", "America/New_York")` | Format timestamp to New York time | `2025-02-07 03:09:40` | +| Variable | Meaning | Example | +| ----------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------- | +| `{scope.code}` | The `code` of the event from the event code table | `1001` | +| `{scope.name}` | The `name` of the corresponding event | `Positioning lost` | +| `{msg}` | The message content that triggered the rule | `{msg}` represents the entire message content | +| `{msg.label}` | The value of the `label` field in the message that triggered the rule | `{msg.label}` = `"Positioning issue","Version:v1.0","Other tags"` | +| `{msg.files}` | The value of the `files` field in the message that triggered the rule | `{msg.files}` = `"/home/coscene/20250808_1.bag","/home/coscene/20250808_2.bag"` | +| `{topic}` | The triggered topic | `/error_status` | +| `{ts}` | The trigger timestamp | `1751436062.133` | +| `{timestamp(ts).format("%Y-%m-%d %H:%M:%S", "America/New_York")}` | Format timestamp to New York time | `2025-07-02 02:01:02` | **Note:** -* When used in rule **conditions**, write the variable directly (no `{}`). -* When used in **non-conditions**, like record name/description, use `{}`. -* Expressions follow [CEL syntax](https://github.com/google/cel-spec/blob/master/doc/langdef.md). +- When used in rule **conditions**, write the variable directly (no `{}`). +- When used in **non-conditions**, like record name/description, use `{}`. +- Expressions follow [CEL syntax](https://github.com/google/cel-spec/blob/master/doc/langdef.md). + +Example usage of rule variables: + +1. **Record Name** + - Input: Error Code:`{scope.code} @ {timestamp(ts).format("%Y-%m-%d %H:%M:%S", "Asia/Shanghai")}` + - Output: Error Code:1001 @ 2025-07-02 14:01:02 + +2. **Record Description** + - Input: `{msg.message}` + - Output: Positioning lost + +3. **Record label** + - Input: `{msg.label}` + - If the message field type is an array/single string, its content can be automatically parsed as record label + - Output: Positioning issue, Version:v1.0, Other tags + +4. **More Settings – Specific Attached Files** + - Input: `{msg.files}` + - If the message field type is an array, the file list inside it can be automatically parsed as attached files for upload + - If you only need to upload the file list defined in the message `{msg.files}`, there is no need to configure the collection path `collect_dirs` in Organization → Device → Device Configuration + - Output: /home/coscene/20250808_1.bag, /home/coscene/20250808_2.bag + +5. **Moment Name** + - Input: `{scope.code}-{scope.name}` + - Output: 1001-Positioning Lost + +6. **Moment Attributes** + - Input: + - Attribute Name Input: Error Level + - Attribute Value Input: `{scope.level}` + - Output: + - Attribute Name: Error Level + - Attribute Value: P1 ### Custom Functions In addition to [CEL syntax](https://github.com/google/cel-spec/blob/master/doc/langdef.md), the following functions are also supported: -* **timestamp** – Convert various types to timestamp +- **timestamp** – Convert various types to timestamp + - Signature: + - `timestamp(double) -> google.protobuf.Timestamp` - * Signature: - - * `timestamp(double) -> google.protobuf.Timestamp` - * Example: + - Example: ```cel timestamp(1738915780.123) -> timestamp("2025-02-07T08:09:40.123") ``` -* **format** – Format timestamp as a string - - * Signature: +- **format** – Format timestamp as a string + - Signature: + - `google.protobuf.Timestamp.format(string) -> string` + - `google.protobuf.Timestamp.format(string, string) -> string` + - `google.protobuf.Timestamp.format(string, int) -> string` - * `google.protobuf.Timestamp.format(string) -> string` - * `google.protobuf.Timestamp.format(string, string) -> string` - * `google.protobuf.Timestamp.format(string, int) -> string` - * Example: + - Example: ```cel timestamp("2025-02-07T08:09:40.123").format("%Y-%m-%d %H:%M:%S") -> "UTC: 2025-02-07 08:09:40" @@ -250,10 +282,10 @@ In addition to [CEL syntax](https://github.com/google/cel-spec/blob/master/doc/l **Note:** -* Timestamp format strings follow `man 3 strftime` ([learn more](https://linux.die.net/man/3/strftime)) -* Timezones support [IANA standard names](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) +- Timestamp format strings follow `man 3 strftime` ([learn more](https://linux.die.net/man/3/strftime)) +- Timezones support [IANA standard names](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) ## Next Steps -* [Debug and Enable Rules](./4-manage-rule-group.md) -* [Add Device](../../device/2-create-device.md) +- [Debug and Enable Rules](./4-manage-rule-group.md) +- [Add Device](../../device/2-create-device.md)