Virtual Thread Configuration

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.

# 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:

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

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:

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.