wehub/apache--hertzbeat
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity

chore: import upstream snapshot with attribution
MCP Bash Server CI / Test MCP Bash Server (dev) (push) Has been cancelled
Details
MCP Bash Server CI / Test MCP Bash Server (release) (push) Has been cancelled
Details

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 13:11:39 +08:00
commit c8cebdfeee
4654 changed files with 626756 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
home/docs/start/account-modify.md
+158
View File
@@ -0,0 +1,158 @@
---
id: account-modify
title: Modify Account Username Password And Secret
sidebar_label: Update Account Secret
---
## Update Account
Apache HertzBeat™ default built-in three user accounts, respectively admin/hertzbeat tom/hertzbeat guest/hertzbeat
If you need add, delete or modify account or password, configure `sureness.yml`. Ignore this step without this demand.
Modify the following **part parameters** in sureness.yml：**[Note⚠️Other default sureness configuration parameters should be retained]**
```yaml
resourceRole:
- /api/account/auth/refresh===post===[admin,user,guest]
- /api/apps/**===get===[admin,user,guest]
- /api/monitor/**===get===[admin,user,guest]
- /api/monitor/**===post===[admin,user]
- /api/monitor/**===put===[admin,user]
- /api/monitor/**===delete==[admin]
- /api/monitors/**===get===[admin,user,guest]
- /api/monitors/**===post===[admin,user]
- /api/monitors/**===put===[admin,user]
- /api/monitors/**===delete===[admin]
- /api/alert/**===get===[admin,user,guest]
- /api/alert/**===post===[admin,user]
- /api/alert/**===put===[admin,user]
- /api/alert/**===delete===[admin]
- /api/alerts/**===get===[admin,user,guest]
- /api/alerts/**===post===[admin,user]
- /api/alerts/**===put===[admin,user]
- /api/alerts/**===delete===[admin]
- /api/notice/**===get===[admin,user,guest]
- /api/notice/**===post===[admin,user]
- /api/notice/**===put===[admin,user]
- /api/notice/**===delete===[admin]
- /api/tag/**===get===[admin,user,guest]
- /api/tag/**===post===[admin,user]
- /api/tag/**===put===[admin,user]
- /api/tag/**===delete===[admin]
- /api/summary/**===get===[admin,user,guest]
- /api/summary/**===post===[admin,user]
- /api/summary/**===put===[admin,user]
- /api/summary/**===delete===[admin]
- /api/collector/**===get===[admin,user,guest]
- /api/collector/**===post===[admin,user]
- /api/collector/**===put===[admin,user]
- /api/collector/**===delete===[admin]
- /api/status/page/**===get===[admin,user,guest]
- /api/status/page/**===post===[admin,user]
- /api/status/page/**===put===[admin,user]
- /api/status/page/**===delete===[admin]
# config the resource restful api that need bypass auth protection
# rule: api===method
# eg: /api/v1/source3===get means /api/v1/source3===get can be access by anyone, no need auth.
excludedResource:
- /api/account/auth/**===*
- /api/i18n/**===get
- /api/apps/hierarchy===get
- /api/push/**===*
- /api/status/page/public/**===*
# web ui resource
- /===get
- /dashboard/**===get
- /monitors/**===get
- /alert/**===get
- /account/**===get
- /setting/**===get
- /passport/**===get
- /status/**===get
- /**/*.html===get
- /**/*.js===get
- /**/*.css===get
- /**/*.ico===get
- /**/*.ttf===get
- /**/*.png===get
- /**/*.gif===get
- /**/*.jpg===get
- /**/*.svg===get
- /**/*.json===get
- /**/*.woff===get
- /**/*.eot===get
# swagger ui resource
- /swagger-resources/**===get
- /v2/api-docs===get
- /v3/api-docs===get
# h2 database
- /h2-console/**===*
# account info config
# eg: admin has role [admin,user], password is hertzbeat
# eg: tom has role [user], password is hertzbeat
# eg: lili has role [guest], plain password is lili, salt is 123, salted password is 1A676730B0C7F54654B0E09184448289
account:
- appId: admin
credential: hertzbeat
role: [admin]
- appId: tom
credential: hertzbeat
role: [user]
- appId: guest
credential: hertzbeat
role: [guest]
- appId: lili
# credential = MD5(password + salt)
# plain password: hertzbeat
# attention: digest authentication does not support salted encrypted password accounts
credential: 94C6B34E7A199A9F9D4E1F208093B489
salt: 123
role: [user]
```
Modify the following **part parameters** in sureness.yml **[Note⚠️Other default sureness configuration parameters should be retained]**：
```yaml
# user account information
# Here is admin tom lili three accounts
# eg: admin has role [admin,user], password is hertzbeat
# eg: tom has role [user], password is hertzbeat
# eg: lili has role [guest], plain password is lili, salt is 123, salted password is 1A676730B0C7F54654B0E09184448289
account:
- appId: admin
credential: hertzbeat
role: [admin]
- appId: tom
credential: hertzbeat
role: [user]
- appId: guest
credential: hertzbeat
role: [guest]
- appId: lili
# credential = MD5(password + salt)
# plain password: hertzbeat
# attention: digest authentication does not support salted encrypted password accounts
credential: 94C6B34E7A199A9F9D4E1F208093B489
salt: 123
role: [user]
```
## Update Security Secret
> This secret is the key for account security encryption management and needs to be updated to your custom key string of the same length.
Update the `application.yml` file in the `config` directory, modify the `sureness.jwt.secret` parameter to your custom key string of the same length.
```yaml
sureness:
jwt:
secret: 'CyaFv0bwq2Eik0jdrKUtsA6bx4sDJeFV643R
LnfKefTjsIfJLBa2YkhEqEGtcHDTNe4CU6+9
8tVt4bisXQ13rbN0oxhUZR73M6EByXIO+SV5
dKhaX0csgOCTlCxq20yhmUea6H6JIpSE2Rwp'
```
**Restart HertzBeat, access [http://ip:1157/](http://ip:1157/) to explore**
home/docs/start/baota-deploy.md
+43
View File
@@ -0,0 +1,43 @@
---
id: baota-deploy
title: Use aaPanel Deploy HertzBeat
sidebar_label: Install via aaPanel
---
Apache HertzBeat™ supports one-click deployment in the `Docker` application store of the aaPanel.
## Prerequisites
Install aaPanel, go to the [aaPanel](https://www.aapanel.com/new/download.html#install), switch the script and install.
## Install
1. Log in, click `Docker` menu and install the `Docker` `Docker Compose` according the prompts.
> Install the Docker service, skip if it already exists.
![HertzBeat](/img/docs/start/install-to-aapanel-1.png)
2. Find `HertzBeat` in `One-Click Install` and click `Install`
![HertzBeat](/img/docs/start/install-to-aapanel-2.png)
3. Config the domain, name and others, click `OK`
![HertzBeat](/img/docs/start/install-to-aapanel-3.png)
- Name: App name, default the `HertzBeat-random`
- Version：Default `latest`
- Domain：Config if you need domain access, please configure the domain name here and resolve the domain name to the server
- Allow External Access：If you need to access directly through `IP+Port`, please check it. If you have already set the domain name, please do not check here
- Port：Default `1157`
4. After submission, the panel will automatically initialize the application, which takes about `1-3` minutes. It can be accessed after the initialization is completed.
## Access HertzBeat
- If you have set a domain name, please enter the domain name directly in the browser address bar to access, such as `http://demo.hertzbeat.apache.org`, you can access the `HertzBeat` console.
- If you choose to access via `IP+Port`, please enter the domain name in the browser address bar to access `http://\<aaPanelIP>:1157`, you can access the `HertzBeat` console.
![HertzBeat](/img/home/0.png)
> Default account username: `admin` password: `hertzbeat`
home/docs/start/custom-config.md
+48
View File
@@ -0,0 +1,48 @@
---
id: custom-config
title: Advanced Params Config
sidebar_label: Advanced Params Config
---
Here it describes how to configure custom parameters for alerts, etc.
**Configuration file `application.yml` of `hertzbeat`**
Configuring the HertzBeat configuration file:
- Modify the configuration file located at `hertzbeat/config/application.yml`
- **Docker Deployment:** ⚠️ When using a Docker container, the `application.yml` file must be mounted to the host machine
- **Installation Package Deployment:** Extract the package and modify the configuration file located at `hertzbeat/config/application.yml`
## 0. Virtual Thread Configuration
Virtual-thread related defaults, tuning guidance, rollback switches, and Docker/package config locations are documented on a dedicated page:
- [Virtual Thread Configuration](./virtual-thread)
## 1. Configuring Custom Alert Parameters
```yaml
alerter:
# Custom console URL
console-url: https://console.tancloud.io
```
## 2. Using an External Redis Instead of In-Memory Storage for Real-Time Metric Data
> By default, real-time metric data is stored in memory. You can configure Redis as a replacement using the settings below.
⚠️ Note: Set `memory.enabled: false, redis.enabled: true`
```yaml
warehouse:
store:
memory:
enabled: false
init-size: 1024
redis:
enabled: true
host: 127.0.0.1
port: 6379
password: 123456
```
home/docs/start/docker-compose-deploy.md
+67
View File
@@ -0,0 +1,67 @@
---
id: docker-compose-deploy
title: Install HertzBeat via Docker Compose
sidebar_label: Install via Docker Compose
---
:::tip
Suggest to use Docker Compose to deploy HertzBeat and its dependent services.
:::
:::note
This document assumes that you already have Docker and Docker Compose installed in your environment. If not, please refer to the [Docker official documentation](https://docs.docker.com/compose/install/).
Run the `docker compose version` command to check if you have a Docker Compose environment.
:::
1. Download the startup script package
Download the installation script package `apache-hertzbeat-xxx-docker-compose.tar.gz` from the [download](/docs/download)
2. Choose to use the HertzBeat + PostgreSQL + VictoriaMetrics solution
:::tip
- `apache-hertzbeat-${version}-docker-compose.tar.gz` contains multiple deployment solutions after decompression. Here we recommend choosing the `hertzbeat-postgresql-victoria-metrics` solution.
- Other deployment methods, please read the README.md file of each deployment solution in detail. The MySQL solution requires you to prepare the MySQL driver package yourself.
:::
- Unzip the script package
```shell
tar zxvf apache-hertzbeat-${version}-docker-compose.tar.gz
```
- Enter the decompression directory and select `HertzBeat + PostgreSQL + VictoriaMetrics` for one-click deployment
```shell
cd apache-hertzbeat-${version}-docker-compose
cd hertzbeat-postgresql-victoria-metrics
```
- One-click start
> Run script in `hertzbeat-postgresql-victoria-metrics` directory
```shell
docker-compose up -d
```
- View service status
> View the running status of each container, up is the normal running status
```shell
docker-compose ps
```
3. Start exploring HertzBeat
Access [http://ip:1157/](http://ip:1157/) in the browser to start exploring and using it. The default account password is admin/hertzbeat.
**HAVE FUN**
----
## FAQ
**The most common problem is network problems, please check in advance**
home/docs/start/docker-deploy.md
+161
View File
@@ -0,0 +1,161 @@
---
id: docker-deploy
title: Install HertzBeat via Docker
sidebar_label: Install via Docker
---
:::tip
Using Docker to start HertzBeat with the minimum available environment, no external service dependencies, easy to experience quickly.
But it is not recommended to use in production environment, it is recommended to use Docker Compose deployment, installation package deployment, Kubernetes deployment in production environment.
:::
:::note
It is necessary to have Docker environment in your environment. If not installed, please refer to [Docker official document](https://docs.docker.com/get-docker/)
:::
## Deploy HertzBeat Server
1. Execute the following command
```shell
$ docker run -d -p 1157:1157 -p 1158:1158 \
-e HERTZBEAT_COLLECTOR_MYSQL_QUERY_ENGINE=auto \
-v $(pwd)/data:/opt/hertzbeat/data \
-v $(pwd)/logs:/opt/hertzbeat/logs \
-v $(pwd)/application.yml:/opt/hertzbeat/config/application.yml \
-v $(pwd)/sureness.yml:/opt/hertzbeat/config/sureness.yml \
--restart=always \
--name hertzbeat apache/hertzbeat
```
> Command parameter explanation
- `docker run -d` : Run a container in the background via Docker
- `-p 1157:1157 -p 1158:1158` : Mapping container ports to the host, 1157 is web-ui port, 1158 is cluster port.
- `-v $(pwd)/data:/opt/hertzbeat/data` : (optional, data persistence) Important, Mount the H2 database file to the local host, to ensure that the data is not lost due to creating or deleting container.
- `-v $(pwd)/logs:/opt/hertzbeat/logs` : (optional) Mount the log file to the local host to facilitate viewing.
- `-v $(pwd)/application.yml:/opt/hertzbeat/config/application.yml` : (optional) Mount the configuration file to the container (please ensure that the file exists locally). [Download](https://github.com/apache/hertzbeat/raw/master/script/application.yml)
- `-v $(pwd)/sureness.yml:/opt/hertzbeat/config/sureness.yml` : (optional) Mount the account configuration file to the container (please ensure that the file exists locally). [Download](https://github.com/apache/hertzbeat/raw/master/script/sureness.yml)
- `-v $(pwd)/ext-lib:/opt/hertzbeat/ext-lib` : (optional) Mount external third-party JAR packages when you need runtime JDBC extension. `mysql-jdbc` is only needed if you explicitly want the JDBC path for MySQL-compatible monitoring; [oracle-jdbc](https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc8/23.4.0.24.05/ojdbc8-23.4.0.24.05.jar) and [oracle-i18n](https://repo.mavenlibs.com/maven/com/oracle/database/nls/orai18n/21.5.0.0/orai18n-21.5.0.0.jar) are still required for Oracle monitoring.
- `-e HERTZBEAT_COLLECTOR_MYSQL_QUERY_ENGINE=auto` : (optional) Override the MySQL-compatible monitoring query path used by the built-in collector. Supported values: `auto`, `jdbc`, `r2dbc`.
- `--name hertzbeat` : (optional) Naming container name hertzbeat
- `--restart=always` : (optional) Configure the container to restart automatically.
- `apache/hertzbeat` : Use the [official application mirror](https://hub.docker.com/r/apache/hertzbeat) to start the container, if the network times out, use `quay.io/tancloud/hertzbeat` instead.
- `--network host` : (optional) Use the host network mode to start Docker, namely making Docker container and hosting share network. `docker run -d --network host .....`
:::tip
- Marked as optional parameters, non-mandatory items, if not needed, delete them.
- This maps the 1157,1158 ports of the container to the 1157,1158 ports of the host. If the port on the host is already occupied, you need to modify the host mapping port.
- When mounting files, the first parameter is your custom local file address, and the second parameter is the container file address. Make sure you have this file locally when mounting.
- You can execute `docker update --restart=always hertzbeat` to configure the container to restart automatically.
- If you want to use the host network mode to start Docker, you can use `docker run -d --network host .....`
:::
2. Start to explore HertzBeat
Access [http://ip:1157/](http://ip:1157/) using browser. You can explore HertzBeat with default account `admin/hertzbeat` now!
### Deploy HertzBeat Collector Cluster(Optional)
:::note
HertzBeat Collector is a lightweight data collector used to collect and send data to HertzBeat Server.
By deploying multiple HertzBeat Collectors, high availability, load balancing, and cloud-edge collaboration of data can be achieved.
:::
![HertzBeat](/img/docs/cluster-arch.png)
1. Execute the following command
```shell
$ docker run -d \
-e IDENTITY=custom-collector-name \
-e MODE=public \
-e MANAGER_HOST=127.0.0.1 \
-e MANAGER_PORT=1158 \
-e HERTZBEAT_COLLECTOR_MYSQL_QUERY_ENGINE=auto \
--name hertzbeat-collector apache/hertzbeat-collector
```
> Command parameter explanation
- `docker run -d` : Run a container in the background via Docker
- `-e IDENTITY=custom-collector-name` : (optional) Set the collector unique identity name. Attention the clusters collector name must unique.
- `-e MODE=public` : set the running mode(public or private), public cluster or private
- `-e MANAGER_HOST=127.0.0.1` : Important, Set the main hertzbeat server ip host, must use the server host instead of 127.0.0.1.
- `-e MANAGER_PORT=1158` : (optional) Set the main hertzbeat server port, default 1158.
- `-e HERTZBEAT_COLLECTOR_MYSQL_QUERY_ENGINE=auto` : (optional) Override the MySQL-compatible monitoring query path. Supported values: `auto`, `jdbc`, `r2dbc`.
- `-v $(pwd)/logs:/opt/hertzbeat-collector/logs` : (optional) Mount the log file to the local host to facilitate viewing.
- `--name hertzbeat-collector` : Naming container name hertzbeat-collector
- `apache/hertzbeat-collector` : Use the [official application mirror](https://hub.docker.com/r/apache/hertzbeat-collector) to start the container, if the network times out, use `quay.io/tancloud/hertzbeat-collector` instead.
- `--network host` : (optional) Use the host network mode to start Docker, namely making Docker container and hosting share network. `docker run -d --network host .....`
:::tip
- Marked as optional parameters, non-mandatory items, if not needed, delete them.
- The `127.0.0.1` in `MANAGER_HOST` needs to be replaced with the external IP address of the HertzBeat Server.
- When mounting files, the first parameter is your custom local file address, and the second parameter is the container file address. Make sure you have this file locally when mounting.
- You can execute `docker update --restart=always hertzbeat-collector` to configure the container to restart automatically.
- If you want to use the host network mode to start Docker, you can use `docker run -d --network host .....`
:::
2. Access `http://localhost:1157` and you will see the registered new collector in dashboard.
**HAVE FUN**
----
### FAQ
**The most common problem is network problems, please check in advance**
1. MYSQL, TDENGINE, IoTDB and HertzBeat are deployed on the same host by Docker,HertzBeat use localhost or 127.0.0.1 connect to the database but fail
The problems lies in Docker container failed to visit and connect localhost port. Because the docker default network mode is Bridge mode which can't access local machine through localhost.
> Solution A：Configure application.yml. Change database connection address from localhost to external IP of the host machine.
> Solution B：Use the Host network mode to start Docker, namely making Docker container and hosting share network. `docker run -d --network host .....`
2. According to the process deploy，visit [http://ip:1157/](http://ip:1157/) no interface
Please refer to the following points to troubleshoot issues：
> 1：If you switch to dependency service MYSQL database，check whether the database is created and started successfully.
> 2：Check whether dependent services, IP account and password configuration is correct in HertzBeat's configuration file `application.yml`.
> 3：`docker logs hertzbeat` Check whether the container log has errors. If you haven't solved the issue, report it to the communication group or community.
3. Historical monitoring charts have been missing data for a long time
> 1：Check whether you configure victoria-metrics or Tdengine or IoTDB. No configuration means no historical chart data.
> 2: Check whether IP account and password configuration is correct in HertzBeat's configuration file `application.yml`.
4. If the history chart on the monitoring page is not displayed，popup [please configure time series database]
> As shown in the popup window，the premise of history chart display is that you need install and configure hertzbeat's dependency service database.
> Installation and initialization this database, please refer to [Using victoria-metrics to store metrics data](victoria-metrics-init)
5. The time series database is installed and configured, but the page still displays a pop-up [Unable to provide historical chart data, please configure dependent time series database]
> Please check if the configuration parameters are correct
> Is time-series database enable set to true
> Note⚠️If both hertzbeat and time-series database are started under the same host for docker containers, 127.0.0.1 cannot be used for communication between containers by default, and the host IP is changed
> You can check the startup logs according to the logs directory
6. What is the purpose of application.yml
> This file is the configuration file of HertzBeat, used to configure various parameters of HertzBeat, such as database connection information, time series database configuration, etc.
> Download `application.yml` file to the host directory, for example: $(pwd)/application.yml
> Download source [github/script/application.yml](https://github.com/apache/hertzbeat/raw/master/script/application.yml)
> You can modify the configuration yml file according to your needs.
>
> - If you need to use email to send alarms, you need to replace the email server parameters `spring.mail` in `application.yml`
> - **Recommended** If you need to use an external Mysql database to replace the built-in H2 database, you need to replace the `spring.datasource` parameter in `application.yml` For specific steps, see [Using Mysql to replace H2 database](mysql-change)
> - **Recommended** If you need to use the time series database victoria-metrics to store metric data, you need to replace the `warehouse.store.victoria-metrics` parameter in `application.yml` for specific steps, see [Using victoria-metrics to store metrics data](victoria-metrics-init)
7. What is the purpose of sureness.yml
> This file is the user configuration file of HertzBeat, used to configure user information of HertzBeat, such as account password, etc.
> HertzBeat default built-in three user accounts, respectively `admin/hertzbeat tom/hertzbeat guest/hertzbeat`
> If you need update account or password, configure `sureness.yml`. Ignore this step without this demand.
> Download and config `sureness.yml` in the host directory，eg:`$(pwd)/sureness.yml`
> Download from [github/script/sureness.yml](https://github.com/apache/hertzbeat/raw/master/script/sureness.yml)
> For detail steps, please refer to [Configure Account Password](account-modify)
home/docs/start/doris-init.md
+224
View File
@@ -0,0 +1,224 @@
---
id: doris-init
title: Use Apache Doris to Store Metrics and Logs Data (Optional)
sidebar_label: Metrics/Logs Store Doris
---
Apache HertzBeat's historical data storage relies on the time series database, you can choose one of them to install and initialize, or not to install (note ⚠️ but it is strongly recommended to configure in the production environment)
> It is recommended to use Greptime as metrics storage.
Apache Doris is an MPP-based real-time analytics database. In HertzBeat, Doris can be used to store:
- Metrics history data (`hzb_history`)
- Log data (`hzb_log`)
**⚠️ If you do not configure a time-series database, only the last hour of historical data is retained.**
> If you already have a Doris cluster, skip directly to the YML configuration section.
## Install Doris (Optional)
You can deploy Doris by package or Docker. For production, follow the official deployment guide:
- Doris docs: [Quick Start](https://doris.apache.org/docs/4.x/gettingStarted/quick-start/)
For HertzBeat integration, ensure at least:
- FE MySQL service port is reachable (default `9030`)
- FE HTTP service port is reachable (default `8030`)
### Note: Install MySQL JDBC Driver Jar
- Download MySQL JDBC driver jar, for example mysql-connector-java-8.1.0.jar. [https://mvnrepository.com/artifact/com.mysql/mysql-connector-j/8.1.0](https://mvnrepository.com/artifact/com.mysql/mysql-connector-j/8.1.0)
- Copy this jar to the `ext-lib` directory in HertzBeat installation directory.
- Restart HertzBeat service.
### Prerequisites
1. Doris FE and BE are running normally.
2. HertzBeat can access:
- FE MySQL port (default `9030`) for metadata/query
- FE HTTP port (default `8030`) for Stream Load
3. The configured Doris user has permission to create database/table and insert/query data.
### Configure Doris in HertzBeat `application.yml`
1. Edit `hertzbeat/config/application.yml`.
For Docker deployment, mount the config file from host.
For package deployment, modify `hertzbeat/config/application.yml` directly.
2. Configure `warehouse.store.doris` (Production Environment Recommended using Stream Load Mode):
```yaml
warehouse:
store:
doris:
enabled: true
# FE MySQL endpoint
url: jdbc:mysql://127.0.0.1:9030
username: root
password:
table-config:
# Enable dynamic partition for automatic expiration
enable-partition: true
# HOUR / DAY / MONTH
partition-time-unit: DAY
# Number of history partitions to keep
partition-retention-days: 30
# Number of future partitions to pre-create
partition-future-days: 3
buckets: 8
replication-num: 3
pool-config:
minimum-idle: 5
maximum-pool-size: 20
connection-timeout: 30000
write-config:
# Strongly recommend stream mode in production for high throughput
write-mode: stream
batch-size: 1000
flush-interval: 5
stream-load-config:
# FE HTTP port
http-port: ":8030"
timeout: 60
max-bytes-per-batch: 10485760
# For complex networks (K8s/cross-domain): direct / public / private
redirect-policy: ""
```
### Switching to Stream Load Mode
#### Production Environment Configuration
For production deployments, **strongly recommend using Stream Load mode** to ensure high-performance large-scale writes. Stream Load writes directly to Doris storage layer, providing better throughput improvement compared to JDBC mode.
#### Pre-Switch Checklist
1. **Network Reachability**
- Ensure HertzBeat can access Doris FE HTTP port (default `8030`)
- If direct connection is not possible, configure BE endpoint labels in Doris
2. **Special Configuration for Complex Network Scenarios**
In K8s, cross-domain, or load-balanced environments, Stream Load's redirect mechanism requires special attention:
- FE redirects requests to an available BE, which must be reachable from HertzBeat
- Control returned BE address type via `redirect-policy`:
- `direct`: Direct BE IP connection
- `public`: Use public IP (cloud environments)
- `private`: Use private IP (private networks)
- Leave empty to use Doris default policy
Reference: [Doris Stream Load in Complex Networks](https://doris.apache.org/zh-CN/docs/4.x/data-operate/import/load-internals/stream-load-in-complex-network)
#### Switching Steps
1. **Modify Configuration File**
Edit `hertzbeat/config/application.yml` and change `write-mode` to `stream`:
```yaml
warehouse:
store:
doris:
write-config:
write-mode: stream # Change here: from jdbc to stream
stream-load-config:
http-port: ":8030"
timeout: 60
max-bytes-per-batch: 10485760
redirect-policy: "" # Configure if complex network
```
2. **Restart HertzBeat Service**
3. **Verify Successful Switch**
Check HertzBeat logs for Stream Load messages
#### Common Switching Questions
**Q: Do I need to rebuild tables after switching?**
A: No. Stream Load and JDBC modes use the same table structure, fully compatible.
**Q: Will data be lost when switching from JDBC to Stream Load?**
A: No. Both write modes are independent, historical data remains unchanged.
**Q: How do I rollback if Stream Load fails?**
A: If the stream processing fails, it will automatically try to use the jdbc mode for fallback writing
**Q: Still getting timeouts in cross-network setup with redirect-policy configured?**
A: Possible causes:
- Returned BE address under current `redirect-policy` setting is unreachable
- Try different `redirect-policy` values (`direct` / `public` / `private`)
- Contact Doris admin to verify BE endpoint label configuration
### Parameter Notes
| Parameter | Description |
| --- | --- |
| `enabled` | Enable/disable Doris storage |
| `url` | Doris FE MySQL JDBC endpoint |
| `table-config.enable-partition` | Enable dynamic partition and automatic expiration |
| `table-config.partition-time-unit` | Partition granularity: `HOUR` / `DAY` / `MONTH` |
| `table-config.partition-retention-days` | Number of partitions retained |
| `table-config.partition-future-days` | Number of future partitions pre-created |
| `table-config.buckets` | Bucket count for table distribution |
| `table-config.replication-num` | Replica count |
| `write-config.write-mode` | `jdbc` or `stream` |
| `write-config.batch-size` | Write batch size |
| `write-config.flush-interval` | Flush interval in seconds |
| `stream-load-config.http-port` | Doris FE HTTP port for Stream Load |
| `stream-load-config.timeout` | Stream Load timeout in seconds |
| `stream-load-config.max-bytes-per-batch` | Max bytes per stream-load batch |
| `stream-load-config.redirect-policy` | Redirect policy for FE->BE endpoint selection: `direct` / `public` / `private` |
### Restart HertzBeat
After configuration changes, restart HertzBeat to apply Doris storage settings.
### Verify Doris Storage Is Working
1. Check HertzBeat logs for Stream Load success messages.
2. Verify database and tables:
```sql
SHOW CREATE TABLE hertzbeat.hzb_history;
SHOW CREATE TABLE hertzbeat.hzb_log;
```
1. If partition is enabled, check dynamic partition state:
```sql
SHOW DYNAMIC PARTITION TABLES FROM hertzbeat;
SHOW PARTITIONS FROM hertzbeat.hzb_history;
SHOW PARTITIONS FROM hertzbeat.hzb_log;
```
### FAQ
1. Do I need to enable partition to use bucket distribution?
> No. Buckets work with or without dynamic partition. `enable-partition` only controls dynamic partition and automatic expiration.
2. Can I use Doris for both metrics and logs at the same time?
> Yes. HertzBeat writes metrics into `hzb_history` and logs into `hzb_log` with the same Doris datasource configuration.
3. If I change partition/bucket settings in `application.yml`, will existing tables auto-update?
> No. Existing Doris table DDL is not automatically altered. For schema-level changes, apply DDL manually or recreate tables.
4. Is stream load compression enabled?
> Current implementation uses JSON stream load by default.
home/docs/start/greptime-init.md
+74
View File
@@ -0,0 +1,74 @@
---
id: greptime-init
title: Use Time Series Database Greptime to Store Metrics Data (Recommended)
sidebar_label: Metrics Store Greptime (Recommended)
---
Apache HertzBeat's historical data storage relies on the time series database, you can choose one of them to install and initialize, or not to install (note ⚠️ but it is strongly recommended to configure in the production environment)
> It is recommended to use Greptime as metrics storage.
[Greptime](https://github.com/GreptimeTeam/greptimedb) is an Open-source, cloud-native, unified observability database for metrics, logs and traces, supporting SQL/PromQL/Streaming.
It's designed to work on infrastructure of the cloud era, and users benefit from its elasticity and commodity storage.
**⚠️ If you do not configure a time series database, only the last hour of historical data is retained.**
## Install GreptimeDvia Docker
1. Download and install Docker environment
Docker tools download refer to [Docker official document](https://docs.docker.com/get-docker/).
After the installation you can check if the Docker version normally output at the terminal.
```shell
$ docker -v
Docker version 20.10.12, build e91ed57
```
2. Install Greptime with Docker
```shell
$ docker run -d -p 127.0.0.1:4000-4003:4000-4003 \
v "$(pwd)/greptimedb:/tmp/greptimedb" \
--name greptime \
greptime/greptimedb:latest standalone start \
--http-addr 0.0.0.0:4000 \
--rpc-addr 0.0.0.0:4001 \
--mysql-addr 0.0.0.0:4002 \
--postgres-addr 0.0.0.0:4003
```
`-v "$(pwd)/greptimedb:/tmp/greptimedb"` is local persistent mount of greptime data directory. `$(pwd)/greptimedb` should be replaced with the actual local directory, default is the `greptimedb` directory under the current directory.
use```$ docker ps``` to check if the database started successfully
### Configure the database connection in hertzbeat `application.yml` configuration file
1. Configure HertzBeat's configuration file
Modify `hertzbeat/config/application.yml` configuration file [/script/application.yml](https://github.com/apache/hertzbeat/raw/master/script/application.yml)
Note⚠️The docker container way need to mount application.yml file locally, while you can use installation package way to unzip and modify `hertzbeat/config/application.yml`
Replace `warehouse.store.greptime` data source parameters, URL account and password.
```yaml
warehouse:
store:
duckdb:
enabled: false
greptime:
enabled: true
grpc-endpoints: localhost:4001
http-endpoint: http://localhost:4000
database: public
username: greptime
password: greptime
```
The default database is `public`, if you specify another database name, you need to create it in `greptimeDB` in advance.
eg: Create a database named `hertzbeat` with a validity period of 90 days SQL: `CREATE DATABASE IF NOT EXISTS hertzbeat WITH(ttl='90d')`
2. Restart HertzBeat
### FAQ
1. Do both the time series databases need to be configured? Can they both be used?
> You don't need to configure all of them, you can choose one of them. Use the enable parameter to control whether it is used or not. You can also install and configure neither, which only affects the historical chart data.
home/docs/start/influxdb-init.md
+74
View File
@@ -0,0 +1,74 @@
---
id: influxdb-init
title: Use Time Series Database InfluxDB to Store Metrics Data (Optional)
sidebar_label: Metrics Store InfluxDB
---
Apache HertzBeat's historical data storage relies on the time series database, you can choose one of them to install and initialize, or not to install (note ⚠️ but it is strongly recommended to configure in the production environment)
> It is recommended to use VictoriaMetrics as metrics storage.
**Note⚠️ Time series database is optional, but production environment configuration is strongly recommended to provide more complete historical chart functions and high performance**
**⚠️ If you do not configure a time series database, only the last hour of historical data is retained.**
Note⚠️ Need InfluxDB 1.x Version.
## 1. Use HuaweiCloud GaussDB For Influx
>
> Use [HuaweiCloud GaussDB For Influx](https://www.huaweicloud.com/intl/en-us/product/gaussdb.html)
>
> Get the `GaussDB For Influx` service url, username and password config.
⚠️Note `GaussDB For Influx` enable SSL default, the service url should use `https:`
### 2. Install TDengine via Docker
1. Download and install Docker environment
Docker tools download refer to [Docker official document](https://docs.docker.com/get-docker/).
After the installation you can check if the Docker version normally output at the terminal.
```shell
$ docker -v
Docker version 20.10.12, build e91ed57
```
2. Install InfluxDB with Docker
```shell
$ docker run -p 8086:8086 \
-v /opt/influxdb:/var/lib/influxdb \
influxdb:1.8
```
`-v /opt/influxdb:/var/lib/influxdb` is local persistent mount of InfluxDB data directory. `/opt/influxdb` should be replaced with the actual local directory.
use```$ docker ps``` to check if the database started successfully
### Configure the database connection in hertzbeat `application.yml` configuration file
1. Configure HertzBeat's configuration file
Modify `hertzbeat/config/application.yml` configuration file
Note⚠️The docker container way need to mount application.yml file locally, while you can use installation package way to unzip and modify `hertzbeat/config/application.yml`
Replace `warehouse.store.influxdb` data source parameters, URL account and password.
```yaml
warehouse:
store:
# disable DuckDB
duckdb:
enabled: false
# enable influxdb
influxdb:
enabled: true
server-url: http://localhost:8086
username: root
password: root
expire-time: '30d'
replication: 1
```
2. Restart HertzBeat
### FAQ
1. Do both the time series databases InfluxDB, IoTDB and TDengine need to be configured? Can they both be used?
> You don't need to configure all of them, you can choose one of them. Use the enable parameter to control whether it is used or not. You can also install and configure neither, which only affects the historical chart data.
home/docs/start/iotdb-init.md
+123
View File
@@ -0,0 +1,123 @@
---
id: iotdb-init
title: Use Time Series Database IoTDB to Store Metrics Data (Optional)
sidebar_label: Metrics Store IoTDB
---
Apache HertzBeat's historical data storage relies on the time series database, you can choose one of them to install and initialize, or not to install (note ⚠️ but it is strongly recommended to configure in the production environment)
> It is recommended to use VictoriaMetrics as metrics storage.
Apache IoTDB is a software system that integrates the collection, storage, management and analysis of time series data of the Internet of Things. We use it to store and analyze the historical data of monitoring metrics collected. Support V1.0.+ version.
**Note⚠️ Time series database is optional, but production environment configuration is strongly recommended to provide more complete historical chart functions and high performance**
**⚠️ If you do not configure a time series database, only the last hour of historical data is retained.**
> If you already have an IoTDB environment, you can skip directly to the YML configuration step.
## Install IoTDB via Docker
>
> Refer to the official website [installation tutorial](https://iotdb.apache.org/UserGuide/V0.13.x/QuickStart/WayToGetIoTDB.html)
1. Download and install Docker environment
Docker tools download refer to [Docker official document](https://docs.docker.com/get-docker/).
After the installation you can check if the Docker version normally output at the terminal.
```shell
$ docker -v
Docker version 20.10.12, build e91ed57
```
2. Install IoTDB via Docker
```shell
$ docker run -d -p 6667:6667 -p 31999:31999 -p 8181:8181 \
-v /opt/iotdb/data:/iotdb/data \
--name iotdb \
apache/iotdb:1.2.2-standalone
```
`-v /opt/iotdb/data:/iotdb/data` is local persistent mount of IotDB data directory.`/iotdb/data` should be replaced with the actual local directory.
use```$ docker ps``` to check if the database started successfully
3. Configure the database connection in hertzbeat `application.yml`configuration file
Modify `hertzbeat/config/application.yml` configuration file
Note⚠️The docker container way need to mount application.yml file locally, while you can use installation package way to unzip and modify `hertzbeat/config/application.yml`
Config the `warehouse.store.duckdb.enabled` `false`. Replace `warehouse.store.iot-db` data source parameters, HOST account and password.
```yml
warehouse:
store:
# disable DuckDB
duckdb:
enabled: false
# enable iot-db
iot-db:
enabled: true
host: 127.0.0.1
rpc-port: 6667
username: root
password: root
query-timeout-in-ms: -1
# default '7776000000'（90days,unit:ms,-1:no-expire）
expire-time: '7776000000'
```
**IoTDB Cluster Configuration**
If you are using IoTDB for clustering, please refer to the configuration below:
```yaml
warehouse:
store:
# Disable default DuckDB
duckdb:
enabled: false
# Enable IoTDB
iot-db:
enabled: true
node-urls: ['127.0.0.1:6667','127.0.0.2:6667','127.0.0.3:6667']
username: root
password: root
# if iotdb version >= 0.13 use default queryTimeoutInMs = -1; else use default queryTimeoutInMs = 0
query-timeout-in-ms: -1
# Data storage time: default '7776000000' (90 days, in milliseconds, -1 means never expire)
expire-time: '7776000000'
```
Configuration parameters:
| Parameter Name | Description |
|---------------------|-------------------------------------------------------------------------------------------|
| enabled | Whether to enable |
| host | IoTDB database address |
| rpc-port | IoTDB database port |
| node-urls | IoTDB cluster addresses |
| username | IoTDB database account |
| password | IoTDB database password |
| version | deprecated |
| query-timeout-in-ms | Query timeout |
| expire-time | Data storage time, default '7776000000' (90 days, in milliseconds, -1 means never expire) |
> If both cluster configuration `node-urls` and standalone configuration are set simultaneously, the cluster `node-urls` configuration takes precedence.
4. Restart HertzBeat
### FAQ
1. Do both the time series databases IoTDB and TDengine need to be configured? Can they both be used?
> You don't need to configure all of them, you can choose one of them. Use the enable parameter to control whether it is used or not. You can also install and configure neither, which only affects the historical chart data.
2. The historical chart of the monitoring page is not displayed, and pops up [Unable to provide historical chart data, please configure to rely on the time series database]
> As shown in the pop-up window, the premise of displaying the history chart is to install and configure the dependent services of hertzbeat - IotDB database or TDengine database
3. The TDengine database is installed and configured, but the page still displays a pop-up [Unable to provide historical chart data, please configure the dependent time series database]
> Please check if the configuration parameters are correct
> Is td-engine enable set to true
> Note⚠️If both hertzbeat and TDengine are started under the same host for docker containers, 127.0.0.1 cannot be used for communication between containers by default, and the host IP is changed
> You can check the startup logs according to the logs directory
home/docs/start/mysql-change.md
+115
View File
@@ -0,0 +1,115 @@
---
id: mysql-change
title: Use MYSQL Replace H2 Database to Store Metadata(Optional)
sidebar_label: Meta Store MYSQL
---
MySQL is a reliable relational database. In addition to default built-in H2 database, Apache HertzBeat™ allows you to use MySQL to store structured relational data such as monitoring information, alarm information and configuration information.
> If you already have a MySQL environment and the MySQL version meets the requirements, you can skip directly to the database creation step.
## Supported MySQL Versions
Please ensure you are using a supported MySQL version. HertzBeat only supports MySQL 5.7+ or 8 versions. You can check the MySQL version with the following command:
```shell
$ mysql --version
mysql Ver 8.0.25 for Linux on x86_64 (MySQL Community Server - GPL)
```
### Install MYSQL via Docker
1. Download and install the Docker environment
For Docker installation, please refer to the [Docker official documentation](https://docs.docker.com/get-docker/).
After the installation, please verify in the terminal that the Docker version can be printed normally.
```shell
$ docker -v
Docker version 20.10.12, build e91ed57
```
2. Install MYSQl with Docker
```shell
$ docker run -d --name mysql \
-p 3306:3306 \
-v /opt/data:/var/lib/mysql \
-e MYSQL_ROOT_PASSWORD=123456 \
--restart=always \
mysql:5.7
```
`-v /opt/data:/var/lib/mysql` is local persistent mount of mysql data directory. `/opt/data` should be replaced with the actual local directory.
use ```$ docker ps``` to check if the database started successfully
### Database creation
1. Enter MYSQL or use the client to connect MYSQL service
`mysql -uroot -p123456`
2. Create database named hertzbeat
`create database hertzbeat default charset utf8mb4 collate utf8mb4_general_ci;`
3. Check if hertzbeat database has been successfully created
`show databases;`
### Add MYSQL jdbc driver jar
- Download the MYSQL jdbc driver jar package, such as mysql-connector-java-8.0.25.jar. [https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-java-8.0.25.zip](https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-java-8.0.25.zip)
- Copy the jar package to the `hertzbeat/ext-lib` directory.
### Modify hertzbeat's configuration file application.yml and switch data source
- Configure HertzBeat's configuration file
Modify `hertzbeat/config/application.yml` configuration file
Note⚠️The docker container way need to mount application.yml file locally, while you can use installation package way to unzip and modify `hertzbeat/config/application.yml`
Replace `spring.database` data source parameters, URL account and password.
For example:
```yaml
spring:
datasource:
driver-class-name: org.h2.Driver
username: sa
password: 123456
url: jdbc:h2:./data/hertzbeat;MODE=MYSQL
hikari:
max-lifetime: 120000
jpa:
show-sql: false
database: h2
hibernate:
ddl-auto: update
properties:
hibernate:
dialect: org.hibernate.dialect.H2Dialect
format_sql: true
```
Specific replacement parameters are as follows and you need to configure account according to the mysql environment:
```yaml
spring:
datasource:
driver-class-name: com.mysql.cj.jdbc.Driver
username: root
password: 123456
url: jdbc:mysql://mysql:3306/hertzbeat?useUnicode=true&characterEncoding=utf-8&allowPublicKeyRetrieval=true&useSSL=false
hikari:
max-lifetime: 120000
jpa:
show-sql: false
database: mysql
hibernate:
ddl-auto: update
properties:
hibernate:
dialect: org.hibernate.dialect.MySQLDialect
format_sql: true
```
- It is recommended to set the host field in the MySQL URL to the public IP address when using HertzBeat in docker.
> Note: The above applies to the method of downloading and installing the package. For local data source switching, simply complete the [Database creation](./mysql-change#database-creation) and modify the configuration in `hertzbeat-startup/src/main/resources/application.yml`.
**Start HertzBeat visit [http://ip:1157/](http://ip:1157/) on the browser You can use HertzBeat monitoring alarm, default account and password are admin/hertzbeat**
home/docs/start/native-collector.md
+82
View File
@@ -0,0 +1,82 @@
---
id: native-collector
title: Native Collector Guide
sidebar_label: Native Collector
description: When to choose the HertzBeat native collector package, its benefits, limitations, and deployment guidance.
---
## When should I choose the native collector?
Choose the native collector package when your monitoring workload does not depend on loading external JDBC drivers from `ext-lib`.
Typical native-friendly workloads include:
- HTTP, HTTPS, website availability, and API checks
- Port, ping, SSL certificate, and other network probes
- MySQL, MariaDB, and OceanBase when you do not rely on runtime `ext-lib` JDBC loading
- TiDB when you do not rely on runtime `ext-lib` JDBC loading for its SQL query metric set
- Redis, Zookeeper, Kafka, and other non-JDBC monitoring types
## Why use it?
Compared with the JVM collector package, the native collector package is usually a better fit when you want:
- Faster startup
- Lower baseline memory usage
- A simpler runtime without a bundled or preinstalled JDK
## What are the trade-offs?
The native collector package is not a drop-in replacement for every JVM collector scenario.
- Native packages are platform-specific. You must choose the package that matches your OS and CPU architecture.
- The native collector does not support loading external JDBC driver JARs from `ext-lib` at runtime.
- If your deployment depends on JVM-style runtime classpath extension, keep using the JVM collector package.
## When should I stay on the JVM collector?
Use the JVM collector package if your monitoring depends on external JDBC drivers, especially:
- Oracle, which requires `ojdbc8` and sometimes `orai18n`
- DB2, which requires `jcc`
- Any MySQL, MariaDB, or OceanBase deployment where you explicitly place `mysql-connector-j` in `ext-lib` and want the JDBC path
## Package naming
The JVM collector package remains cross-platform:
- `apache-hertzbeat-collector-{version}-bin.tar.gz`
The native collector package is platform-specific:
- Linux or macOS: `apache-hertzbeat-collector-native-{version}-{platform}-bin.tar.gz`
- Windows: `apache-hertzbeat-collector-native-{version}-windows-amd64-bin.zip`
Examples:
- `apache-hertzbeat-collector-native-1.8.0-linux-amd64-bin.tar.gz`
- `apache-hertzbeat-collector-native-1.8.0-macos-arm64-bin.tar.gz`
- `apache-hertzbeat-collector-native-1.8.0-windows-amd64-bin.zip`
## Configuration consistency
The native collector package uses the same `config/application.yml` layout as the JVM collector package.
That means:
- Collector connection settings are edited in the same place
- Virtual-thread related configuration is edited in the same place
- Native-only boot adjustments are applied by code at runtime instead of maintaining a second `application.yml`
## Recommended decision
- Choose the native collector package when you want lower memory usage and faster startup for non-JDBC monitoring, for MySQL, MariaDB, and OceanBase without `ext-lib`, or for TiDB when its SQL query metric set can use the built-in MySQL-compatible query engine.
- Choose the JVM collector package when you need `ext-lib`, external JDBC drivers, or JVM-style runtime extensibility.
- For MySQL-compatible monitoring on the JVM collector, `auto` only checks `ext-lib`. If you need to force a path, set `hertzbeat.collector.mysql.query-engine=jdbc`, `r2dbc`, or `auto`.
## How are the official multi-platform packages built?
- `mvn clean package -pl hertzbeat-collector-collector -am -Pnative` builds a native collector package for the current host only.
- The official Linux, macOS, and Windows native release packages are produced by manually running the `Collector Native Release` GitHub Actions workflow during release preparation, not on every push or pull request.
For package deployment steps, refer to [Install HertzBeat via Package](package-deploy).
home/docs/start/package-deploy.md
+169
View File
@@ -0,0 +1,169 @@
---
id: package-deploy
title: Install HertzBeat via Package
sidebar_label: Install via Package
---
:::tip
You can install and run Apache HertzBeat™ on Linux Windows Mac system, and CPU supports X86/ARM64.
The current branch uses `Java 25`, and the standard installation package no longer provides a built-in JDK. Use HertzBeat according to the following situations:
- When the default environment variable on your server is `Java 25`, you do not need to take any action for this step.
- When the default environment variable on your server is not `Java 25`, such as `Java 8`, `Java 11`, or `Java 21`, and if there are no other applications on your server that require a lower version of Java, download `Java 25` from [https://www.oracle.com/java/technologies/downloads/](https://www.oracle.com/java/technologies/downloads/) according to your system, and set a new environment variable pointing to `Java 25`.
- When the default environment variable on your server is not `Java 25`, such as `Java 8`, `Java 11`, or `Java 21`, and you do not want to change the environment variable because there are other applications on your server that require a lower version of Java, download `Java 25` from [https://www.oracle.com/java/technologies/downloads/](https://www.oracle.com/java/technologies/downloads/) according to your system, rename the extracted folder to `java`, and then copy it to the HertzBeat extraction directory.
:::
## Deploy HertzBeat Server
1. Download installation package
Download installation package `apache-hertzbeat-xxx-bin.tar.gz` corresponding to your system environment
- [Download Page](/docs/download)
2. Configure HertzBeat's configuration file(optional)
Unzip the installation package to the host eg: /opt/hertzbeat
```shell
tar zxvf apache-hertzbeat-xxx-bin.tar.gz
```
:::tip
The configuration file is located in `config/application.yml`, you can modify the configuration file according to your needs to configure external dependent services, such as databases, time series databases, etc.
HertzBeat defaults to using internal services when started, but it is recommended to switch to external database services in production environments.
:::
It is recommended to use [PostgreSQL](postgresql-change) for metadata storage and [VictoriaMetrics](victoria-metrics-init) for metric data storage. Specific steps are as follows
- [Switch built-in H2 database to PostgreSQL](postgresql-change)
- [Using VictoriaMetrics to store metric data](victoria-metrics-init)
3. Configure the account file(optional)
HertzBeat default built-in three user accounts, respectively `admin/hertzbeat tom/hertzbeat guest/hertzbeat`
If you need modify account or password, configure `config/sureness.yml`.
For detail steps, please refer to [Configure Account Password](account-modify)
4. Start the service
Execute the startup script in the installation directory `bin/`, or `startup.bat` in windows.
```shell
./startup.sh
```
5. Begin to explore HertzBeat
Access [http://ip:1157/](http://ip:1157/) using browser. You can explore HertzBeat with default account `admin/hertzbeat` now!
### Deploy HertzBeat Collector Cluster(Optional)
:::note
HertzBeat Collector is a lightweight data collector used to collect and send data to HertzBeat Server.
Deploying multiple HertzBeat Collectors can achieve high availability, load balancing, and cloud-edge collaboration of data.
:::
:::tip Native Collector Recommendation
If your monitoring workload does not depend on external JDBC drivers from `ext-lib`, prefer the native collector package for faster startup and lower memory usage. MySQL, MariaDB, and OceanBase can also use the native collector package directly when `mysql-connector-j` is not provided. TiDB follows the same rule for its SQL query metric set.
Before choosing it, review the trade-offs in [Native Collector Guide](native-collector).
:::
![HertzBeat](/img/docs/cluster-arch.png)
1. Download installation package
Download the collector package that matches your deployment mode:
- JVM collector package: `apache-hertzbeat-collector-xxx-bin.tar.gz`
- Native collector package for Linux or macOS: `apache-hertzbeat-collector-native-xxx-{platform}-bin.tar.gz`
- Native collector package for Windows: `apache-hertzbeat-collector-native-xxx-windows-amd64-bin.zip`
- [Download Page](/docs/download)
2. Configure the collector configuration file
Unzip the installation package to the host eg: /opt/hertzbeat-collector
```shell
tar zxvf apache-hertzbeat-collector-xxx-bin.tar.gz
# or
tar zxvf apache-hertzbeat-collector-native-xxx-linux-amd64-bin.tar.gz
# or
unzip apache-hertzbeat-collector-native-xxx-windows-amd64-bin.zip
```
Configure the collector configuration yml file `config/application.yml`: unique `identity` name, running `mode` (public or private), hertzbeat `manager-host`, hertzbeat `manager-port`
```yaml
collector:
dispatch:
entrance:
netty:
enabled: true
identity: ${IDENTITY:}
mode: ${MODE:public}
manager-host: ${MANAGER_HOST:127.0.0.1}
manager-port: ${MANAGER_PORT:1158}
```
> Parameters detailed explanation
- `identity` : (optional) Set the unique identifier name of the collector. Note that the name of the collector must be unique when there are multiple collectors.
- `mode` : Configure the running mode (public or private), public cluster mode or private cloud-edge mode.
- `manager-host` : Important, configure the address of the connected HertzBeat Server,
- `manager-port` : (optional) Configure the port of the connected HertzBeat Server, default 1158.
3. Start the service
Run `$ ./bin/startup.sh` or `bin/startup.bat` for the JVM collector package. Run `$ ./bin/startup.sh` for Linux or macOS native collector packages, and `bin\\startup.bat` for the Windows native collector package.
4. Begin to explore HertzBeat Collector
Open the HertzBeat server dashboard at `http://<manager-host>:1157` and confirm the new collector is registered.
:::important Native Collector Limitations
The native collector package is suitable for monitoring types that do not rely on external JVM classpath extension.
See [Native Collector Guide](native-collector) for package selection, package naming, and platform-specific trade-offs.
`ext-lib`-based JDBC driver loading is a JVM collector capability. The native collector package does not support loading external JDBC driver JARs from `ext-lib` at runtime.
If your monitoring depends on external JDBC drivers, use the JVM collector package instead of the native collector package. This currently includes:
- Oracle, which requires `ojdbc8` and often `orai18n`
- DB2, which requires `jcc`
- Any MySQL, MariaDB, or OceanBase deployment where you explicitly place `mysql-connector-j` in `ext-lib` and want the JDBC path
Recommended deployment:
- Use the native collector package for HTTP, website, port, ping, similar non-JDBC monitoring types, and for MySQL, MariaDB, or OceanBase without `ext-lib`
- Use the JVM collector package when you need `ext-lib` driver extension
:::
**HAVE FUN**
----
### FAQ
1. you need to prepare the JAVA environment in advance
Install JAVA runtime environment-refer to [official website](https://www.oracle.com/java/technologies/downloads/)
requirement：JDK25 ENV
download JAVA installation package: [mirror website](https://mirrors.huaweicloud.com/openjdk/)
After installation use command line to check whether you install it successfully.
```shell
$ java -version
openjdk version "25.0.2" 2026-01-20
OpenJDK Runtime Environment (build 25.0.2+8)
OpenJDK 64-Bit Server VM (build 25.0.2+8, mixed mode, sharing)
```
2. According to the process deploy，visit [http://ip:1157/](http://ip:1157/) no interface
Please refer to the following points to troubleshoot issues:
> 1：If you switch to dependency service MYSQL database，check whether the database is created and started successfully.
> 2：Check whether dependent services, IP account and password configuration is correct in HertzBeat's configuration file `hertzbeat/config/application.yml`.
> 3：Check whether the running log has errors in `hertzbeat/logs/` directory. If you haven't solved the issue, report it to the communication group or community.
home/docs/start/postgresql-change.md
+103
View File
@@ -0,0 +1,103 @@
---
id: postgresql-change
title: Use PostgreSQL Replace H2 Database to Store Metadata(Recommended)
sidebar_label: Meta Store PostgreSQL (Recommended)
---
PostgreSQL is an RDBMS emphasizing extensibility and SQL compliance. In addition to default built-in H2 database, Apache HertzBeat™ allows you to use PostgreSQL to store structured relational data such as monitoring information, alarm information and configuration information.
> If you have a PostgreSQL environment, you can skip directly to the database creation step.
## Install PostgreSQL via Docker
1. Download and install the Docker environment
Docker tools download refer to [Docker official document](https://docs.docker.com/get-docker/)。
After the installation you can check if the Docker version normally output at the terminal.
```shell
$ docker -v
Docker version 20.10.12, build e91ed57
```
2. Install PostgreSQL with Docker
```shell
docker run -d --name postgresql -p 5432:5432 -e POSTGRES_USER=root -e POSTGRES_PASSWORD=123456 -e TZ=Asia/Shanghai postgres:15
```
use```$ docker ps```to check if the database started successfully
### Database creation
1. Enter postgreSQL or use the client to connect postgreSQL service
```shell
su - postgres
psql
```
2. Create database named hertzbeat
```sql
CREATE DATABASE hertzbeat;
```
3. Check if hertzbeat database has been successfully created
```sql
SELECT * FROM pg_database where datname='hertzbeat';
```
### Modify hertzbeat's configuration file application.yml and switch data source
1. Configure HertzBeat's configuration file
Modify `hertzbeat/config/application.yml` configuration file
Note⚠️The docker container way need to mount application.yml file locally, while you can use installation package way to unzip and modify `hertzbeat/config/application.yml`
Replace `spring.database` data source parameters, URL account and password.
```yaml
spring:
datasource:
driver-class-name: org.h2.Driver
username: sa
password: 123456
url: jdbc:h2:./data/hertzbeat;MODE=MYSQL
hikari:
max-lifetime: 120000
jpa:
show-sql: false
database: h2
hibernate:
ddl-auto: update
properties:
hibernate:
dialect: org.hibernate.dialect.H2Dialect
format_sql: true
```
Specific replacement parameters are as follows and you need to configure account, ip, port according to the postgresql environment:
```yaml
spring:
datasource:
driver-class-name: org.postgresql.Driver
username: root
password: 123456
url: jdbc:postgresql://postgresql:5432/hertzbeat
hikari:
max-lifetime: 120000
jpa:
show-sql: false
database: postgresql
hibernate:
ddl-auto: update
properties:
hibernate:
dialect: org.hibernate.dialect.PostgreSQLDialect
format_sql: true
```
> Note: The above applies to the method of downloading and installing the package. For local data source switching, simply complete the [Database creation](./postgresql-change#database-creation) and modify the configuration in `hertzbeat-startup/src/main/resources/application.yml`.
**Start HertzBeat visit [http://ip:1157/](http://ip:1157/) on the browser You can use HertzBeat monitoring alarm, default account and password are admin/hertzbeat**
home/docs/start/questdb-init.md
+137
View File
@@ -0,0 +1,137 @@
---
id: questdb-init
title: Installation and Initialization of Time-Series Database Service QuestDB (Optional)
sidebar_label: Metrics Store QuestDB
---
The historical data storage of Apache HertzBeat™ relies on a time-series database. You can choose to install and initialize **one** of the supported databases, or skip the installation (⚠️ However, it is strongly recommended to configure one in the production environment).
> We recommend using and providing long-term support for VictoriaMetrics as the storage solution.
QuestDB is an open-source time-series database that stands out in the field of time-series data processing due to its high performance and low latency. We use it to store and analyze the collected historical monitoring metric data.
**⚠️ Note: Configuring a time-series database is optional, but it is strongly recommended for production environments to ensure more comprehensive historical chart functions, high performance, and stability.**
**⚠️ If no time-series database is configured, only the historical data of the last hour will be retained.**
> If you already have an existing QuestDB environment, you can skip directly to the YML configuration step.
## Install QuestDB<!-- markdownlint-disable MD029 -->
1. Download the installation package
​ Download the latest version for your operating system from the official GitHub repository:
```shell
# For Linux/macOS (taking v7.3.9 as an example; replace with the latest version number)
wget https://github.com/questdb/questdb/releases/download/7.3.9/questdb-7.3.9-no-jre-bin.tar.gz
# Extract the package
tar -zxvf questdb-7.3.9-no-jre-bin.tar.gz
mv questdb-7.3.9 /opt/questdb # Move to a common directory
```
​ For Windows users:
​ Download the zip package and extract it to C:\questdb or a custom directory.
2. Start QuestDB
```shell
# For Linux/macOS: Navigate to the installation directory and start the service
cd /opt/questdb/bin
./questdb start
# For Windows (Command Prompt):
cd C:\questdb\bin
questdb.exe start
```
3. Set up access password
​ QuestDB enables authentication through a configuration file, which needs to be modified manually.
​ Edit the configuration file:
```shell
# For Linux/macOS
vi /opt/questdb/conf/server.conf
# For Windows
notepad C:\questdb\conf\server.conf
```
​ Enable authentication and configure the password:
```shell
# Enable authentication (disabled by default)
http.security.enabled=true
pg.security.enabled=true # PostgreSQL protocol authentication
# Set admin account and password (customize as needed)
http.security.admin.username=admin
http.security.admin.password=YourStrongPassword123!
# Optional: Restrict Web Console access to specific IPs (e.g., local access only)
http.bind.to=127.0.0.1:9000
```
​ Restart QuestDB for the changes to take effect:
```shell
# For Linux/macOS
./questdb stop
./questdb start
# For Windows
questdb.exe stop
questdb.exe start
```
4. Configure QuestDB connection in HertzBeat's application.yml file
​ Modify HertzBeat's configuration file
​ Locate and edit the configuration file at hertzbeat/config/application.yml
​ ⚠️ Note: For Docker container deployment, you need to mount the application.yml file to the host machine. For the installation package deployment, simply extract the package and modify the file at hertzbeat/config/application.yml.
​ **Set the** **warehouse.store.duckdb.enabled** **parameter to** **false****, configure the** **warehouse.store.questdb** **data source parameters (HOST, username, password, etc.), and set** **enabled** **to** **true** **to enable QuestDB.**
```yaml
warehouse:
store:
# Disable the default DuckDB
duckdb:
enabled: false
# Enable QuestDB
questdb:
enabled: true
url: localhost:9000
username: admin
password: quest
```
Parameter Description:
| Parameter Name | Description |
| -------------- | ------------------------------ |
| enabled | Whether to enable QuestDB |
| url | QuestDB server URL (host:port) |
| username | QuestDB database account |
| password | QuestDB database password |
> **Note:** Due to QuestDB's architectural design, if you need to set an expiration time for data, you can configure it in QuestDB's configuration file server.conf:
```shell
cairo.default.ttl=30d
```
5. Restart HertzBeat
<!-- markdownlint-enable MD029 -->
home/docs/start/quickstart.md
+166
View File
@@ -0,0 +1,166 @@
---
id: quickstart
title: HertzBeat Quick Start - Install in 5 Minutes
sidebar_label: Quick Start
description: Install Apache HertzBeat monitoring system in minutes using Docker, package, or source code. Step-by-step guide for X86 and ARM64 systems.
---
## How to Install HertzBeat?
Install Apache HertzBeat™ in under 5 minutes using Docker with a single command. HertzBeat supports Docker, binary packages, and source code installation on X86/ARM64 architectures.
**Quick Install Command:** `docker run -d -p 1157:1157 -p 1158:1158 --name hertzbeat apache/hertzbeat`
## Installation Methods
HertzBeat provides multiple installation options:
1. **Docker** (Recommended) - Fastest setup, production-ready
2. **Binary Package** - Traditional deployment with manual configuration
3. **Source Code** - For development and customization
4. **Docker Compose** - Full stack with database and time-series storage
### Installation Method Comparison
| Method | Setup Time | Difficulty | Use Case |
|--------|-----------|-----------|----------|
| Docker | 2 minutes | Easy | Production, testing |
| Package | 10 minutes | Medium | Custom configurations |
| Source Code | 30 minutes | Advanced | Development |
| Docker Compose | 5 minutes | Easy | Full stack deployment |
## Installation Instructions
### 1：Install quickly via docker
1. Just one command to get started:
```docker run -d -p 1157:1157 -p 1158:1158 --name hertzbeat apache/hertzbeat```
2. Access `http://localhost:1157` to start, default account: `admin/hertzbeat`
3. Deploy collector clusters(Optional)
```shell
docker run -d -e IDENTITY=custom-collector-name -e MANAGER_HOST=127.0.0.1 -e MANAGER_PORT=1158 --name hertzbeat-collector apache/hertzbeat-collector
```
- `-e IDENTITY=custom-collector-name` : set the collector unique identity name.
- `-e MODE=public` : set the running mode(public or private), public cluster or private cloud-edge.
- `-e MANAGER_HOST=127.0.0.1` : set the main hertzbeat server ip.
- `-e MANAGER_PORT=1158` : set the main hertzbeat server port, default 1158.
Detailed config refer to [Install HertzBeat via Docker](https://hertzbeat.apache.org/docs/start/docker-deploy)
#### 2：Install via package
1. Download the release package `apache-hertzbeat-xx-bin.tar.gz` [Download Page](https://hertzbeat.apache.org/docs/download)
2. Configure the HertzBeat configuration yml file `hertzbeat/config/application.yml` (optional)
3. Run command `$ ./bin/startup.sh` or `bin/startup.bat`
4. Access `http://localhost:1157` to start, default account: `admin/hertzbeat`
5. Deploy collector clusters(Optional)
- If you do not need external JDBC drivers from `ext-lib`, prefer the native collector package for faster startup and lower memory usage. MySQL, MariaDB, and OceanBase can use the built-in query engine directly when `mysql-connector-j` is not provided. TiDB follows the same rule for its SQL query metric set. See [Native Collector Guide](native-collector).
- Download the release package `apache-hertzbeat-collector-xx-bin.tar.gz` (JVM collector) or the native collector package for your target platform, such as `apache-hertzbeat-collector-native-xx-linux-amd64-bin.tar.gz` or `apache-hertzbeat-collector-native-xx-windows-amd64-bin.zip`, to the new machine [Download Page](https://hertzbeat.apache.org/docs/download)
- Configure the collector configuration yml file `hertzbeat-collector/config/application.yml`: unique `identity` name, running `mode` (public or private), hertzbeat `manager-host`, hertzbeat `manager-port`
```yaml
collector:
dispatch:
entrance:
netty:
enabled: true
identity: ${IDENTITY:}
mode: ${MODE:public}
manager-host: ${MANAGER_HOST:127.0.0.1}
manager-port: ${MANAGER_PORT:1158}
```
- Native collector trade-offs: platform-specific packages, no runtime `ext-lib` JDBC loading, and less suitable for JVM-style runtime classpath extension. See [Native Collector Guide](native-collector).
- If `mysql-connector-j` is present in `ext-lib`, the built-in server collector or JVM collector automatically prefers JDBC for MySQL, MariaDB, and OceanBase after restart. TiDB follows the same rule for its SQL query metric set, while its HTTP metrics stay unchanged. Oracle and DB2 still require the JVM collector package because they depend on external JDBC drivers.
- Run command `$ ./bin/startup.sh` or `bin/startup.bat` for the JVM collector package. Run `$ ./bin/startup.sh` for Linux or macOS native collector packages, and `bin\\startup.bat` for the Windows native collector package.
- Access the HertzBeat server dashboard at `http://localhost:1157` and confirm the new collector is registered.
Detailed config refer to [Install HertzBeat via Package](package-deploy)
##### 3：Start via source code
1. Local source code debugging needs to start the back-end project `manager` and the front-end project `web-app`.
2. Backend：need `maven3+`, `java25`, `lombok`, start the `hertzbeat-startup` service.
3. Web：need `nodejs` and `pnpm` environment, run `pnpm install` then `pnpm start` in `web-app` directory after backend startup.
4. Access `http://localhost:4200` to start, default account: `admin/hertzbeat`
Detailed steps refer to [CONTRIBUTING](../community/contribution)
##### 4：Install All(hertzbeat+postgresql+tsdb) via Docker-compose
Install and deploy the postgresql/mysql database, victoria-metrics/iotdb/tdengine database and hertzbeat at one time through [docker-compose deployment script](https://github.com/apache/hertzbeat/tree/master/script/docker-compose).
Detailed steps refer to [Install via Docker-Compose](https://github.com/apache/hertzbeat/tree/master/script/docker-compose)
##### 5. Install All(hertzbeat+collector+postgresql+tsdb) via kubernetes helm charts
Install HertzBeat cluster in a Kubernetes cluster by Helm chart.
Detailed steps refer to [Artifact Hub](https://artifacthub.io/packages/helm/hertzbeat/hertzbeat)
## Installation FAQ
### What are HertzBeat's system requirements?
**Minimum Requirements:**
- 2 CPU cores
- 4GB RAM
- 10GB disk space
- Docker 20.10+ or Java 25+
**Operating Systems:** Linux, macOS, Windows (via Docker or WSL)
### What ports does HertzBeat use?
- **1157** - Web UI and API
- **1158** - Collector communication (cluster mode only)
### How do I verify HertzBeat is running?
1. Check container status: `docker ps | grep hertzbeat`
2. Access web UI: `http://localhost:1157`
3. Login with: admin/hertzbeat
### Can I change the default password?
Yes. After first login, navigate to Settings → Account Management to change the password.
### How do I upgrade HertzBeat?
**Docker upgrade:**
```bash
docker stop hertzbeat
docker rm hertzbeat
docker pull apache/hertzbeat:latest
docker run -d -p 1157:1157 -p 1158:1158 --name hertzbeat apache/hertzbeat
```
### What database does HertzBeat use?
HertzBeat uses H2 embedded database by default. For production, configure external databases:
- **Metadata:** MySQL, PostgreSQL
- **Time-series data:** VictoriaMetrics, IoTDB, TDengine, InfluxDB
### How do I add my first monitor?
1. Login to web UI
2. Click "Monitors" → "New Monitor"
3. Select monitoring type (e.g., MySQL, Linux, Website)
4. Enter IP, port, credentials
5. Click "Confirm" to start monitoring
### Where can I get help?
- **Documentation:** [https://hertzbeat.apache.org/docs/](https://hertzbeat.apache.org/docs/)
- **GitHub Issues:** [https://github.com/apache/hertzbeat/issues](https://github.com/apache/hertzbeat/issues)
- **Community:** [https://hertzbeat.apache.org/docs/community/contact](https://hertzbeat.apache.org/docs/community/contact)
**HAVE FUN**
home/docs/start/rainbond-deploy.md
+50
View File
@@ -0,0 +1,50 @@
---
id: rainbond-deploy
title: Use Rainbond Deploy HertzBeat
sidebar_label: Install via Rainbond
---
If you are unfamiliar with Kubernetes, and want to install Apache HertzBeat™ in Kubernetes, you can use Rainbond to deploy. Rainbond is a cloud-native application management platform built on Kubernetes and simplifies the application deployment to Kubernetes.
## Rainbond Cloud deployment
If you want to deploy "HertzBeat" on "Rainbond Cloud" in one click, you can follow the steps below to do so.
- Open the details of the [HertzBeat application](https://hub.grapps.cn/marketplace/apps/753)
![HertzBeat app desc](/img/docs/start/hertzbeat-desc.png)
- Log in to your Rainbond Cloud account. If you don't have an account, register one in advance!
![Rainbond Cloud](/img/docs/start/rainbond-cloud.png)
- Select the version for installation
![hertzbeat versions](/img/docs/start/hertzbeat-versions.png)
## Open-source Rainbond deployment
### Prerequisites
To install Rainbond, please refer to [Rainbond Quick Install](https://www.rainbond.com/docs/quick-start/quick-install)。
### Deploy HertzBeat
After logging in Rainbond, click Market in the left menu, switch to open source app store, and search HertzBeat in the search box, and click the Install button.
![HertzBeat](/img/docs/start/install-to-rainbond-en.png)
Fill in the following information, and click Confirm button to install.
- Team: select a team or create a new team
- Cluster: select a cluster
- Application: select an application or create a new application
- Version: select a version
After installation, HertzBeat can be accessed via the Access button.
![HertzBeat](/img/docs/start/hertzbeat-topology-en.png)
:::tip
HertzBeat installed via Rainbond, External Mysql database and Redis and IoTDB are used by default, The HertzBeat configuration file is also mounted, which can be modified in `Components -> Environment Configuration -> Configuration File Settings`.
:::
home/docs/start/tdengine-init.md
+125
View File
@@ -0,0 +1,125 @@
---
id: tdengine-init
title: Use Time Series Database TDengine to Store Metrics Data (Optional)
sidebar_label: Metrics Store TDengine
---
Apache HertzBeat's historical data storage relies on the time series database, you can choose one of them to install and initialize, or not to install (note ⚠️ but it is strongly recommended to configure in the production environment)
> It is recommended to use VictoriaMetrics as metrics storage.
TDengine is an open-source IoT time-series database, which we use to store the collected historical data of monitoring metrics. Pay attention to support ⚠️ 3.x version.
**Note⚠️ Time series database is optional, but production environment configuration is strongly recommended to provide more complete historical chart functions and high performance**
**⚠️ If you do not configure a time series database, only the last hour of historical data is retained.**
Note⚠️ Need TDengine 3.x Version.
> If you have TDengine environment, can directly skip to create a database instance.
## Install TDengine via Docker
1. Download and install Docker environment
Docker tools download refer to [Docker official document](https://docs.docker.com/get-docker/).
After the installation you can check if the Docker version normally output at the terminal.
```shell
$ docker -v
Docker version 20.10.12, build e91ed57
```
2. Install TDengine with Docker
```shell
$ docker run -d -p 6030-6049:6030-6049 -p 6030-6049:6030-6049/udp \
-v /opt/taosdata:/var/lib/taos \
--name tdengine -e TZ=Asia/Shanghai \
tdengine/tdengine:3.0.4.0
```
`-v /opt/taosdata:/var/lib/taos` is local persistent mount of TDengine data directory. `/opt/taosdata` should be replaced with the actual local directory.
`-e TZ="Asia/Shanghai"` can set time zone for TDengine.Set up the corresponding time zone you want.
use```$ docker ps``` to check if the database started successfully
### Create database instance
1. Enter database Docker container
```shell
docker exec -it tdengine /bin/bash
```
2. Create database named hertzbeat
After entering the container，execute `taos` command as follows:
```shell
root@tdengine-server:~/TDengine-server# taos
Welcome to the TDengine shell from Linux, Client Version
Copyright (c) 2020 by TAOS Data, Inc. All rights reserved.
taos>
```
execute commands to create database
```shell
taos> show databases;
taos> CREATE DATABASE hertzbeat KEEP 90 DURATION 10 BUFFER 16;
```
The above statements will create a database named hertzbeat. The data will be saved for 90 days (more than 90 days data will be automatically deleted).
A data file every 10 days, memory blocks buffer is 16MB.
3. Check if hertzbeat database has been created success
```shell
taos> show databases;
taos> use hertzbeat;
```
**Note⚠️If you install TDengine using package**
> In addition to start the server，you must execute `systemctl start taosadapter` to start adapter
### Configure the database connection in hertzbeat `application.yml` configuration file
1. Configure HertzBeat's configuration file
Modify `hertzbeat/config/application.yml` configuration file
Note⚠️The docker container way need to mount application.yml file locally,while you can use installation package way to unzip and modify `hertzbeat/config/application.yml`
Replace `warehouse.store.td-engine` data source parameters, URL account and password.
```yaml
warehouse:
store:
# disable jpa
jpa:
enabled: false
# enable td-engine
td-engine:
enabled: true
driver-class-name: com.taosdata.jdbc.rs.RestfulDriver
url: jdbc:TAOS-RS://localhost:6041/hertzbeat
username: root
password: taosdata
```
2. Restart HertzBeat
### FAQ
1. Do both the time series databases IoTDB and TDengine need to be configured? Can they both be used?
> You don't need to configure all of them, you can choose one of them. Use the enable parameter to control whether it is used or not. You can also install and configure neither, which only affects the historical chart data.
2. The historical chart of the monitoring page is not displayed, and pops up [Unable to provide historical chart data, please configure to rely on the time series database]
> As shown in the pop-up window, the premise of displaying the history chart is to install and configure the dependent services of hertzbeat - IotDB database or TDengine database
3. The historical picture of monitoring details is not displayed or has no data, and TDengine has been deployed
> Please confirm whether the installed TDengine version is 3.x, version 2.x are not compatible.
4. The TDengine database is installed and configured, but the page still displays a pop-up [Unable to provide historical chart data, please configure the dependent time series database]
> Please check if the configuration parameters are correct
> Is td-engine enable set to true
> Note⚠️If both hertzbeat and TDengine are started under the same host for docker containers, 127.0.0.1 cannot be used for communication between containers by default, and the host IP is changed
> You can check the startup logs according to the logs directory
home/docs/start/update-1.6.0.md
+161
View File
@@ -0,0 +1,161 @@
---
id: 1.6.0-update
title: How to update to 1.6.0
sidebar_label: Update to 1.6.0 guide
---
## HertzBeat 1.6.0 Upgrade Guide
:::note
This guide is applicable for upgrading from 1.5.0 to version 1.6.0.
If you are using an older version, it is recommended to reinstall using the export function, or upgrade to 1.5.0 and then follow this guide to 1.6.0.
:::
Follow the [HertzBeat New Version Upgrade](upgrade)
## Binary Installation Package Upgrade
### Upgrade Java Environment
Since version 1.6.0 uses Java 17 and the installation package no longer provides a built-in JDK version, use the new HertzBeat according to the following situations:
- When the default environment variable on your server is Java 17, you do not need to take any action for this step.
- When the default environment variable on your server is not Java 17, such as Java 8 or Java 11, and if there are no other applications on your server that require a lower version of Java, download the appropriate version from [https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html) according to your system, and search the engine for how to set a new environment variable pointing to the new Java 17.
- When the default environment variable on your server is not Java 17, such as Java 8 or Java 11, and if there are other applications on your server that require a lower version of Java, download the appropriate version from [https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html) according to your system, and rename the extracted folder to `java`, then copy it to the HertzBeat extraction directory.
### Upgrade Database
Go to [https://github.com/apache/hertzbeat/tree/master/hertzbeat-startup/src/main/resources/db/migration](https://github.com/apache/hertzbeat/tree/master/hertzbeat-startup/src/main/resources/db/migration), choose the directory of your database and execute the corresponding `V160__update_column.sql` file for the upgrade SQL.
### Upgrade Configuration Files
Due to significant changes in `application.yml` and `sureness.yml`, it is recommended to directly use the new `yml` configuration files and then modify them based on your own needs.
#### `application.yml` generally needs to modify the following parts
Default is:
```yaml
datasource:
driver-class-name: org.h2.Driver
username: sa
password: 123456
url: jdbc:h2:./data/hertzbeat;MODE=MYSQL
hikari:
max-lifetime: 120000
jpa:
show-sql: false
database-platform: org.eclipse.persistence.platform.database.MySQLPlatform
database: h2
properties:
eclipselink:
logging:
level: SEVERE
```
If you change to a MySQL database, here is an example:
```yaml
datasource:
driver-class-name: com.mysql.cj.jdbc.Driver
username: root
password: root
url: jdbc:mysql://localhost:3306/hertzbeat?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai
hikari:
max-lifetime: 120000
jpa:
show-sql: false
database-platform: org.eclipse.persistence.platform.database.MySQLPlatform
database: mysql
properties:
eclipselink:
logging:
level: SEVERE
```
#### `sureness.yml` modification is optional, usually when you need to change account passwords
```yaml
# account info config
# eg: admin has role [admin,user], password is hertzbeat
# eg: tom has role [user], password is hertzbeat
# eg: lili has role [guest], plain password is lili, salt is 123, salted password is 1A676730B0C7F54654B0E09184448289
account:
- appId: admin
credential: hertzbeat
role: [admin]
- appId: tom
credential: hertzbeat
role: [user]
- appId: guest
credential: hertzbeat
role: [guest]
- appId: lili
# credential = MD5(password + salt)
# plain password: hertzbeat
# attention: digest authentication does not support salted encrypted password accounts
credential: 94C6B34E7A199A9F9D4E1F208093B489
salt: 123
role: [user]
```
### Add the corresponding database drivers
Due to the Apache Foundation's requirements for license compliance, HertzBeat's installation package cannot include dependencies with GPL licenses such as MySQL, Oracle, etc. Users need to add them themselves. Users can download the drivers from the following links and copy them to the `ext-lib` directory of the installation:
- MySQL: [https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-java-8.0.25.zip](https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-java-8.0.25.zip)
- Oracle (If you want to monitor Oracle, these two drivers are required):
- [https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc8/23.4.0.24.05/ojdbc8-23.4.0.24.05.jar](https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc8/23.4.0.24.05/ojdbc8-23.4.0.24.05.jar)
- [https://repo.mavenlibs.com/maven/com/oracle/database/nls/orai18n/21.5.0.0/orai18n-21.5.0.0.jar](https://repo.mavenlibs.com/maven/com/oracle/database/nls/orai18n/21.5.0.0/orai18n-21.5.0.0.jar)
Next, run the start-up script as before to experience the latest HertzBeat 1.6.0!
## Docker Upgrade - Mysql Database
- Stop the HertzBeat container:
```shell
docker stop hertzbeat
```
- Upgrade the database script:
- Go to [https://github.com/apache/hertzbeat/tree/master/hertzbeat-startup/src/main/resources/db/migration](https://github.com/apache/hertzbeat/tree/master/hertzbeat-startup/src/main/resources/db/migration), choose the directory of your database and execute the corresponding `V160__update_column.sql` file in MySQL.
- Upgrade the configuration files:
- As mentioned, due to significant changes in `application.yml` and `sureness.yml`, it is recommended to directly mount and use the new `yml` configuration files, and then modify them based on your own needs.
- Add the corresponding database drivers:
- Due to the Apache Foundation's license compliance requirements, HertzBeat's installation package cannot include MySQL, Oracle, and other GPL-licensed dependencies. Users need to add them themselves by downloading the driver jars from the above links and placing them in the local `ext-lib` directory, then mounting `ext-lib` to the container's `/opt/hertzbeat/ext-lib` directory when starting.
Next, run HertzBeat using Docker as before to experience the latest HertzBeat 1.6.0!
## Docker Installation Upgrade - H2 Built-in Database (Not recommended for production use)
- Stop the HertzBeat container:
```shell
docker stop hertzbeat
```
- Edit the H2 database files:
- Assuming you have mounted the H2 database files in the `data` directory to the local system, or copied the `/opt/hertzbeat/data` directory from the old container manually.
- Download the H2 driver jar from [https://mvnrepository.com/artifact/com.h2database/h2/2.2.220](https://mvnrepository.com/artifact/com.h2database/h2/2.2.220).
- Start the database locally using the H2 driver jar:
```shell
java -jar h2-2.2.220.jar -url jdbc:h2:file:./hertzbeat -user sa -password 123456
```
- Upgrade the configuration files:
- As mentioned, due to significant changes in `application.yml` and `sureness.yml`, it is recommended to directly mount and use the new `yml` configuration files, and then modify them based on your own needs.
- Add the corresponding database drivers:
- As mentioned, due to the Apache Foundation's license compliance requirements, HertzBeat's installation package cannot include MySQL, Oracle, and other GPL-licensed dependencies. Users need to add them themselves by downloading the driver jars from the above links and placing them in the local `ext-lib` directory, then mounting `ext-lib` to the container's `/opt/hertzbeat/ext-lib` directory when starting.
Next, run the Docker to start HertzBeat as before to experience the latest HertzBeat 1.6.0!
## Upgrade via Export and Import
If you do not want to go through the tedious script upgrade method mentioned above, you can directly export and import the monitoring tasks and threshold information from the old environment.
- Deploy a new environment with the latest version.
- Export the monitoring tasks and threshold information from the old environment on the page
home/docs/start/update-1.7.0.md
+41
View File
@@ -0,0 +1,41 @@
---
id: 1.7.0-update
title: How to update to 1.7.0
sidebar_label: Update to 1.7.0 guide
---
## HertzBeat 1.7.0 Upgrade Guide
:::note
This guide is applicable for upgrading from 1.6.x to version 1.7.0.
If you are using an older version, it is recommended to reinstall using the export function, or upgrade to 1.6.0 and then follow this guide to 1.7.0.
:::
Follow the [HertzBeat New Version Upgrade](upgrade)
## Installation Upgrade
### Upgrade Database
In 1.7.0, we use the `label` instead of `tag`, in some environment, we need drop or delete the table `hzb_tag_monitor_bind` in database.
```sql
DELETE FROM hzb_tag_monitor_bind;
```
### Upgrade Alarm Threshold
In 1.7.0, we redesign the new alarm threshold, include the Real-Time Threshold and Scheduled Threshold.
We need reconfigure the alarm threshold, alarm group by manual.
:::tip
There are no default built-in threshold rules, such as the previous availability threshold.
So if you find that there is no alarm after the monitoring is down, you need to configure the corresponding availability threshold yourself.
:::
## Upgrade via Export and Import
If you do not want to go through the tedious script upgrade method mentioned above, you can directly export and import the monitoring tasks and threshold information from the old environment.
- Deploy a new environment with the latest version.
- Export the monitoring tasks and threshold information from the old environment on the page
home/docs/start/upgrade.md
+46
View File
@@ -0,0 +1,46 @@
---
id: upgrade
title: HertzBeat New Version Upgrade
sidebar_label: Version Upgrade Guide
---
**HertzBeat Release Version List**
- [Download Page](https://hertzbeat.apache.org/docs/download)
- [Github Release](https://github.com/apache/hertzbeat/releases)
- [DockerHub Release](https://hub.docker.com/r/apache/hertzbeat/tags)
Apache HertzBeat's metadata information is stored in H2 or Mysql, PostgreSQL relational databases, and the collected metric data is stored in time series databases such as TDengine and IotDB.
**You need to save and back up the data files of the database and monitoring templates yml files before upgrading**
## Upgrade For Docker Deploy
1. If using custom monitoring templates
- Need to back up docker templates directory `docker cp hertzbeat:/opt/hertzbeat/define ./define` in the container `/opt/hertzbeat/define`
- `docker cp hertzbeat:/opt/hertzbeat/define ./define`
- And mount the template define directory when docker start `-v $(pwd)/define:/opt/hertzbeat/define`
- `-v $(pwd)/define:/opt/hertzbeat/define`
2. If using the built-in default H2 database
- Need to mount or back up `-v $(pwd)/data:/opt/hertzbeat/data` database file directory in the container `/opt/hertzbeat/data`
- Stop and delete the container, delete the local HertzBeat docker image, and pull the new version image
- Refer to [Docker installation of HertzBeat](./docker-deploy) to create a new container using a new image. Note that the database file directory needs to be mounted `-v $(pwd)/data:/opt/hertzbeat/data`
3. If using external relational database Mysql, PostgreSQL
- No need to mount the database file directory in the backup container
- Stop and delete the container, delete the local HertzBeat docker image, and pull the new version image
- Refer to [Docker installation HertzBeat](./docker-deploy) to create a new container using the new image, and configure the database connection in `application.yml`
### Upgrade For Package Deploy
1. If using the built-in default H2 database
- Back up the database file directory under the installation package `/opt/hertzbeat/data`
- If there is a custom monitoring template, you need to back up the template YML under `/opt/hertzbeat/define`
- `bin/shutdown.sh` stops the HertzBeat process and downloads the new installation package
- Refer to [Installation package to install HertzBeat](./package-deploy) to start using the new installation package
2. If using external relational database Mysql, PostgreSQL
- No need to back up the database file directory under the installation package
- If there is a custom monitoring template, you need to back up the template YML under `/opt/hertzbeat/define`
- `bin/shutdown.sh` stops the HertzBeat process and downloads the new installation package
- Refer to [Installation package to install HertzBeat](./package-deploy) to start with the new installation package and configure the database connection in `application.yml`
**HAVE FUN**
home/docs/start/usecase/linux-os-practice.md
+94
View File
@@ -0,0 +1,94 @@
---
id: linux-os-practice
title: Linux Operating System Monitoring Practice
sidebar_label: Linux Operating System Monitoring Practice
---
This article describes how to use the HertzBeat monitoring system to collect and monitor general performance metrics for Linux operating systems, and send us alert messages when file system usage is too high.
## What's HertzBeat
Apache HertzBeat™ is a real-time monitoring tool with powerful custom monitoring capabilities without Agent. Website monitoring, port availability, database, operating system, threshold alarms, alarm notification (email, WeChat, DingTalk, Feishu).
github: [https://github.com/apache/hertzbeat](https://github.com/apache/hertzbeat)
## Install
1. The `docker` environment can be installed with just one command
```bash
docker run -d -p 1157:1157 -p 1158:1158 --name hertzbeat apache/hertzbeat
```
2. After the installation is successful, the browser can access `http://ip:1157` to start, the default account password is `admin/hertzbeat`.
:::note
The production environment recommends a complete deployment method, refer [Install HertzBeat via Docker Compose](https://hertzbeat.apache.org/docs/start/docker-compose-deploy)
:::
## Monitoring Linux Operating System
### 1. Click Add Linux Operating System Monitor
> HertzBeat Page -> Monitors -> New Monitor -> OS Monitor -> Add OS Linux
![HertzBeat](/img/docs/start/linux-os-practice-1.png)
### 2. Configure the monitoring parameters
- **Target Host**：The IPV4, IPV6, or domain name of the host being monitored. No protocol header (e.g., https://, http://).
- **Port**：The port provided by Linux SSH, default is 22.
- **Timeout**：Sets the connection timeout in milliseconds, default is 6000 ms.
- **Reuse Connection**: Sets whether SSH connections are reused, default is :false. If false, a new connection is created each time information is retrieved.
- **Username**: SSH connection username
- **Password**: SSH connection password, optional.
> For more parameters and advanced settings, please refer to the help documentation: [Monitoring：Linux operating system monitoring](https://hertzbeat.apache.org/docs/help/linux)
Tasks can be managed using label classification, such as adding bind labels like `OS=Linux`.
![HertzBeat](/img/docs/start/linux-os-practice-2.png)
### 3. View the detection index data
In the monitoring list, you can view the monitoring status, and in the monitoring details, you can view the metric data chart, etc.
![HertzBeat](/img/docs/start/linux-os-practice-3.png)
![HertzBeat](/img/docs/start/linux-os-practice-4.png)
### 4. Set the threshold
Here, we set a threshold rule to trigger an alert when **the usage rate of a certain directory in the file system is too high**.
> HertzBeat Page -> Alerting -> Threshold -> New Threshold -> RealTime Threshold Rule
>
> Configure the threshold, configure the alarm expression-triggered when the metric`Disk Usage` greater than or equal to `50%`，set the alarm level notification template information, etc.
![HertzBeat](/img/docs/start/linux-os-practice-5.png)
> Threshold rule has others function you can try e.g., associating thresholds with monitoring, trigger times so on.
Finally, you can see the triggered alarm in the alarm center.
![HertzBeat](/img/docs/start/linux-os-practice-6.png)
### 5. Alarm notification
> HertzBeat Page -> Notification -> Notice Receiver -> New Receiver -> Configure the Email Receiver
![HertzBeat](/img/docs/start/linux-os-practice-7.png)
> HertzBeat Page -> Notification -> Notice Policy -> New Notice Policy -> Enable Notification for the Recipient Just Configured
![HertzBeat](/img/docs/start/linux-os-practice-8.png)
When the threshold is triggered, we can receive the corresponding alarm message. If there is no notification, you can also view the alarm information in the alarm center.
----
## Summary
The practice of monitoring linux operating system is here. Of course, for HertzBeat, this function is just the tip of the iceberg. If you think HertzBeat is a good open source project, please give us a Star on GitHub, thanks for your support.
**Github: [https://github.com/apache/hertzbeat](https://github.com/apache/hertzbeat)**
home/docs/start/usecase/springboot-auto-practice.md
+245
View File
@@ -0,0 +1,245 @@
---
id: springboot-auto-practice
title: SpringBoot Web Application Monitoring Practice
sidebar_label: SpringBoot Web Application Monitoring Practice
---
:::tip
In the cloud-native era, monitoring and visualization of SpringBoot applications have become core components of O&M (Operations & Maintenance) systems. Real-time monitoring of application performance is crucial for ensuring system stability.
:::
This article introduces an integrated solution using the HertzBeat monitoring system, covering metric collection, visualization, and alarm notifications. It demonstrates the complete operational procedure and monitoring practices.
## What is HertzBeat
Apache HertzBeat is a real-time monitoring tool with powerful custom monitoring capabilities without Agent. Website monitoring, PING connectivity, port availability, database, operating system, middleware, API monitoring, threshold alarms, alarm notification (email, WeChat, Ding Ding Feishu).
**github: [https://github.com/apache/hertzbeat](https://github.com/apache/hertzbeat)**
## Install HertzBeat
> For production environments, it is recommended to deploy HertzBeat using **PostgreSQL** + **VictoriaMetrics**.
1. Deploy HertzBeat
> Download the installation package
>
> Download the `apache-hertzbeat-xxx-incubating-bin.tar.gz` installation package corresponding to your system environment from the [Download Page](https://hertzbeat.apache.org/docs/download). Extract the package to a host directory, e.g., `/opt/hertzbeat`.
```sh
tar zxvf apache-hertzbeat-xxx-incubating-bin.tar.gz
```
2. Quick Install PostgreSQL + VictoriaMetrics Services
> Install PostgreSQL via Docker
```sh
docker run -d --name postgresql -p 5432:5432 -v "$PWD/postgresql:/var/lib/postgresql/data" -e POSTGRES_USER=root -e POSTGRES_PASSWORD=123456 -e TZ=Asia/Shanghai postgres:15
```
> Install VictoriaMetrics via Docker
```sh
docker run -d -p 8428:8428 -v "$PWD/victoria-metrics-data:/victoria-metrics-data" --name victoria-metrics victoriametrics/victoria-metrics:v1.95.1
```
3. Modify HertzBeat's Configuration File
> Switch the metadata storage data source
>
> Modify the `hertzbeat/config/application.yml` configuration file to use the PostgreSQL service.
:::note
For PostgreSQL configuration details, please refer to the documentation: [Meta Store PostgreSQL (Recommended)](https://hertzbeat.apache.org/docs/start/postgresql-change)
:::
> Configure the time-series database for metric storage
>
> Modify the `hertzbeat/config/application.yml` configuration file to enable the VictoriaMetrics service for storing metrics.
:::note
For VictoriaMetrics configuration details, please refer to the documentation: [Metrics Store VictoriaMetrics (Recommended)](https://hertzbeat.apache.org/docs/start/victoria-metrics-init)
:::
4. Start HertzBeat
> Use the `startup.sh` script located in the `bin` directory of the extracted installation folder. For Windows environments, use `startup.bat`.
>
> After successful startup, access `http://localhost:1157` in your browser to begin. The default username and password are `admin/hertzbeat`.
```sh
./startup.sh
```
## SpringBoot Application Configuration
1. Enable Actuator Configuration
> Add the following dependencies to project's `pom.xml`:
```xml
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-registry-prometheus</artifactId>
</dependency>
```
> Configure `application.yml` to expose endpoints:
```yml
management:
endpoints:
web:
exposure:
include: '*'
enabled-by-default: true
metrics:
export:
prometheus:
enabled: true
```
> *Note: If your project also introduces authentication related dependencies, such as springboot security, the interfaces exposed by SpringBoot Actor may be intercepted. In this case, you need to manually release these interfaces. Taking springboot security as an example, you should add the following code to the Security Configuration class:*
```java
public class SecurityConfig extends WebSecurityConfigurerAdapter{
@Override
protected void configure(HttpSecurity httpSecurity) throws Exception{
httpSecurity
// Configure the interfaces to be opened
.antMatchers("/actuator/**").permitAll()
.antMatchers("/metrics/**").permitAll()
.antMatchers("/trace").permitAll()
.antMatchers("/heapdump").permitAll()
// ...
}
}
```
2. Verify Endpoints
> After starting SpringBoot application, request the following URL:
>
> * `http://<your-host>:<port>`/actuator`: Verify the enabled endpoints.
> * `http://<your-host>:<port>`/actuator/prometheus`: Should return metric data in Prometheus format.
## Monitor SpringBoot Application
1. Add AUTO Monitor
> HertzBeat Page -> Monitors -> New Monitor -> AUTO -> Prometheus Task
![HertzBeat](/img/docs/start/springboot-auto-practice-1.png)
2. Fill in Key Parameters
> **Target Host**: The server address of the SpringBoot application (without the protocol prefix like `http://` or `https://`).
>
> **Port**: The application service port (e.g., `8080`).
>
> **Endpoint Path**: `/actuator/prometheus`
>
> Tasks can be managed using label classification, such as adding Bind Labels like `env=test`.
![HertzBeat](/img/docs/start/springboot-auto-practice-2.png)
3. View Detected Metric Data
> Click on the newly created monitor to view detailed metric data, historical charts, etc.
![HertzBeat](/img/docs/start/springboot-auto-practice-3.png)
![HertzBeat](/img/docs/start/springboot-auto-practice-4.png)
## Grafana Visualization Integration (Optional)
1. Grafana Dashboard Configuration
> Enable Grafana's embedding feature and enable anonymous access.
:::note
For complete configuration details, please refer to the documentation: [Grafana Historical Charts](https://hertzbeat.apache.org/docs/help/grafana_dashboard)
:::
2. Embed Grafana Dashboard in HertzBeat Monitor
> After configuring and enabling Grafana, restart the HertzBeat service. Then, in the newly added AUTO monitor settings, enable Grafana Templates and upload a Grafana dashboard template.
>
> For example: In Grafana, select `hertzbeat-victoria-metrics` as the data source. Then click on the dashboard:「Share」→「Export」→「Save to file」to download the template and upload this file to the HertzBeat monitor.
![HertzBeat](/img/docs/start/springboot-auto-practice-5.png)
3. View Grafana Dashboard
> Go to the AUTO monitor page, click the Grafana icon button, and view the integrated Grafana dashboard.
![HertzBeat](/img/docs/start/springboot-auto-practice-6.png)
## Alarm and Notification Interlinkage
1. HertzBeat Alarm Configuration
> HertzBeat Page -> Alerting -> Threshold -> New -> New Threshold Rule
![HertzBeat](/img/docs/start/springboot-auto-practice-7.png)
> HertzBeat provides two types of threshold rule settings: **RealTime Calculation** and **Periodically execute**. Here, we use the **Periodically execute** threshold rule as an example.
>
> * **Rule Name**: Name of the threshold rule.
> * **Threshold Rule**: Enter the rule for monitoring the metric (supports `PromQL`).
> * **Execution Period**: The time interval for periodically executing the threshold calculation.
> * **Alarm Severity**: The alarm level that triggers the threshold, from low to high: Warning，Critical，Emergency.
> * **Trigger Times**: Set how many times the threshold is triggered before sending an alarm.
> * **Alarm Content**: Enter the content of the monitoring alarm(supports variables).
2. Set Threshold Rule
> For example, to monitor the CPU usage of the SpringBoot application, add a threshold rule like: `system_cpu_usage{job="Jolly_Vulture_43vT"}` > 0.01`
>
>You can create many combinations of threshold rules. Users can set up richer alarm rules based on their specific needs.
![HertzBeat](/img/docs/start/springboot-auto-practice-8.png)
> Finally, you can see the triggered alarm in the alarm center.
![HertzBeat](/img/docs/start/springboot-auto-practice-9.png)
3. Alarm Notification
> HertzBeat Page -> Notification -> Notice Receiver -> New Receiver
![HertzBeat](/img/docs/start/springboot-auto-practice-10.png)
> HertzBeat Page -> Notification -> Notice Policy -> New Notice Policy -> Select Recipient(s) and Enable Notification
![HertzBeat](/img/docs/start/springboot-auto-practice-11.png)
4. OK! When the threshold is triggered, we will receive the corresponding alarm message. If no notification is configured, you can also view the alarm information in the alarm center.
## Quick Summary
This article demonstrates how users can build a complete monitoring system within minutes using simple configurations, highlighting several advantages of HertzBeat:
* Monitors SpringBoot Actuator endpoints without needing to deploy Exporter or Agent, supporting custom metric collection and alert rules.
* Lightweight: Compared to the traditional Prometheus + AlertManager combination, HertzBeat simplifies the deployment and maintenance process.
* Seamless Integration with Grafana: HertzBeat pushes collected time-series data to Grafana in real-time for building visualization dashboards.
* Integrated Monitoring + Alerting + Notification: Combines full protocol coverage, real-time/periodic threshold detection, and multi-channel notifications (DingTalk/Feishu/Webhook, etc.).
------
## Wrapping Up
That concludes this practical guide on monitoring SpringBoot applications with HertzBeat. Of course, this functionality is just the tip of the iceberg for HertzBeat. If you think hertzbeat is a good open source project, please give it a **Star** on GitHub and Gitee! Your Star motivate our continuous improvement! Feel free to light up the little star ✨
**Making monitoring simpler, looking forward to building the ecosystem together!** 💝
**GitHub: [https://github.com/apache/hertzbeat](https://github.com/apache/hertzbeat)**
**Gitee: [https://gitee.com/hertzbeat/hertzbeat](https://gitee.com/hertzbeat/hertzbeat)**
home/docs/start/usecase/sslcert-practice.md
+95
View File
@@ -0,0 +1,95 @@
---
id: ssl-cert-practice
title: SSL Certificate Monitoring Practice
sidebar_label: SSL Certificate Monitoring Practice
---
:::tip
Most websites now support HTTPS by default. The certificate we apply for is usually 3 months or 1 year. It is easy to expire the SSL certificate over time, but we did not find it the first time, or did not update the certificate in time before it expired.
:::
This article introduces how to use the hertzbeat monitoring tool to detect the validity period of our website's SSL certificate, and send us a warning message when the certificate expires or a few days before the certificate expires.
## What is HertzBeat
Apache HertzBeat™ is a real-time monitoring tool with powerful custom monitoring capabilities without Agent. Website monitoring, PING connectivity, port availability, database, operating system, middleware, API monitoring, threshold alarms, alarm notification (email, WeChat, Ding Ding Feishu).
github: [https://github.com/apache/hertzbeat](https://github.com/apache/hertzbeat)
## Install HertzBeat
1. The `docker` environment can be installed with just one command
`docker run -d -p 1157:1157 -p 1158:1158 --name hertzbeat apache/hertzbeat`
2. After the installation is successful, the browser can access `localhost:1157` to start, the default account password is `admin/hertzbeat`
:::note
The production environment recommends a complete deployment method, refer [https://hertzbeat.apache.org/docs/start/docker-compose-deploy](https://hertzbeat.apache.org/docs/start/docker-compose-deploy)
:::
## Monitoring SSL Certificates
1. Click Add SSL Certificate Monitor
> HertzBeat Page -> Monitors -> New Monitor -> Service Monitor -> Add SSL Certificate
![HertzBeat](/img/docs/start/ssl_1.png)
2. Configure the monitoring website
> Here we take the example of monitoring Baidu website, configure monitoring host domain name, name, collection interval, etc.
> Click OK Note
![HertzBeat](/img/docs/start/ssl_2.png)
3. View the detection index data
> In the monitoring list, you can view the monitoring status, and in the monitoring details, you can view the metric data chart, etc.
![HertzBeat](/img/docs/start/ssl_3.png)
![HertzBeat](/img/docs/start/ssl_4.png)
4. Set the threshold (triggered when the certificate expires)
> HertzBeat Page -> Alerting -> Threshold -> New Threshold -> ReadTime Threshold Rule
> Configure the threshold, select the SSL certificate metric object, configure the alarm expression-triggered when the metric `expired` is `true`, that is, `equals(expired,"true")`, set the alarm level notification template information, etc.
![HertzBeat](/img/docs/start/ssl_5.png)
> Threshold rule has others function you can try eg: associating thresholds with monitoring, trigger times so on.
5. Set the threshold (triggered one week before the certificate expires)
> In the same way, switch coding threshold, add a new configuration threshold and configure an alarm expression - when the metric expires timestamp `end_timestamp`, the `now()` function is the current timestamp, if the configuration triggers an alarm one week in advance: `end_timestamp <= (now() + 604800000)` , where `604800000` is the 7-day total time difference in milliseconds.
![HertzBeat](/img/docs/start/ssl_6.png)
> Finally, you can see the triggered alarm in the alarm center.
![HertzBeat](/img/docs/start/ssl_7.png)
6. Alarm notification (in time notification via Dingding WeChat Feishu, etc.)
> HertzBeat Page -> Notification -> Notice Receiver -> New Receiver -> Config the Feishu Receiver
![HertzBeat](/img/docs/start/notice_receiver_1.png)
For token configuration such as Feishu, please refer to the help document
[https://hertzbeat.apache.org/docs/help/alert_feishu](https://hertzbeat.apache.org/docs/help/alert_feishu)
> Notification -> Notice Policy -> New Notice Policy -> Enable Notification for the Recipient Just Configured
![HertzBeat](/img/docs/start/notice_policy_1.png)
7. OK When the threshold is triggered, we can receive the corresponding alarm message. If there is no notification, you can also view the alarm information in the alarm center.
----
## The End
The practice of monitoring SSL certificates is here. Of course, for hertzbeat, this function is just the tip of the iceberg. If you think hertzbeat is a good open source project, please give us a Gitee star on GitHub, thank you very much. Thank you for your support. Refill!
**github: [https://github.com/apache/hertzbeat](https://github.com/apache/hertzbeat)**
home/docs/start/usecase/tdengine-practice.md
+166
View File
@@ -0,0 +1,166 @@
---
id: tdengine-practice
title: TDengine Monitoring Practice
sidebar_label: TDengine Monitoring Practice
---
:::tip
TDengine TSDB is an open-source, high-performance, cloud-native time series database (TSDB) optimized for IoT, vehicle networking, industrial Internet, finance, IT operations, and other scenarios. It also comes with built-in caching, streaming computing, data subscription, and other system functions that greatly reduce system design complexity and lower R&D and operational costs, making it an extremely simple time series data processing platform.
:::
This article introduces how to use the HertzBeat monitoring system to collect and monitor TDengine general performance indicators.
## What is HertzBeat?
Apache HertzBeat™ is a real-time monitoring tool with powerful customization capabilities that does not require an agent. It monitors websites, PING connectivity, port availability, databases, operating systems, middleware, APIs, threshold alerts, and alert notifications (email, WeChat, DingTalk, Feishu).
> **github: [https://github.com/apache/hertzbeat](https://github.com/apache/hertzbeat)**
## Install HertzBeat
1. The `docker` environment can be installed with just one command.
`docker run -d -p 1157:1157 -p 1158:1158 --name hertzbeat apache/hertzbeat`
2. Once installed, you can start by accessing `localhost:1157` in your browser. The default username and password are `admin/hertzbeat`.
:::note
Recommended deployment method for production environments, reference: [https://hertzbeat.apache.org/docs/start/docker-compose-deploy](https://hertzbeat.apache.org/docs/start/docker-compose-deploy)
:::
## Enable TDengine monitoring
:::tip
TDengine TSDB integrates multiple monitoring metric collection mechanisms and aggregates them through taosKeeper. taosKeeper is a monitoring metric export tool for TDengine TSDB version 3.0. With just a few simple configurations, you can obtain the runtime status of TDengine TSDB. For reference: [https://docs.taosdata.com/reference/components/taoskeeper/](https://docs.taosdata.com/reference/components/taoskeeper/)
:::
## Monitor TDengine(PromQL)
1. Added TDengine-PromQL monitoring
> System Page -> Monitoring Center -> Add Monitoring -> Custom Monitoring -> TDengine-PromQL Task
![HertzBeat](/img/docs/start/tdengine_1.png)
2. Fill in key parameters
> **Target Host**: Prometheus application server address (without protocol header, e.g., https://, http://)
>
> **Port**: Prometheus API port, default value: 9090
>
> **Endpoint path**: The URL for Prometheus to query PromQL. Default value: `/api/v1/query`
>
> You can use tags to categorize tasks, such as adding business-related tags like `env=test`.
![HertzBeat](/img/docs/start/tdengine_2.png)
3. View inspection indicator data
> You can view task statuses in the monitoring list and view metric data charts and other information in the monitoring details.
![HertzBeat](/img/docs/start/tdengine_3.png)
![HertzBeat](/img/docs/start/tdengine_4.png)
## Monitor TDengine(Prometheus)
1. New AUTO monitoring
> System Page -> Monitoring Center -> Add Monitoring -> AUTO -> Prometheus Task
![HertzBeat](/img/docs/start/tdengine_1_1.png)
2. Fill in key parameters
> **Target Host** taosKeeper service address (without protocol header, e.g., https://, http://)
>
> **Port**: taosKeeper service port (e.g., 6043)
>
> **Endpoint path**: `/metrics`
>
> You can use tags to categorize tasks, such as adding business-related tags like `env=test`.
![HertzBeat](/img/docs/start/tdengine_1_2.png)
3. View inspection indicator data
> You can view task statuses in the monitoring list and view metric data charts and other information in the monitoring details.
![HertzBeat](/img/docs/start/tdengine_1_3.png)
![HertzBeat](/img/docs/start/tdengine_1_4.png)
### Grafana visualization integration (optional)
1. Grafana chart configuration
> You need to enable Grafana's embeddable feature and allow anonymous access.
:::note
For complete configuration, please refer to the documentation: [Grafana Historical Charts](https://hertzbeat.apache.org/zh-cn/docs/help/grafana_dashboard)
:::
2. Embedding Grafana dashboards in HertzBeat monitoring
> After enabling Grafana, restart the HertzBeat service, enable it in the newly added AUTO monitoring, and upload the Grafana template.
>
> For example: Select the Grafana data source `hertzbeat-victoria-metrics`, then click "Share" → "Export" → "Save to file" on the dashboard to download the template and upload it to HertzBeat monitoring. For reference, see: [taoskeeper-prometheus-dashboard](https://grafana.com/grafana/dashboards/15164-taoskeeper-prometheus-dashboard/)
![HertzBeat](/img/docs/start/tdengine_1_5.png)
3. View Grafana charts
> Go to the new AUTO monitoring page, click the Grafana icon button to view the Grafana chart.
![HertzBeat](/img/docs/start/tdengine_1_6.png)
## Alarm and notification linkage
1. HertzBeat Alert Configuration
> System Page -> Alerts -> Threshold Rules -> Add -> Add Threshold
![HertzBeat](/img/docs/start/tdengine_5.png)
> HertzBeat provides two types of threshold rule settings: **real-time calculation** and **scheduled cycle**. Here, we will use the **scheduled cycle** threshold rule as an example.
>
> * **Threshold Name**: Threshold rule name
> * **Threshold rules**: Fill in the rules for monitoring indicators (supports `PromQL`).
> * **Execution cycle**: The time interval for calculating the periodic execution threshold.
> * **Alarm Level**: The alarm level triggered by the threshold, from low to high: Warning, Critical, Emergency.
> * **Trigger count**: Set the threshold number of times the trigger must occur before an alert is sent.
> * **Alarm content**: Fill in the content of the monitoring alarm (supports filling in variables)
2. Set threshold rules
> For example, to monitor the CPU percentage used by the Dnode node system, add a threshold rule: `taos_dnodes_info_cpu_system_value > 20`
>
> There are many combinations of threshold rules that can be set, and users can set more detailed alert rules according to their needs.
![HertzBeat](/img/docs/start/tdengine_6.png)
> Finally, you can see the triggered alerts in the Alert Center.
![HertzBeat](/img/docs/start/tdengine_7.png)
3. Alert notification
> System Page -> Message Notifications -> Notification Media -> Add New Recipient
![HertzBeat](/img/docs/start/tdengine_8.png)
> System Page -> Message Notifications -> Notification Policies -> Add Notification Policy -> Select recipients and enable notifications
![HertzBeat](/img/docs/start/tdengine_9.png)
4. OK! When the threshold rule is triggered, we will receive the corresponding alert message. If no notification is configured, you can also view the alert information in the alert center.
## Summary
That concludes our practical guide to monitoring TDengine applications. Of course, this feature is just the tip of the iceberg for HertzBeat. If you like this open-source project, please give it a star on GitHub or Gitee. Your stars are what motivate us to keep improving! Please light up the little stars ✨
**Making monitoring simpler, we look forward to building an ecosystem with you!** 💝
**github: [https://github.com/apache/hertzbeat](https://github.com/apache/hertzbeat)**
**gitee: [https://gitee.com/hertzbeat/hertzbeat](https://gitee.com/hertzbeat/hertzbeat)**
home/docs/start/victoria-metrics-init.md
+155
View File
@@ -0,0 +1,155 @@
---
id: victoria-metrics-init
title: Use Time Series Database VictoriaMetrics to Store Metrics Data (Recommended)
sidebar_label: Metrics Store VictoriaMetrics (Recommended)
---
Apache HertzBeat's historical data storage relies on the time series database, you can choose one of them to install and initialize, or not to install (note ⚠️ but it is strongly recommended to configure in the production environment)
> It is recommended to use VictoriaMetrics as metrics storage.
VictoriaMetrics is a fast, cost-effective and scalable monitoring solution and time series database.Recommend Version(VictoriaMetrics:v1.95.1+, HertzBeat:v1.4.3+)
**Note⚠️ Time series database is optional, but production environment configuration is strongly recommended to provide more complete historical chart functions and high performance**
**⚠️ If you do not configure a time series database, only the last hour of historical data is retained.**
> If you already have a VictoriaMetrics environment, you can skip directly to the YML configuration step.
## Install VictoriaMetrics via Docker
1. Download and install Docker environment
Docker tools download refer to [Docker official document](https://docs.docker.com/get-docker/).
After the installation you can check if the Docker version normally output at the terminal.
```shell
$ docker -v
Docker version 20.10.12, build e91ed57
```
2. Install VictoriaMetrics via Docker
```shell
$ docker run -d -p 8428:8428 \
-v $(pwd)/victoria-metrics-data:/victoria-metrics-data \
--name victoria-metrics \
victoriametrics/victoria-metrics:v1.95.1
```
`-v $(pwd)/victoria-metrics-data:/victoria-metrics-data` is local persistent mount of VictoriaMetrics data directory
use```$ docker ps``` to check if the database started successfully
3. Configure the database connection in hertzbeat `application.yml`configuration file
Modify `hertzbeat/config/application.yml` configuration file
Note⚠️The docker container way need to mount application.yml file locally, while you can use installation package way to unzip and modify `hertzbeat/config/application.yml`
Config the `warehouse.store.duckdb.enabled` `false`. Replace `warehouse.store.victoria-metrics` data source parameters, HOST account and password.
```yaml
warehouse:
store:
# disable DuckDB
duckdb:
enabled: false
# enable victoria-metrics
victoria-metrics:
enabled: true
url: http://localhost:8428
username: root
password: root
```
4. Restart HertzBeat
### Use VictoriaMetrics in Cluster Mode
VictoriaMetrics provides a **cluster mode** with separate components for ingestion (`vminsert`), storage (`vmstorage`), and querying (`vmselect`). The following section explains how to deploy VictoriaMetrics in cluster mode and integrate it with HertzBeat.
#### 1. Deploy VictoriaMetrics Cluster via Docker Compose
Create a `docker-compose.yml` file with the following content:
```yaml
version: "3"
services:
vmstorage1:
image: victoriametrics/vmstorage
command:
- "-retentionPeriod=1"
- "-storageDataPath=/storage"
volumes:
- vmstorage-data:/storage
ports:
- "8400:8400" # vminsert connects here
- "8401:8401" # vmselect connects here
vminsert:
image: victoriametrics/vminsert
command:
- "-storageNode=vmstorage1:8400"
- "-httpAuth.username=root"
- "-httpAuth.password=root"
ports:
- "8480:8480" # ingestion endpoint
vmselect:
image: victoriametrics/vmselect
command:
- "-storageNode=vmstorage1:8401"
- "-httpAuth.username=root"
- "-httpAuth.password=root"
ports:
- "8481:8481" # query endpoint
volumes:
vmstorage-data:
```
Start the cluster with:
```shell
docker-compose up -d
```
Check all components are running via:
```shell
docker ps
```
#### 2. Configure HertzBeat for Cluster Mode
Edit the `hertzbeat/config/application.yml` configuration file as follows:
```yaml
warehouse:
store:
duckdb:
enabled: false
victoria-metrics:
cluster:
enabled: true
select:
url: http://127.0.0.1:8481
username: root
password: root
insert:
url: http://127.0.0.1:8480
username: root
password: root
```
**Note:**
- Set `enabled: true` under `cluster` to enable cluster mode.
- Ensure the URLs match your Docker Compose network or deployment addresses.
#### 3. Restart HertzBeat
Once configured, restart HertzBeat to connect to the VictoriaMetrics cluster.
### FAQ
1. Do both the time series databases need to be configured? Can they both be used?
> You don't need to configure all of them, you can choose one of them. Use the enable parameter to control whether it is used or not. You can also install and configure neither, which can affects the historical chart data.
home/docs/start/virtual-thread.md
+122
View File
@@ -0,0 +1,122 @@
---
id: virtual-thread
title: Virtual Thread Configuration
sidebar_label: Virtual Threads
description: Configure HertzBeat virtual-thread executors, defaults, rollback switches, and tuning guidance.
---
HertzBeat runs on JDK 25 and uses virtual threads for the blocking execution paths that benefit from them. All `hertzbeat.vthreads` keys are optional. If you upgrade HertzBeat but do not merge the new YAML block into your existing `application.yml`, HertzBeat still starts with built-in defaults.
## 1. Where to Configure It
Choose the config file that matches your deployment mode:
- Package deployment: `hertzbeat/config/application.yml`
- Docker single-node deployment: mount your local `application.yml` to `/opt/hertzbeat/config/application.yml`
- Docker Compose deployment: edit `script/docker-compose/*/conf/application.yml`
- Standalone collector deployment: edit `hertzbeat-collector/config/application.yml`
## 2. No Configuration Required
You can leave out the entire `hertzbeat.vthreads` block.
```yaml
# No virtual-thread override is required.
```
HertzBeat will apply runtime defaults automatically.
## 3. Full Optional Configuration Template
Use this only when you want to override the defaults:
```yaml
hertzbeat:
vthreads:
enabled: true
common:
mode: UNBOUNDED_VT
collector:
mode: LIMIT_AND_REJECT
manager:
mode: LIMIT_AND_REJECT
max-concurrent-jobs: 10
alerter:
notify:
mode: LIMIT_AND_REJECT
max-concurrent-jobs: 64
periodic-max-concurrent-jobs: 10
log-worker:
max-concurrent-jobs: 10
queue-capacity: 1000
reduce:
max-concurrent-jobs: 2
window-evaluator:
max-concurrent-jobs: 2
notify-max-concurrent-per-channel: 4
warehouse:
mode: UNBOUNDED_VT
async:
enabled: true
concurrency-limit: 256
reject-when-limit-reached: true
task-termination-timeout: 5000
```
## 4. Built-In Defaults
| Key | Default | Notes |
| --- | --- | --- |
| `hertzbeat.vthreads.enabled` | `true` | Global switch for the HertzBeat virtual-thread executors |
| `hertzbeat.vthreads.common.mode` | `UNBOUNDED_VT` | Common short-running tasks |
| `hertzbeat.vthreads.collector.mode` | `LIMIT_AND_REJECT` | Keeps collector fast-fail admission |
| `hertzbeat.vthreads.collector.max-concurrent-jobs` | `512` | Balanced default for mixed HTTP and JDBC collection workloads on a single node |
| `hertzbeat.vthreads.manager.mode` | `LIMIT_AND_REJECT` | Keeps manager admission behavior |
| `hertzbeat.vthreads.manager.max-concurrent-jobs` | `10` | Same as the legacy limit |
| `hertzbeat.vthreads.alerter.notify.mode` | `LIMIT_AND_REJECT` | Notification executor admission |
| `hertzbeat.vthreads.alerter.notify.max-concurrent-jobs` | `64` | Global notify concurrency |
| `hertzbeat.vthreads.alerter.notify-max-concurrent-per-channel` | `4` | Per notification channel/type |
| `hertzbeat.vthreads.alerter.periodic-max-concurrent-jobs` | `10` | Global periodic alert concurrency |
| `hertzbeat.vthreads.alerter.log-worker.max-concurrent-jobs` | `10` | Log alert short-task concurrency |
| `hertzbeat.vthreads.alerter.log-worker.queue-capacity` | `1000` | Bounded queue to preserve backlog semantics |
| `hertzbeat.vthreads.alerter.reduce.max-concurrent-jobs` | `2` | Alarm reduce concurrency |
| `hertzbeat.vthreads.alerter.reduce.queue-capacity` | unbounded | Leave unset to keep the legacy unbounded queue behavior |
| `hertzbeat.vthreads.alerter.window-evaluator.max-concurrent-jobs` | `2` | Window evaluator concurrency |
| `hertzbeat.vthreads.alerter.window-evaluator.queue-capacity` | unbounded | Leave unset to keep the legacy unbounded queue behavior |
| `hertzbeat.vthreads.warehouse.mode` | `UNBOUNDED_VT` | Storage short tasks; downstream pools still limit real resources |
| `hertzbeat.vthreads.async.enabled` | `true` | Dedicated `@Async` executor switch |
| `hertzbeat.vthreads.async.concurrency-limit` | `256` | `@Async` concurrency guard |
| `hertzbeat.vthreads.async.reject-when-limit-reached` | `true` | Reject extra `@Async` tasks at the limit |
| `hertzbeat.vthreads.async.task-termination-timeout` | `5000` | Milliseconds |
## 5. Tuning Guidance
- Start with the defaults unless you already know a downstream dependency is weak.
- The collector default is intentionally higher than the legacy CPU-based pool size so a single HertzBeat node can carry more blocking collection work before you need extra collectors.
- `512` is the default because it is a good mixed-workload starting point. In local verification, HTTP-heavy collection continued scaling beyond `512`, while JDBC-style collection peaked around `512` and dropped when concurrency was pushed higher.
- Virtual threads remove platform-thread pressure, but they do not remove database limits, HTTP connection limits, network bandwidth limits, file descriptor limits, or downstream rate limits. Raising concurrency too far just moves the bottleneck.
- If most of your workload is HTTP collection across many different targets, try `768` first and then `1024` if timeouts, error rates, and connection usage remain stable.
- If most of your workload is JDBC or other database-backed collection, keep `collector.max-concurrent-jobs` around `256` to `512`. In this type of workload, raising concurrency above `512` can reduce total throughput instead of improving it.
- If you are not sure about the workload mix, keep `512` as the starting point. It is a safer default than `768+` for mixed environments.
- Lower `collector.max-concurrent-jobs` when the collector talks to a small database, a low-capacity HTTP endpoint, or fragile network devices.
- Raise `alerter.notify.max-concurrent-jobs` or `notify-max-concurrent-per-channel` only if your notification providers and HTTP connection pools can absorb the increase.
- Keep `warehouse.mode` unbounded unless you have a clear bottleneck model. Database and TSDB client pools should remain the main limiters.
- `reduce.queue-capacity` and `window-evaluator.queue-capacity` are intentionally left unset by default so existing queueing semantics remain compatible.
- Change concurrency in steps and observe timeout rate, downstream `429` or `5xx`, database pool wait time, and memory or file descriptor usage before raising it again.
## 6. Rollback
Disable HertzBeat virtual-thread executors with:
```yaml
hertzbeat:
vthreads:
enabled: false
```
This rolls the affected executors back to their legacy platform-thread implementations.
## 7. Notes
- If your current deployment is stable, you can keep your existing `application.yml` unchanged.
- Add the `hertzbeat.vthreads` block only when you want to tune concurrency limits or explicitly disable the feature.