DataBot User Manual

Internal

DataBot

Overview

DataBot is a low-overhead O/S level event collector that generates events-compatible events. os-sats is designed to run as a system daemon, indefinitely. Only one DataBot instance per VM is necessary. DataBot will collect timed events and channel them to various destinations, such as files, network, etc. It is capable of collecting memory, CPU, etc. usage statistics, as well as WildFly management domain model and JMX metrics.

Installation

Download the stable release from

https://github.com/NovaOrdis/databot/releases

The release consists in a ZIP file with a name matching "databot-<version>.zip".

Unzip the release file in a conventional binary directory, such as /opt or /usr/local. An "databot-<version>" sub-directory will be created.

Add .../databot-<version>/bin to PATH.

DataBot needs a Java VM to run. It will attempt to use, in this order:

1. Value of "OS_STATS_JAVA_HOME" environment variable, if set.
2. Value of "JAVA_HOME" environment variable, if set.
3. The "java" executable found in path.

Configuration File

Choose a directory to store the configuration file. If the configuration will be shared by multiple users and there will be used by just one DataBot instance on the system, we recommend /etc/databot. Otherwise, each user could maintain an individual configuration file in ~/.databot (recommended) or a directory of their choosing. The location of the configuration file should be exposed as the value of the OS_STATS_CONF environment variable in the environment of the user who will execute DataBot. If no OS_STATS_CONF environment variable is defined, DataBot will attempt to read ~/.databot/databot.yaml.

The configuration file location can be overridden from command line using -c|--configuration= options. If one of these options is specified, the environment variables and default locations are ignored.

Regardless of how the configuration file is declared, DataBot will fail if the file is not found. For details on the configuration file syntax see Configuration section below.

Complete any of target-specific configuration procedures, if they apply.

Usage

If a DataBot process is already running in the background, an attempt to start another DataBot instance will fail.

To start an instance that runs in foreground, use -f|--foreground command line option. In foreground mode, the output is switched automatically from the configured file destination to /dev/stdout and the output.file configuration, as described below, is ignored.

Commands

help

Display in-line help.

version

Display version information.

status

Display whether a background DataBot process already runs on the system. If a process is found running, the command provides more information about it (such as the PID).

stop

Stop the background DataBot process, if running.

Options

-fg|--foreground

Run the command in foreground and automatically switch the output from the configured file destination to /dev/stdout.

-v|--verbose

Turns on DEBUG logging at stdout.

-d|--debug

Start the JVM in debug mode, so it can be accessed by a debugger. It also turns on DEBUG logging.

Configuration

sampling.interval - the sampling interval, in seconds. If not specified, the default is 10 seconds.

output.file - the name of the output file. If not specified, the default value is /tmp/databot.csv. Note that if --foreground (or -fg) option is used, the output will forcibly send to /dev/stdout, regardless of the value of 'output.file' configuration parameter.

output.file.append - true/false. Indicates whether to append to an already existing output file or to overwrite the existing file. The default value is "true" (append); this configuration will allow accumulation of historical data. Every time DataBot is restarted in "append" mode, a new header line will be inserted in the file.

metrics - comma-separated list of the definitions for the metrics to be collected from the system.

Example:

   metrics=PhysicalMemoryUsed,CpuUserTime,jboss:/subsystem=web/connector=http/bytesReceived

For a complete list of supported metrics, syntax details and extensive documentation, see https://kb.novaordis.com/index.php/DataBot_Metric_Reference

jboss.home - the path to a locally accessible JBoss instance. If it needs to monitor JBoss CLI metrics, DataBot must be configured to detect and use the libraries from a JBoss instance it has access to (it does not ship with the required JARs, as those may be different depending on the version of the target JBoss instance. In order to enable DataBot to build the classpath fragment, jboss_home must be specified in the configuration file.

Example

https://github.com/NovaOrdis/databot/blob/master/main/src/test/resources/data/configuration/reference.yaml

In-Line Help

databot --help

Configuration

Example

#
# DataBot configuration file
#

#
# sampling interval (in seconds)
#
sampling.interval: 20

#
# output configuration
#
output:
  file: /home/vagrant/tmp/databot.csv
  append: true

#
# metrics
#
metrics:
  - PhysicalMemoryTotal

Metric Reference

Metric Reference