Run as a Service

In production, it is recommended to run the Intelligence Hub as a service, so that it starts automatically during system boot-up and continues running when no user is signed in.

Windows

Install the Service

To install the Intelligence Hub as a service, run the runtime\service\install-windows-service.bat script. Note, this feature requires Java to be in the system PATH environment variable. If you are unsure if this was set when you installed Java check out this link: https://www.java.com/en/download/help/path.html .

Once installed, the service can be found in Windows Services Manager under the name HighByte Intelligence Hub Runtime.

Uninstall the Service

Executing the file runtime\service\uninstall-windows-service.bat will stop and uninstall the service.

Service Configuration

The Windows service is configured by runtime\service\service-installer-windows.xml. The installer reads this file when the service is created, and the service re-reads it every time it starts.

Element	Description
`id`	The service name used internally by Windows. It must be unique across the system.
`name`	The display name shown in the Windows Services Manager.
`description`	The description shown in the Windows Services Manager.
`logmode`	Controls how the service log files are rotated. See Log Rotation Modes .
`logpath`	The directory that holds the service log files, relative to `runtime\service`.
`startmode`	When Windows starts the service. `Automatic` starts it during boot-up.
`executable`	The script the service runs, which calls the standard `start-windows.bat` and `stop-windows.bat` scripts.
`startarguments`	The arguments passed to the executable when the service starts.
`stoparguments`	The arguments passed to the executable when the service stops.

Most changes to this file take effect the next time the HighByte Intelligence Hub Runtime service is restarted. The exceptions are id, name, description, and startmode. Windows records those four when the service is created and never reads them again, so changing one has no effect until the service is uninstalled and installed again.

Service Log Files

When running as a Windows service, the runtime console output is instead written to two files in runtime\service\logs:

File	Contents
`service-installer-windows.out.log`	Everything the runtime wrote to standard output.
`service-installer-windows.err.log`	Everything the runtime wrote to standard error.

These files are useful when the service fails to start, because a startup failure often occurs before the Intelligence Hub is able to log anything itself.

These files are separate from the Intelligence Hub event log. The event log is written to intelligencehub-events.log in the application data directory and is sized using the File Size setting described in Logging . That setting has no effect on the service log files, which are sized only by the elements described below. See Event Log for details on the event log itself.

Each file is rotated independently. When a file is rotated, the current file is renamed to service-installer-windows.0.out.log, any existing archive is shifted up by one, and the oldest archive is deleted.

Log Rotation Modes

The logmode element determines whether the service log files are bounded. Because the Intelligence Hub typically runs for months without a restart, a mode that only rotates at startup will allow a log file to grow indefinitely. A pipeline that repeatedly logs the same error can produce a very large file this way.

The mode can be written in either of two equivalent forms. The shipped configuration uses a logmode element that holds the mode name as its text, such as <logmode>roll-by-size</logmode>. The alternative is a log element that carries the mode name in a mode attribute instead, such as <log mode="roll-by-size">. The log form is required when changing the size limits described in Changing the Log Size Limit , because that form is the only one that accepts nested elements.

Mode	Behavior	Bounds the active file for a long-running service?
`roll-by-size`	Checks the file size as each line is written and rotates during operation.	Yes
`roll-by-time`	Rotates on a time pattern, such as daily. Requires a `pattern` element.	Yes
`roll-by-size-time`	Rotates on size or on a time pattern, whichever comes first. Requires a `pattern` element.	Yes
`roll`	Renames the file when the service starts, then appends to a new file.	No
`reset`	Truncates the file when the service starts, then appends to it.	No
`append`	Appends to the file indefinitely and never rotates.	No
`none`	Discards the output. No file is written.	Yes

Bounding the active file is not the same as bounding total disk usage. Of the rotating modes, only roll-by-size also limits how many archives are kept, as described in Changing the Log Size Limit .

The Intelligence Hub is configured to use roll-by-size so that the service log files stay bounded without requiring a restart. Using the default limits, each file is rotated at 10 MB and eight archives are retained, which is nine files in total, or roughly 90 MB. Because standard output and standard error are rotated independently, the two sets of files together can occupy roughly 180 MB.

Changing the Log Size Limit

The rotation limits are set by two elements:

Element	Description
`sizeThreshold`	The size in kilobytes a file may reach before it is rotated. Defaults to `10240`, which is 10 MB.
`keepFiles`	The number of archives to retain, in addition to the file currently being written. Defaults to `8`. Applies to `roll-by-size` only.

Both elements must be nested inside a log element, so setting them requires switching from the logmode form to the log form. Remove the logmode line and add the following in its place, noting that the mode name moves into a mode attribute. The example below rotates each file at 5 MB and keeps two archives, limiting each set of files to roughly 15 MB.

<log mode="roll-by-size">
  <sizeThreshold>5120</sizeThreshold>
  <keepFiles>2</keepFiles>
</log>

Both the logmode and log forms of the element are supported, but logmode takes precedence. If the logmode line is left in the file, the sizeThreshold and keepFiles values are ignored and the defaults are used instead. Be sure to remove it.

Both values must be given as plain numbers. Unlike logpath, they do not accept environment variables, and a value that is not a number will prevent the service from starting.

If the mode is changed to roll-by-time or roll-by-size-time, keepFiles no longer has any effect, and neither mode prunes archives on its own:

roll-by-time retains every archive it creates, and offers no element that removes or compresses them. The number of archives grows for as long as the service runs.
roll-by-size-time accepts a zipOlderThanNumDays element, which compresses archives older than the given number of days and deletes the originals. It takes effect only when an autoRollAtTime element is also present, because the compression runs on that daily schedule. The resulting zip files are grouped by zipDateFormat, which defaults to one file per month, and are never removed.

Restart the HighByte Intelligence Hub Runtime service to apply the change.

Upgrades

The configuration file is part of the runtime directory, so the upgrade process replaces it with a fresh copy. Note any changes you make so they can be applied again to the new installation.

Linux

Copy the runtime, configuration, and appData directories from HighByte-Intelligence-Hub-x.x to the desired installation directory, using sudo if the location requires super user permission. This example will use /opt/highbyte.

Once complete, the directory listing should look like:

$ ls /opt/highbyte/
configuration  runtime appData

Make sure the start and stop scripts have execute permissions: sudo chmod +x /opt/highbyte/runtime/*-linux.sh

Using sudo, create /etc/systemd/system/highbyte.service. This minimal example service file will automatically start the Intelligence Hub during system boot-up.

To install the service run: sudo systemctl enable highbyte.service

To start the service run: sudo systemctl start highbyte.service

To verify the service started successfully run: sudo systemctl status highbyte.service

Console Output

A systemd service directs the console output of the runtime according to the StandardOutput and StandardError settings in the service file. When these settings are left at their defaults, the output is sent to the journal and is viewed by running journalctl -u highbyte.service. The journal applies its own size limits, which are configured in /etc/systemd/journald.conf rather than by the Intelligence Hub.

If the service file redirects this output to a file instead, that file will grow without limit unless an external log rotation tool such as logrotate is configured to bound it.