LogScale Launcher Script

LogScale uses a Launcher Script that can be used to configure and start LogScale when deployed within single node, cluster, and Docker configurations.

The launcher script is the recommended method for starting LogScale and provides methods for setting configuration, performance and monitoring settings.

Starting LogScale with the Launcher

The launcher script can be found in the tarball in the bin directory.

To start LogScale using the launcher script:

  1. Download the tarball from the LogScale Repo. Files are located within version specific directories.

  2. Extract the contents:

    For glibc Linux distributions:

    shell
    $ tar zxf server-linux_x64-1.183.1.tar.gz

    For musl libc Linux distributions:

    shell
    $ tar zxf server-alpine_x64-1.183.1.tar.gz

  3. Change to the extracted directory:

    shell
    $ cd humio

  4. Execute the launcher script, humio-server-start.sh, that is located in the bin directory.

    shell
    $ ./bin/humio-server-start.sh

The script sets some essential Java parameters and performance settings suitable for LogScale automatically, taking account of the CPU and memory configuration of the environment. These can be customized by setting environment variables. See Configuration for more information.

Configuration

The script is configured using environment variables. Setting a variable manually will disable the defaults set by the script.

Note

The defaults set by the launcher script are subject to change as calculation methods are improved. If you want to see the values the script is using, run the script with the option DRY_RUN=true, all settings are then printed to the console, for the machine the script is running on.

The following variables can be used to set the configuration and are set by the script:

  • General options

    • HUMIO_MEMORY_OPTS — Heap space and other memory-related options. If not set, the launcher calculates a reasonable default. The calculation method strives for a heap size of 75% of the host machine's capacity, plus 0.25GB of offheap memory per core.

      This variable can be overwritten directly, or customized with the following variables:

      • HUMIO_HEAP_SIZE_MB — can be customized. It is used to configure the heap size for the JVM, i.e. it is used to set -Xmx and -Xms.

      • HUMIO_NON_HEAP_SIZE_MB is an alternative to the HUMIO_HEAP_SIZE_MB variable. It enables you to specify how much memory you would like LogScale to reserve for uses other than the LogScale heap. The use case for this is running clusters with mixed hardware in Kubernetes, where it can be tedious to specify heap settings for individual nodes.

      • HUMIO_MAX_DIRECT_MEMORY_SIZE_MB — can be customized. It is used to configure the limit on off-heap memory for the JVM, i.e. it is used to set -XX:MaxDirectMemorySize.

        Note

        The memory settings are tunable. When tuning, the goal is to leave enough memory free for the OS, other processes and the page cache, while assigning as much memory to LogScale as possible. The launcher's default settings provide a decent starting point for tuning for most environments.

    • HUMIO_JVM_PERFORMANCE_OPTS — Options related to the Java JIT compiler and other performance tuning. We do not recommend deviating from the defaults for this option.

    • HUMIO_GC_OPTS — Options for configuring the garbage collector.

  • Debugging/monitoring options

    • HUMIO_JMX_OPTS — JMX configuration options, excluding the setting configuring the JMX port

    • JMX_PORT — The port to open for JMX access. Not set by default.

    • HUMIO_OPTS — Any settings that don't fit into the other variables. Blank by default.

    • HUMIO_OPTS_FS — Can be set to override the field separator used when word-splitting $HUMIO_OPTS in the startup script. This is useful when the options contain characters that are in $IFS (Internal Field Separator), such as spaces, which would otherwise cause the options to be split incorrectly.

    • Removed:Debugging-Related Variables v1.187.0

      Variables that control debugging are removed in LogScale version 1.187.0.

      HUMIO_DEBUG — If set, enables JVM debugging with default options. If not set (the default), debugging is disabled. Can be customized using the following variables:

      • JAVA_DEBUG_PORT — The port to open for debugger access

      • DEBUG_SUSPEND_FLAG — y to suspend the JVM on boot until a debugger attaches, n to not suspend.

      • JAVA_DEBUG_OPTS — The flags used for enabling debugging.

    • HUMIO_JVM_LOG_OPTS — Options for configuring JVM logging. Can be customized by with the following variables:

      • JVM_LOG_DIR — The directory to write JVM logs to. Defaults to the logs directory inside the LogScale directory.

    • DRY_RUN — true to skip launching LogScale. The script will instead print the command line it would have used for launching LogScale.

The configuration can be overridden by setting the corresponding environment variable before running the script. For example:

shell
$ export HUMIO_OPTS=...
$ ./bin/humio-server-start.sh

Configuring Available CPU Cores

To configure the number of CPUs available to LogScale, set the CORES to the number of CPU cores to use. When using docker deployments, the launcher script will honour the corresponding CGROUP configuration.