GermainUX-Engine

⚙️ GermainUX Engine

The GermainUX Engine runs monitoring, diagnostic, and automation components close to the systems being monitored. It retrieves its configuration from Germain Enterprise, executes assigned components, and sends the resulting telemetry to GermainUX for analysis, alerting, reporting, and automation.

Each Engine host contains an Engine Manager, which controls one or more Engine instances on that server.

🏗️ Architecture

A single Engine Manager can control multiple Engines on the same host. The first Engine is usually named standalone, but it can be renamed and additional Engines can be created.

✨ Common use cases

Deploy a GermainUX Engine to:

Place Engines close to the monitored systems to minimize latency and avoid unnecessary firewall exposure.

📦 Deployment methods

GermainUX supports several deployment models:

See Engine Deployment for the complete procedures.

📋 Prerequisites

Before deploying an Engine, confirm that:

The reference sizing for an Engine is approximately:

Actual requirements depend on component count, execution frequency, telemetry volume, local buffering, and state-store usage.

📁 Engine directory

The Engine installation directory is referred to as:

ENGINE_HOME

Example locations:

Windows: D:\Germain\engines
Linux:   /opt/germain/engines

It typically contains:

bin/       Startup scripts and service definitions
config/    Bootstrap and local configuration
lib/       Additional libraries and JDBC drivers
logs/      Engine Manager and Engine logs
database/  Local state-store files

🛠️ Initial configuration

For a standalone deployment, configure:

ENGINE_HOME/config/germain-bootstrap.properties

The initial configuration identifies:

When the monitoring-node value is empty, the Engine Manager automatically registers a new node in Germain Enterprise. This is the preferred approach for most deployments.

For production, use a dedicated account with only the permissions required by the Engine. Protect the bootstrap file because it may contain credentials.

🔗 Messaging compatibility

Older Engine packages contain an ActiveMQ connection property and use port 61616. ActiveMQ applies only to GermainUX releases earlier than 2024-01-01.

GermainUX 2024.2 and later uses Kafka or the transport mechanism supplied with the applicable Engine distribution. Follow the network and messaging configuration for the installed GermainUX release rather than copying legacy ActiveMQ settings.

🔑 Authorize the Engine Manager

A newly registered Engine Manager may require authorization before it can retrieve its configuration.

In the GermainUX Workspace:

1. Open Germain > State.

2. Select Nodes.

3. Find the new Engine Manager.

4. Select the lock in the Sessions column.

5. Confirm the authorization.

The Engine Manager retries while waiting for authorization. After approval, it retrieves its configuration and starts its assigned Engines.

A successful startup is indicated in EngineManager.log by a message similar to:

Started EngineManagerApplication in <duration> seconds

🎛️ Manage the Engine Manager

🖥️ Windows

The Engine Manager runs as a Windows service. Use the Windows Services console to start, stop, or restart it.

🐧 Linux

The Engine Manager can run through:

• The supplied startup script

• A System V service

• A systemd service

For production, configure automatic startup and operating-system-managed recovery.

Avoid forcefully terminating the Engine Manager with kill -9. A forced termination prevents it from shutting down its managed Engine processes cleanly.

⚙️ Manage individual Engines

Administrators can control individual Engines from the Workspace:

1. Sign in as an administrator.

2. Open Germain > State.

3. Find the Engine by name.

4. Enable or disable it using the corresponding toggle.

Disabling an Engine does not necessarily stop the Engine Manager or other Engines on the same host.

See Engine Configuration.

🧠 Configure Engine memory

Engine JVM memory can be updated from Germain > State:

1. Find and select the Engine.

2. Update its JVM memory option, such as -Xmx.

3. Save the configuration.

4. Select Restart this Engine.

5. Verify the effective command line or review the Engine logs.

Documented default JVM options include:

-server
-Xms256m
-Xmx1024m
-XX:+CrashOnOutOfMemoryError
-XX:-HeapDumpOnOutOfMemory
-XX:-CreateMinidumpOnCrash

Increase memory only when the host has sufficient free capacity. If the host itself is constrained, moving workload to another Engine is safer than allocating more heap.

See Engine Memory Configuration.

🌐 Configure a proxy

Proxy settings may be required for two separate processes:

🔧 Engine Manager

Add the appropriate JVM properties to VMARGS in:

Windows: bin/startEngineManager.bat
Linux:   bin/startEngineManager.sh

HTTP:

-Dhttp.proxyHost=<proxy-host>
-Dhttp.proxyPort=<proxy-port>

HTTPS:

-Dhttps.proxyHost=<proxy-host>
-Dhttps.proxyPort=<proxy-port>

🤖 Individual Engine

In Germain > State:

1. Select the Engine.

2. Open its advanced settings.

3. Add the required HTTP or HTTPS proxy properties to its JVM options.

4. Save and restart the Engine.

To pass the Engine Manager’s proxy configuration automatically to its Engines, enable Relay Proxy Settings on the node configuration.

See Engine Proxy Configuration.

📈 Capacity management

An Engine may become slow when it or its host runs out of memory or CPU.

If the Engine lacks JVM memory but the host has sufficient capacity, increase its heap through Germain > State.

If the host lacks CPU or memory:

Do not continually increase heap without reviewing host capacity and component workload.

See Engine Capacity Issues.

💾 Local state store

An Engine uses a local database to track processing state. For example, it records which portions of monitored log files have already been parsed.

Cleaning the state store causes the Engine to recreate this local processing state. Depending on the monitoring configuration, this can result in data being reread or reprocessed.

Only clean it when:

• The state store is corrupted.

• GermainUX Support recommends doing so.

• You intentionally need to restart processing from a clean state.

Before cleaning it:

1. Stop all Engines using the state store.

2. Preserve the Engine logs.

3. Back up the state-store directory.

4. Confirm the potential effect on data reprocessing.

5. Follow the documented cleanup procedure.

6. Restart the Engines and validate processing.

See Clean Up an Engine State Store.

❗ Engine does not start

Begin with:

ENGINE_HOME/logs/EngineManager.log

Then verify the following.

📡 Enterprise connectivity

The Engine must be able to reach Germain Enterprise.

Typical HTTP ports include:

80
8080

The actual port depends on the Germain Enterprise, proxy, load-balancer, and TLS configuration.

Legacy ActiveMQ deployments also require access to:

61616

Do not assume port 61616 applies to current Kafka-based deployments. Use the requirements for your GermainUX release.

☕ Java

Verify the active Java version:

java -version

The Engine documentation supports Java 11 or later, but you should use the specific version approved for your GermainUX release.

Confirm JAVA_HOME.

Windows Command Prompt:

echo %JAVA_HOME%

PowerShell:

echo $env:JAVA_HOME

Linux:

echo $JAVA_HOME

If the wrong Java version appears, review the host’s PATH, JAVA_HOME, service definition, and installed Java versions.

See Engine Does Not Start.

🔍 Identify an Engine Windows process

Windows Task Manager may truncate the command line, making it difficult to identify which Engine belongs to a Java process.

Run:

wmic process get Name,ProcessId,CommandLine /format:table > file.txt

Review file.txt for the Engine name and corresponding process ID.

On Windows versions where wmic is unavailable, use an approved PowerShell or process-management equivalent that displays the complete process command line.

See Identify an Engine from a Windows Process.

📄 Logs and validation

The primary Engine Manager log is:

ENGINE_HOME/logs/EngineManager.log

After deployment or configuration changes, confirm that:

⬆️ Upgrades

The Engine Manager automatically restarts after an Engine upgrade.

After upgrading, verify that:

📚 Engine documentation