This is an automated email from the ASF dual-hosted git repository. zhaoqingran pushed a commit to branch xml in repository https://gitbox.apache.org/repos/asf/hertzbeat.git
commit 32f38222758ab7cf66a389cff2073a28ab5f2099 Author: Logic <[email protected]> AuthorDate: Thu Apr 3 16:44:25 2025 +0800 feat(monitor): add Hikvision ISAPI monitoring support - Add monitoring template for Hikvision ISAPI in app-hikvision_isapi.yml- Create new XML parsing guide in extend-http-xmlpath.md - Update sidebar to include Hikvision ISAPI in server category - Add help document for Hikvision ISAPI monitoring --- .../main/resources/define/app-hikvision_isapi.yml | 2 +- .../docs/advanced/extend-http-xmlpath.md | 140 +++++++++++---------- .../current/advanced/extend-http-xmlpath.md | 140 +++++++++++---------- .../current/help/hikvision_isapi.md | 58 +++++++++ home/sidebars.json | 6 +- 5 files changed, 210 insertions(+), 136 deletions(-) diff --git a/hertzbeat-manager/src/main/resources/define/app-hikvision_isapi.yml b/hertzbeat-manager/src/main/resources/define/app-hikvision_isapi.yml index 73bd4d0e57..b20eaa4da0 100644 --- a/hertzbeat-manager/src/main/resources/define/app-hikvision_isapi.yml +++ b/hertzbeat-manager/src/main/resources/define/app-hikvision_isapi.yml @@ -14,7 +14,7 @@ # limitations under the License. # The monitoring type category：service-application service monitoring db-database monitoring custom-custom monitoring os-operating system monitoring -category: service +category: server # The monitoring type eg: linux windows tomcat mysql aws... app: hikvision_isapi # The monitoring i18n name diff --git a/hertzbeat-manager/src/main/resources/define/app-hikvision_isapi.yml b/home/docs/advanced/extend-http-xmlpath.md similarity index 60% copy from hertzbeat-manager/src/main/resources/define/app-hikvision_isapi.yml copy to home/docs/advanced/extend-http-xmlpath.md index 73bd4d0e57..80ef18b8d5 100644 --- a/hertzbeat-manager/src/main/resources/define/app-hikvision_isapi.yml +++ b/home/docs/advanced/extend-http-xmlpath.md @@ -1,20 +1,76 @@ -# Licensed to the Apache Software Foundation (ASF) under one or more -# contributor license agreements. See the NOTICE file distributed with -# this work for additional information regarding copyright ownership. -# The ASF licenses this file to You under the Apache License, Version 2.0 -# (the "License"); you may not use this file except in compliance with -# the License. You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -# The monitoring type category：service-application service monitoring db-database monitoring custom-custom monitoring os-operating system monitoring -category: service +--- +id: extend-http-xmlpath +title: HTTP Protocol XmlPath Parsing Method +sidebar_label: XmlPath Parsing Method +--- + +> After calling the HTTP API to obtain the response data, use the XmlPath script parsing method to parse the response data. + +Note⚠️ The response data must be in XML format. + +**Use XPath scripts to parse the response data into data that conforms to the data structure rules specified by HertzBeat.** + +### XmlPath Parsing Logic + +The XmlPath parsing method in HertzBeat uses a two-step XPath process: + +1. **Main XPath Expression (`parseScript`)**: This XPath expression is defined in the `http` configuration section under `parseScript`. It is used to select one or more main XML nodes from the response. Each selected node will correspond to one row of metric data in HertzBeat. +2. **Relative Field XPath Expressions (`xpath`)**: For each metric field defined in the `fields` list, you can specify a relative `xpath`. This XPath expression is evaluated *relative to each main node* selected by the `parseScript` in step 1. It extracts the specific value for that metric field from the current main node. + +This allows you to easily parse structured XML data where multiple records or items are present. + +**Special Metrics**: +* `responseTime`: This built-in metric represents the HTTP request's response time and is automatically collected. It does not require an `xpath`. +* `keyword`: This built-in metric counts the occurrences of a specified keyword (configured in `http.keyword`) in the raw response body. It does not require an `xpath`. + +### Example + +Assume the HTTP API returns the following XML data: + +```xml +<DeviceStatus xmlns="http://www.isapi.org/ver20/XMLSchema"; version="2.0"> + <CPUList> + <CPU> + <cpuUtilization>36.400002</cpuUtilization> + </CPU> + </CPUList> + <MemoryList> + <Memory> + <memoryUsage>399640</memoryUsage> + <memoryAvailable>98792</memoryAvailable> + <cacheSize>228492</cacheSize> + </Memory> + </MemoryList> + <NetPortStatusList> + <NetPortStatus> + <id>1</id> + <workSpeed>1000</workSpeed> + </NetPortStatus> + <NetPortStatus> + <id>2</id> + <workSpeed>0</workSpeed> + </NetPortStatus> + </NetPortStatusList> + <bootTime>2025-01-06 10:27:48</bootTime> + <deviceUpTime>87天0时55分59秒</deviceUpTime> + <lastCalibrationTime>2025-04-03 11:09:18</lastCalibrationTime> + <lastCalibrationTimeDiff>1</lastCalibrationTimeDiff> + <uploadTimeConsumingList> + <avgTime>16</avgTime> + <maxTime>23</maxTime> + <minTime>12</minTime> + </uploadTimeConsumingList> + <lastCalibrationTimeMode>NTP</lastCalibrationTimeMode> + <lastCalibrationTimeAddress>34.191.45.101</lastCalibrationTimeAddress> +</DeviceStatus> +``` + +We want to monitor the device status and extract various metrics. + +Here's how you would configure the monitoring template YML: + +```yaml +category: server # The monitoring type eg: linux windows tomcat mysql aws... app: hikvision_isapi # The monitoring i18n name @@ -72,56 +128,6 @@ params: # collect metrics config list metrics: - - name: system_info - i18n: - zh-CN: 系统信息 - en-US: System Info - priority: 0 - protocol: http - http: - host: ^_^host^_^ - port: ^_^port^_^ - ssl: ^_^ssl^_^ - url: /ISAPI/System/deviceInfo - method: GET - timeout: ^_^timeout^_^ - authorization: - type: Digest Auth - digestAuthUsername: ^_^username^_^ - digestAuthPassword: ^_^password^_^ - parseType: xmlPath - parseScript: 'DeviceInfo' - fields: - - field: deviceName - type: 1 - i18n: - zh-CN: 设备名称 - en-US: Device Name - xpath: deviceName - - field: deviceID - type: 1 - i18n: - zh-CN: 设备ID - en-US: Device ID - xpath: deviceID - - field: firmwareVersion - type: 1 - i18n: - zh-CN: 固件版本 - en-US: Firmware Version - xpath: firmwareVersion - - field: model - type: 1 - i18n: - zh-CN: 设备型号 - en-US: Device Model - xpath: model - - field: macAddress - type: 1 - i18n: - zh-CN: mac地址 - en-US: Mac Address - xpath: macAddress - name: status protocol: http http: diff --git a/hertzbeat-manager/src/main/resources/define/app-hikvision_isapi.yml b/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/advanced/extend-http-xmlpath.md similarity index 62% copy from hertzbeat-manager/src/main/resources/define/app-hikvision_isapi.yml copy to home/i18n/zh-cn/docusaurus-plugin-content-docs/current/advanced/extend-http-xmlpath.md index 73bd4d0e57..b6956b8800 100644 --- a/hertzbeat-manager/src/main/resources/define/app-hikvision_isapi.yml +++ b/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/advanced/extend-http-xmlpath.md @@ -1,20 +1,76 @@ -# Licensed to the Apache Software Foundation (ASF) under one or more -# contributor license agreements. See the NOTICE file distributed with -# this work for additional information regarding copyright ownership. -# The ASF licenses this file to You under the Apache License, Version 2.0 -# (the "License"); you may not use this file except in compliance with -# the License. You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -# The monitoring type category：service-application service monitoring db-database monitoring custom-custom monitoring os-operating system monitoring -category: service +--- +id: extend-http-xmlpath +title: HTTP 协议 XmlPath 解析方法 +sidebar_label: XmlPath 解析方法 +--- + +> 调用 HTTP API 获取响应数据后，使用 XmlPath 脚本解析方法解析响应数据。 + +注意⚠️ 响应数据必须是 XML 格式。 + +**使用 XPath 脚本将响应数据解析为符合 HertzBeat 指定的数据结构规则的数据。** + +### XmlPath 解析逻辑 + +HertzBeat 中的 XmlPath 解析方法使用两步 XPath 处理： + +1. **主 XPath 表达式 (`parseScript`)**: 此 XPath 表达式在 `http` 配置部分的 `parseScript` 中定义。它用于从响应中选择一个或多个主要的 XML 节点。每个选中的节点将对应 HertzBeat 中的一行指标数据。 +2. **相对字段 XPath 表达式 (`xpath`)**: 对于在 `fields` 列表中定义的每个指标字段，您可以指定一个相对的 `xpath`。此 XPath 表达式是*相对于*步骤 1 中 `parseScript` 选择的每个主节点进行评估的。它从当前主节点中提取该指标字段的具体值。 + +这使您可以轻松地解析包含多个记录或项目的结构化 XML 数据。 + +**特殊指标**: +* `responseTime`: 这个内置指标代表 HTTP 请求的响应时间，是自动收集的。它不需要 `xpath`。 +* `keyword`: 这个内置指标计算原始响应体中指定关键字（在 `http.keyword` 中配置）的出现次数。它不需要 `xpath`。 + +### 示例 + +假设 HTTP API 返回以下 XML 数据： + +```xml +<DeviceStatus xmlns="http://www.isapi.org/ver20/XMLSchema"; version="2.0"> + <CPUList> + <CPU> + <cpuUtilization>36.400002</cpuUtilization> + </CPU> + </CPUList> + <MemoryList> + <Memory> + <memoryUsage>399640</memoryUsage> + <memoryAvailable>98792</memoryAvailable> + <cacheSize>228492</cacheSize> + </Memory> + </MemoryList> + <NetPortStatusList> + <NetPortStatus> + <id>1</id> + <workSpeed>1000</workSpeed> + </NetPortStatus> + <NetPortStatus> + <id>2</id> + <workSpeed>0</workSpeed> + </NetPortStatus> + </NetPortStatusList> + <bootTime>2025-01-06 10:27:48</bootTime> + <deviceUpTime>87天0时55分59秒</deviceUpTime> + <lastCalibrationTime>2025-04-03 11:09:18</lastCalibrationTime> + <lastCalibrationTimeDiff>1</lastCalibrationTimeDiff> + <uploadTimeConsumingList> + <avgTime>16</avgTime> + <maxTime>23</maxTime> + <minTime>12</minTime> + </uploadTimeConsumingList> + <lastCalibrationTimeMode>NTP</lastCalibrationTimeMode> + <lastCalibrationTimeAddress>34.191.45.101</lastCalibrationTimeAddress> +</DeviceStatus> +``` + +我们想要监控设备状态并提取各种指标。 + +以下是您将如何配置监控模板 YML： + +```yaml +category: server # The monitoring type eg: linux windows tomcat mysql aws... app: hikvision_isapi # The monitoring i18n name @@ -72,56 +128,6 @@ params: # collect metrics config list metrics: - - name: system_info - i18n: - zh-CN: 系统信息 - en-US: System Info - priority: 0 - protocol: http - http: - host: ^_^host^_^ - port: ^_^port^_^ - ssl: ^_^ssl^_^ - url: /ISAPI/System/deviceInfo - method: GET - timeout: ^_^timeout^_^ - authorization: - type: Digest Auth - digestAuthUsername: ^_^username^_^ - digestAuthPassword: ^_^password^_^ - parseType: xmlPath - parseScript: 'DeviceInfo' - fields: - - field: deviceName - type: 1 - i18n: - zh-CN: 设备名称 - en-US: Device Name - xpath: deviceName - - field: deviceID - type: 1 - i18n: - zh-CN: 设备ID - en-US: Device ID - xpath: deviceID - - field: firmwareVersion - type: 1 - i18n: - zh-CN: 固件版本 - en-US: Firmware Version - xpath: firmwareVersion - - field: model - type: 1 - i18n: - zh-CN: 设备型号 - en-US: Device Model - xpath: model - - field: macAddress - type: 1 - i18n: - zh-CN: mac地址 - en-US: Mac Address - xpath: macAddress - name: status protocol: http http: diff --git a/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/hikvision_isapi.md b/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/hikvision_isapi.md new file mode 100644 index 0000000000..57139c6906 --- /dev/null +++ b/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/hikvision_isapi.md @@ -0,0 +1,58 @@ +--- +id: hikvision_isapi +title: 监控 海康ISAPI +sidebar_label: 海康ISAPI +keywords: [ monitor, hikvision_isapi, 海康 ] +--- + +> 通过ISAPI接口监控海康威视设备状态，获取设备健康数据。 + +## 监控配置参数 + +| 参数名称 | 参数帮助描述 | +| ----------- | ----------- | +| 监控Host | 被监控的对端IP或域名。注意⚠️不带协议头(eg: https://, http://)。 | +| 监控名称 | 标识此监控的名称，名称需要保证唯一性。 | +| 端口 | 网络请求端口，默认为80。 | +| 超时时间 | 设置超时时间，单位ms毫秒，默认5000毫秒。 | +| 用户名 | 海康设备登录用户名。 | +| 密码 | 海康设备登录密码。 | +| 启用HTTPS | 是否启用HTTPS，默认未启用。 | +| 采集间隔 | 监控周期性采集数据间隔时间，单位秒，可设置的最小间隔为30秒 | + +## 采集指标 + +### 系统信息 + +- 设备名称 +- 设备ID +- 固件版本 +- 设备型号 +- mac地址 + +### 设备状态 + +- CPU 利用率(%) +- 内存使用量(MB) +- 可用内存(MB) +- 缓存大小(MB) +- 网口1速度(Mbps) +- 网口2速度(Mbps) +- 启动时间 +- 运行时长 +- 上次校时时间 +- 上次校时时间差(s) +- 平均上传耗时(ms) +- 最大上传耗时(ms) +- 最小上传耗时(ms) +- 上次校时模式 +- 上次校时地址 +- 响应时间(ms) + +## 监控实现原理 + +通过海康威视设备的ISAPI接口获取设备信息和状态： +1. 采集系统信息：`/ISAPI/System/deviceInfo` +2. 采集设备状态：`/ISAPI/System/status` + +采用HTTP协议Digest认证方式访问接口，解析XML格式响应数据获取监控指标。 \ No newline at end of file diff --git a/home/sidebars.json b/home/sidebars.json index f0b8f681d4..c5a590a2ee 100755 --- a/home/sidebars.json +++ b/home/sidebars.json @@ -145,7 +145,10 @@ { "type": "category", "label": "server", - "items": ["help/ipmi"] + "items": [ + "help/ipmi", + "help/hikvision_isapi" + ] }, { "type": "category", @@ -272,6 +275,7 @@ "advanced/extend-http", "advanced/extend-http-default", "advanced/extend-http-jsonpath", + "advanced/extend-http-xmlpath", "advanced/extend-http-example-hertzbeat", "advanced/extend-http-example-token" ] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
