DataBot User Manual

Internal

os-stats

Overview

A low-overhead O/S level event collector that generates events-compatible events. It is designed to run in background, collect times 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/os-stats/releases

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

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

Add .../os-stats-<version>/bin to PATH.

os-stats 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.

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 os-stats instance on the system, we recommend /etc/os-stats. Otherwise, each user could maintain an individual configuration file in ~/.os-stats (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 os-stats. If no OS_STATS_CONF environment variable is defined, os-stats will attempt to read ~/.os-stats/os-stats.yaml. Regardless of how the configuration file is declared, os-stats 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

os-stats is a low-overhead monitoring program designed to run in the background, indefinitely. Only one os-stats instance per VM is necessary. os-stats reads O/S level metrics in a loop and writes them in a CSV file. If an os-stats process is already running in the background, an attempt to start another os-stats instance will fail. The program reads its configuration from the default location $OS_STATS_CONFIG_DIR/os-stats.conf or, if configured at startup with -c|--configuration=, from the file specified by the configuration option. If no OS_STATS_CONFIG_DIR environment variable is declared and no configuration file is specified at startup with -c|--configuration=, the program will fail to start. More details on the syntax of configuration file are available under the "Configuration" section.

To start an instance that runs in foreground, use --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.

os-stats attempts to use the java installation indicated by the OS_STATS_JAVA_HOME environment variable, is set. If the OS_STATS_JAVA_HOME environment variable is not set, os-stats uses the standard way of locating java (JAVA_HOME, PATH, etc.)

os-stats can also be used as a command line manager of the os-stats process running in the background. The commands that can be used are:

 help - display this content and exits.

 version - display the version and exit.

 status -  display whether a background os-stats 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 os-stats process, if running.

Command line options:

 --foreground, -fg -  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.

 --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/os-stats.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 os-stats 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/Os-stats_Metric_Reference

jboss.home - the path to a locally accessible JBoss instance. If it needs to monitor JBoss CLI

   metrics,  os-stats 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 os-stats  to build the classpath
   fragment, jboss_home must be specified in the configuration file.

In-Line Help

os-stats --help

Configuration

Example

#
# os-stats configuration file
#

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

#
# output configuration
#
output:
  file: /home/vagrant/tmp/os-stats.csv
  append: true

#
# metrics
#
metrics:
  - PhysicalMemoryTotal

Metric Reference

Metric Reference