JVM Settings

// Setup

Tune memory for the Banalytics runtime

Singleton thing that manages JVM startup options for the Banalytics Box process. It stores options in `banalytics.vmoptions`.

Saved JVM options are applied after the agent process is restarted

WARNING: JVM options are startup parameters. A typo, unsupported option, conflicting GC setting, too small memory limit, or an overly aggressive native-memory limit can prevent Banalytics Box from starting. Change these parameters consciously, preferably one group at a time, and keep the previous working configuration available for rollback. If the agent cannot start after a bad change, rollback may require direct access to the device or operating system to edit banalytics.vmoptions manually. Before changing JVM options on a remote installation, prepare an alternative access path such as reverse SSH, direct SSH, remote desktop, TeamViewer, or another out-of-band administration channel.

01

Measure before changing limits

Use System Monitor to check Java heap, system memory, and native memory pressure before increasing limits.

02

Leave RAM for the operating system

Do not allocate all physical RAM to the JVM. The operating system, camera/network buffers, file cache, codecs, AI libraries, and native media code also need memory.

03

Restart to apply changes

Saved JVM options are not applied live. They take effect only after the agent process is restarted.

// Reference

Configuration parameters

Parameter	Required	Description	Default
Initial Heap Size	Optional	Memory option. Initial Java heap reserved for Banalytics. Value format: e.g. 300m, 512m, 1g. JVM option: `-Xms`.	Not set
Maximum Heap Size	Optional	Memory option. Maximum Java heap available to Banalytics. Value format: e.g. 1g, 2g, 4g. JVM option: `-Xmx`.	Not set
Thread Stack Size	Optional	Memory option. Stack size reserved for each Java thread. Value format: e.g. 512k, 1m. JVM option: `-Xss`.	Not set
Initial Metaspace Size	Optional	Memory option. Initial metaspace size for loaded class metadata. Value format: e.g. 64m. JVM option: `-XX:MetaspaceSize`.	Not set
Max Metaspace Size	Optional	Memory option. Maximum metaspace size for loaded class metadata. Value format: e.g. 256m, 512m. JVM option: `-XX:MaxMetaspaceSize`.	Not set
Max Direct Memory Size	Optional	Memory option. Maximum direct/native buffer memory available outside the Java heap. Value format: e.g. 512m, 1g. JVM option: `-XX:MaxDirectMemorySize`.	Not set
Initial Young Gen Size	Optional	Memory option. Initial young generation size. Value format: e.g. 256m. JVM option: `-XX:NewSize`.	Not set
Max Young Gen Size	Optional	Memory option. Maximum young generation size. Value format: e.g. 512m. JVM option: `-XX:MaxNewSize`.	Not set
Use G1 GC	Optional	GC Selection option. Enables the G1 garbage collector. Enter + to enable it. JVM option: `-XX:+UseG1GC`.	Not set
Use ZGC (generational, JVM 21)	Optional	GC Selection option. Enables ZGC on JVM versions that support it. Enter + to enable it. JVM option: `-XX:+UseZGC`.	Not set
Use Serial GC	Optional	GC Selection option. Enables Serial GC. Enter + to enable it. JVM option: `-XX:+UseSerialGC`.	Not set
Use Parallel GC	Optional	GC Selection option. Enables Parallel GC. Enter + to enable it. JVM option: `-XX:+UseParallelGC`.	Not set
Max GC Pause Target	Optional	GC Tuning option. Target maximum pause time. Value format: ms, e.g. 200. JVM option: `-XX:MaxGCPauseMillis`.	Not set
GC Time Ratio	Optional	GC Tuning option. Ratio between application time and garbage collection time. Value format: e.g. 12. JVM option: `-XX:GCTimeRatio`.	Not set
G1 Region Size	Optional	GC Tuning option. Region size used by G1. Value format: e.g. 4m, 8m, 16m. JVM option: `-XX:G1HeapRegionSize`.	Not set
Parallel GC Threads	Optional	GC Tuning option. Number of parallel GC worker threads. Value format: number. JVM option: `-XX:ParallelGCThreads`.	Not set
Concurrent GC Threads	Optional	GC Tuning option. Number of concurrent GC worker threads. Value format: number. JVM option: `-XX:ConcGCThreads`.	Not set
Reserved Code Cache Size	Optional	JIT Compilation option. Reserved code cache for compiled methods. Value format: e.g. 256m. JVM option: `-XX:ReservedCodeCacheSize`.	Not set
Tiered Compilation	Optional	JIT Compilation option. Enables tiered compilation. Enter + to enable it. JVM option: `-XX:+TieredCompilation`.	Not set
JIT Compile Threshold	Optional	JIT Compilation option. Invocation threshold before compilation. Value format: e.g. 10000. JVM option: `-XX:CompileThreshold`.	Not set
Heap Dump on OutOfMemoryError	Optional	Diagnostics option. Creates a heap dump when the JVM throws OutOfMemoryError. Enter + to enable it. JVM option: `-XX:+HeapDumpOnOutOfMemoryError`.	Not set
Heap Dump Path	Optional	Diagnostics option. File or directory path for heap dumps. Value format: file path. JVM option: `-XX:HeapDumpPath`.	Not set
Native Memory Tracking	Optional	Diagnostics option. Native memory tracking mode. Value format: off / summary / detail. JVM option: `-XX:NativeMemoryTracking`.	Not set
Unlock Diagnostic VM Options	Optional	Diagnostics option. Unlocks additional diagnostic VM options. Enter + to enable it. JVM option: `-XX:+UnlockDiagnosticVMOptions`.	Not set
String Deduplication (G1 / ZGC)	Optional	Optimization option. Enables string deduplication for supported collectors. Enter + to enable it. JVM option: `-XX:+UseStringDeduplication`.	Not set
Disable System.gc()	Optional	Optimization option. Disables explicit System.gc() calls. Enter + to enable it. JVM option: `-XX:+DisableExplicitGC`.	Not set
File Encoding	Optional	System Properties option. Default file encoding used by the JVM. Value format: e.g. UTF-8. JVM option: `-Dfile.encoding`.	Not set
User Timezone	Optional	System Properties option. Default JVM timezone. Value format: e.g. UTC, Europe/Berlin. JVM option: `-Duser.timezone`.	Not set
JavaCPP Max Bytes	Optional	JavaCPP option. Cleanup threshold for JavaCPP-managed native memory. Value format: e.g. 1g, 2g. JVM option: `-Dorg.bytedeco.javacpp.maxbytes`.	Not set
JavaCPP Max Physical Bytes	Optional	JavaCPP option. Maximum physical/native memory budget for JavaCPP-managed allocations. Value format: e.g. 2g, 4g. JVM option: `-Dorg.bytedeco.javacpp.maxphysicalbytes`.	Not set

// How it works

Heap and native memory are separate resource pools

JVM Settings is a singleton runtime component. It stores startup options in banalytics.vmoptions and exposes them to the UI and business interface. There are no regular form fields beyond the generated options view: the saved values become launcher options for the next process start.

Java heap memory is controlled by options such as -Xms and -Xmx. Native memory is used outside the Java heap by JavaCPP, codecs, frame buffers, and some AI libraries. For media-heavy installations, increasing only -Xmx may not solve native memory pressure.

HEAP

Java heap

Stores ordinary Java objects. Increase maximum heap when the agent needs more room for application state, events, task data, and Java-side processing.

NAT

Native memory

Used by codecs, JavaCPP, frame buffers, model runtimes, and direct buffers. Native failures can happen even when heap usage looks healthy.

OPS

Restart boundary

Changes are startup options. Save them carefully and restart the agent to apply the new runtime limits.

// Use cases

Choose JVM options for the workload you actually run

01

Small installation or default profile

Keep the default heap close to -Xms300m and -Xmx512m when the agent runs only lightweight tasks. This leaves RAM for the operating system, camera/network buffers, file cache, and native libraries.

02

Several cameras, recording buffers, or AI/media processing

Increase -Xmx gradually, for example to 1g, 2g, or 4g, depending on installed RAM and observed usage. Use System Monitor to verify heap headroom during peak load.

03

Stable workload with predictable memory use

Set -Xms closer to the normal working heap, for example 50-75% of -Xmx, to reduce heap expansion during busy periods. On low-RAM devices keep -Xms modest.

04

Native/video processing

JavaCPP, codecs, frame buffers, and some AI libraries can use native memory outside the Java heap. If media tasks fail while heap usage is not close to -Xmx, tune -XX:MaxDirectMemorySize, -Dorg.bytedeco.javacpp.maxbytes, and -Dorg.bytedeco.javacpp.maxphysicalbytes.

05

Out-of-memory investigation

Enable -XX:+HeapDumpOnOutOfMemoryError and set -XX:HeapDumpPath to a disk location with enough free space. Heap dumps can be large and may contain sensitive data, so this is usually a troubleshooting setting.

06

Native memory diagnostics

Use -XX:NativeMemoryTracking=summary when investigating native memory growth. Use detailed tracking only for short diagnostic windows because it adds overhead; turn it off after the incident.

07

GC tuning

The default JVM collector or -XX:+UseG1GC is suitable for most deployments. Change ZGC, Parallel GC, Serial GC, pause targets, or GC thread counts only after observing pauses or throughput issues.

08

Constrained hardware

Avoid large -Xss values because every thread reserves stack memory. Prefer smaller heap and native limits, lower FPS or buffer settings in media tasks, and fewer concurrent heavy tasks before increasing JVM limits.

09

Stable timestamps and text processing

Set -Duser.timezone when schedules, event timestamps, or logs must use a fixed timezone independent of the operating system. Keep -Dfile.encoding=UTF-8 unless an integration explicitly requires another encoding.

// Operations

Operational notes

01

Changes are not live

The launcher reads banalytics.vmoptions during startup, so saved changes are not applied to the running process.

02

Heap does not replace native memory

Heap memory and native memory are separate resource pools. For media-heavy installations, increasing only -Xmx may not solve native memory pressure.

03

Keep rollback access

Before changing startup options remotely, keep an alternative administration path ready. A bad option can prevent the service from starting and may require manual file editing on the operating system.

// Next steps