wehub-resource-sync
83 lines
3.8 KiB
Markdown
83 lines
3.8 KiB
Markdown
---
|
|
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).
|