[Docs] Initial docs for monitorstack
This patch adds some initial docs for monitorstack. This is by no means an exhaustive set of documentation, but it's a good place to start. Change-Id: Ia028bd51f145093c42eec91314a0a0e124170be0
This commit is contained in:
parent
b616091eb9
commit
57d1fb9651
|
@ -128,8 +128,9 @@ html_theme = 'openstackdocs'
|
||||||
# Theme options are theme-specific and customize the look and feel of a theme
|
# Theme options are theme-specific and customize the look and feel of a theme
|
||||||
# further. For a list of options available for each theme, see the
|
# further. For a list of options available for each theme, see the
|
||||||
# documentation.
|
# documentation.
|
||||||
#
|
html_theme_options = {
|
||||||
# html_theme_options = {}
|
"display_toc": False
|
||||||
|
}
|
||||||
|
|
||||||
# Add any paths that contain custom themes here, relative to this directory.
|
# Add any paths that contain custom themes here, relative to this directory.
|
||||||
html_theme_path = [openstackdocstheme.get_html_theme_path()]
|
html_theme_path = [openstackdocstheme.get_html_theme_path()]
|
||||||
|
|
|
@ -0,0 +1,9 @@
|
||||||
|
Configuration
|
||||||
|
=============
|
||||||
|
|
||||||
|
The OpenStack monitoring plugins within monitorstack require basic
|
||||||
|
configuration that provides URLs for endpoints and credentials for those
|
||||||
|
endpoints. The following example provides configuration details for various
|
||||||
|
OpenStack services:
|
||||||
|
|
||||||
|
.. literalinclude:: ../../tests/files/test-openstack.ini
|
|
@ -0,0 +1,41 @@
|
||||||
|
===============
|
||||||
|
Developer guide
|
||||||
|
===============
|
||||||
|
|
||||||
|
One of the design goals of monitorstack is to make it easy to develop new
|
||||||
|
monitoring plugins.
|
||||||
|
|
||||||
|
Writing plugins
|
||||||
|
---------------
|
||||||
|
|
||||||
|
Start by adding a new python script in the ``plugins`` directory. The plugin
|
||||||
|
will inherit the same name as the file. For example, creating a plugin file
|
||||||
|
called ``my_plugin.py`` will create a new plugin called ``my_plugin``.
|
||||||
|
|
||||||
|
Use the ``uptime`` plugin as a guide for developing new plugins:
|
||||||
|
|
||||||
|
.. literalinclude:: ../../monitorstack/plugins/uptime.py
|
||||||
|
|
||||||
|
Every plugin will have a ``cli()`` method that is the equivalent of
|
||||||
|
``___main___`` in other Python scripts.
|
||||||
|
|
||||||
|
Testing plugins
|
||||||
|
---------------
|
||||||
|
|
||||||
|
Add tests in the ``tests`` directory and follow the ``uptime`` example. Here
|
||||||
|
are the contents of ``tests/test_plugin_uptime.py`` as an example:
|
||||||
|
|
||||||
|
.. literalinclude:: ../../tests/test_plugin_uptime.py
|
||||||
|
|
||||||
|
Running tests
|
||||||
|
-------------
|
||||||
|
|
||||||
|
There are two main sets of tests: pep8/flake8 tests and unit tests:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
# PEP8 and flake8 checks
|
||||||
|
tox -e linters
|
||||||
|
|
||||||
|
# Unit tests
|
||||||
|
tox -e functional
|
|
@ -1,15 +1,19 @@
|
||||||
Welcome to monitorstack's documentation!
|
==============================
|
||||||
========================================
|
Documentation for monitorstack
|
||||||
|
==============================
|
||||||
|
|
||||||
|
The monitorstack project provides a framework for writing monitoring plugins
|
||||||
|
that output data in various formats for different monitoring systems.
|
||||||
|
Developers can quickly add new monitoring plugins (along with tests) without
|
||||||
|
worrying about how to format the data.
|
||||||
|
|
||||||
|
Documentation sections
|
||||||
|
----------------------
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
:caption: Contents:
|
|
||||||
|
|
||||||
|
install
|
||||||
|
configure
|
||||||
Indices and tables
|
usage
|
||||||
==================
|
develop
|
||||||
|
|
||||||
* :ref:`genindex`
|
|
||||||
* :ref:`modindex`
|
|
||||||
* :ref:`search`
|
|
||||||
|
|
|
@ -0,0 +1,19 @@
|
||||||
|
Installation
|
||||||
|
============
|
||||||
|
|
||||||
|
The project is conveniently packaged as a Python package that is installed with
|
||||||
|
``pip``.
|
||||||
|
|
||||||
|
Installing from pypi with ``pip``
|
||||||
|
---------------------------------
|
||||||
|
|
||||||
|
*The pypi-based installation is coming soon.*
|
||||||
|
|
||||||
|
Installing from git
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
Install monitorstack with ``pip``:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
pip install git+https://github.com/openstack/monitorstack
|
|
@ -0,0 +1,128 @@
|
||||||
|
Usage
|
||||||
|
=====
|
||||||
|
|
||||||
|
Run the ``monitorstack`` command without any arguments to review a list of
|
||||||
|
available commands and options:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ monitorstack
|
||||||
|
Usage: monitorstack [OPTIONS] COMMAND [ARGS]...
|
||||||
|
|
||||||
|
A complex command line interface.
|
||||||
|
|
||||||
|
Options:
|
||||||
|
-f, --format [json|line|telegraf|rax-maas]
|
||||||
|
Output format (valid options: json, line,
|
||||||
|
telegraf, rax-maas
|
||||||
|
-v, --verbose Enables verbose mode.
|
||||||
|
--help Show this message and exit.
|
||||||
|
|
||||||
|
Commands:
|
||||||
|
kvm Get metrics from a KVM hypervisor.
|
||||||
|
os_block_pools_totals Get block storage totals from the available pools.
|
||||||
|
os_block_pools_usage Get block storage usage from the available pools.
|
||||||
|
os_vm_quota_cores Get nova cores quotas.
|
||||||
|
os_vm_quota_instance Get nova instance quotas.
|
||||||
|
os_vm_quota_ram Get nova ram quotas.
|
||||||
|
os_vm_used_cores Get nova used cores.
|
||||||
|
os_vm_used_disk Get nova used disk.
|
||||||
|
os_vm_used_instance Get nova used instances.
|
||||||
|
os_vm_used_ram Get nova used ram.
|
||||||
|
process Check if a process is running.
|
||||||
|
uptime Get system uptime.
|
||||||
|
|
||||||
|
Executing simple plugins
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
The most simple plugins do not require any arguments. For example, to get the
|
||||||
|
system uptime, use the ``uptime`` command to run the corresponding ``uptime``
|
||||||
|
plugin:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ monitorstack uptime
|
||||||
|
{
|
||||||
|
"variables": {
|
||||||
|
"uptime": "22613.26"
|
||||||
|
},
|
||||||
|
"message": "uptime is ok",
|
||||||
|
"meta": {
|
||||||
|
"platform": "Linux-4.10.5-200.fc25.x86_64-x86_64-with-fedora-25-Twenty_Five"
|
||||||
|
},
|
||||||
|
"exit_code": 0,
|
||||||
|
"measurement_name": "system_uptime"
|
||||||
|
}
|
||||||
|
|
||||||
|
The default output type is json, but this is configured with the ``-f,
|
||||||
|
--format`` option. Here is another example that outputs data in telegraf
|
||||||
|
format:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ monitorstack -f telegraf uptime
|
||||||
|
system_uptime platform=Linux-4.10.5-200.fc25.x86_64-x86_64-with-fedora-25-Twenty_Five uptime=23005.05 1490819061833774080
|
||||||
|
|
||||||
|
Executing plugins with arguments
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
|
The ``process`` plugin searches the current list of running processes to find
|
||||||
|
any that match a string provided as an argument. Execute the plugin without any
|
||||||
|
arguments for some usage help:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ monitorstack process
|
||||||
|
Usage: monitorstack process [OPTIONS] PROCESS_NAME
|
||||||
|
|
||||||
|
Error: Missing argument "process_name".
|
||||||
|
|
||||||
|
In this example, we want to ensure that the ``chronyd`` process is running:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ monitorstack process chronyd
|
||||||
|
{
|
||||||
|
"variables": {
|
||||||
|
"chronyd": 1
|
||||||
|
},
|
||||||
|
"message": "process check is ok",
|
||||||
|
"meta": {
|
||||||
|
"platform": "Linux-4.10.5-200.fc25.x86_64-x86_64-with-fedora-25-Twenty_Five"
|
||||||
|
},
|
||||||
|
"exit_code": 0,
|
||||||
|
"measurement_name": "process"
|
||||||
|
}
|
||||||
|
|
||||||
|
We can also see a negative result if we check for a non-existent process called
|
||||||
|
``processdoesntexist``:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ monitorstack process processdoesntexist
|
||||||
|
{
|
||||||
|
"variables": {
|
||||||
|
"processdoesntexist": 0
|
||||||
|
},
|
||||||
|
"message": "process failed -- Process processdoesntexist not found",
|
||||||
|
"meta": {
|
||||||
|
"platform": "Linux-4.10.5-200.fc25.x86_64-x86_64-with-fedora-25-Twenty_Five"
|
||||||
|
},
|
||||||
|
"exit_code": 1,
|
||||||
|
"measurement_name": "process"
|
||||||
|
}
|
||||||
|
|
||||||
|
Executing plugins with configuration files
|
||||||
|
------------------------------------------
|
||||||
|
|
||||||
|
Many of the OpenStack plugins require a configuration file that specifies the
|
||||||
|
URLs of OpenStack endpoints as well as valid credentials for those endpoints.
|
||||||
|
For more information on the format of these configuration files, refer to the
|
||||||
|
documentation on `configuration <configure.html>`_.
|
||||||
|
|
||||||
|
Here is an example with the ``os_vm_quota_ram`` plugin with a configuration
|
||||||
|
file in ``/home/user/openstack.ini``:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ monitorstack os_vm_quota_ram --config-file=/etc/openstack/openstack.ini
|
Loading…
Reference in New Issue