[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:
Major Hayden
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
|
||||
# further. For a list of options available for each theme, see the
|
||||
# documentation.
|
||||
#
|
||||
# html_theme_options = {}
|
||||
html_theme_options = {
|
||||
"display_toc": False
|
||||
}
|
||||
|
||||
# Add any paths that contain custom themes here, relative to this directory.
|
||||
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::
|
||||
:maxdepth: 2
|
||||
:caption: Contents:
|
||||
|
||||
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
install
|
||||
configure
|
||||
usage
|
||||
develop
|
||||
|
|
|
|||
|
|
@ -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