/// DECLARE path=/help/monitors/shell
/// DECLARE title=Shell Monitor
/// DECLARE section=help
/// DECLARE subsection=monitors

# Shell Monitor

This monitoring module periodically executes a specified shell command, and records the output.
It can be used to monitor any information that can be retrieved via a shell command. Shell commands
are run from the Scalyr Agent, and execute as the same user as the agent.

@class=bg-warning docInfoPanel: A *monitoring module* is a component of the Scalyr Agent. To use a module,
simply add it to the ``monitors`` section of the Scalyr Agent configuration file (``/etc/scalyr/agent.json``).
For more information, see !!!.


## Sample Configuration

Here is a simple configuration fragment showing use of the shell_monitor module. This sample will record
the version of the Linux kernel in use on the machine where the agent is running.

    monitors: [
      {
        module:  "scalyr_agent.builtin_monitors.shell_monitor",
        id:      "kernel-version",
        command: "uname -r"
      }
    ]


## Configuration Reference

|||# Option                   ||| Usage
|||# ``module``               ||| Always ``scalyr_agent.builtin_monitors.shell_monitor``
|||# ``id``                   ||| Included in each log message generated by this monitor, as a field named ``instance``. \
                                  Allows you to distinguish between values recorded by different monitors.
|||# ``command``              ||| The shell command to execute.
|||# ``extract``              ||| Optional: a regular expression to apply to the command output. If defined, this \
                                  expression must contain a matching group (i.e. a subexpression enclosed in parentheses). \
                                  The monitor will record only the content of that matching group. This allows you to discard \
                                  unnecessary portions of the command output and extract the information you need.
|||# ``log_all_lines``        ||| Optional (defaults to false). If true, the monitor will record the entire command output; \
                                  otherwise, it only records the first line.
|||# ``max_characters``       ||| Optional (defaults to 200). At most this many characters of output are recorded. \
                                  You may specify a value up to 10000, but the Scalyr server currently truncates all \
                                  fields to 3500 characters.


## Log Reference

Each event recorded by this module will have the following fields:

|||# Field                    ||| Meaning
|||# ``monitor``              ||| Always ``shell_monitor``
|||# ``metric``               ||| Always ``output``
|||# ``instance``             ||| The ``id`` value from the module configuration, e.g. ``kernel-version``
|||# ``command``              ||| The shell command for this module instance, e.g. ``uname -r``
|||# ``value``                ||| The output of the shell command, e.g. ``3.4.73-64.112.amzn1.x86_64``

Add initial documentation for the shell-command monitor plugin
Add initial documentation for the shell-command monitor plugin
