Browse Source

[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
Major Hayden 2 years ago
parent
commit
57d1fb9651
No account linked to committer's email address
6 changed files with 215 additions and 13 deletions
  1. 3
    2
      doc/source/conf.py
  2. 9
    0
      doc/source/configure.rst
  3. 41
    0
      doc/source/develop.rst
  4. 15
    11
      doc/source/index.rst
  5. 19
    0
      doc/source/install.rst
  6. 128
    0
      doc/source/usage.rst

+ 3
- 2
doc/source/conf.py View File

@@ -128,8 +128,9 @@ html_theme = 'openstackdocs'
128 128
 # Theme options are theme-specific and customize the look and feel of a theme
129 129
 # further.  For a list of options available for each theme, see the
130 130
 # documentation.
131
-#
132
-# html_theme_options = {}
131
+html_theme_options = {
132
+    "display_toc": False
133
+}
133 134
 
134 135
 # Add any paths that contain custom themes here, relative to this directory.
135 136
 html_theme_path = [openstackdocstheme.get_html_theme_path()]

+ 9
- 0
doc/source/configure.rst View File

@@ -0,0 +1,9 @@
1
+Configuration
2
+=============
3
+
4
+The OpenStack monitoring plugins within monitorstack require basic
5
+configuration that provides URLs for endpoints and credentials for those
6
+endpoints. The following example provides configuration details for various
7
+OpenStack services:
8
+
9
+.. literalinclude:: ../../tests/files/test-openstack.ini

+ 41
- 0
doc/source/develop.rst View File

@@ -0,0 +1,41 @@
1
+===============
2
+Developer guide
3
+===============
4
+
5
+One of the design goals of monitorstack is to make it easy to develop new
6
+monitoring plugins.
7
+
8
+Writing plugins
9
+---------------
10
+
11
+Start by adding a new python script in the ``plugins`` directory. The plugin
12
+will inherit the same name as the file. For example, creating a plugin file
13
+called ``my_plugin.py`` will create a new plugin called ``my_plugin``.
14
+
15
+Use the ``uptime`` plugin as a guide for developing new plugins:
16
+
17
+.. literalinclude:: ../../monitorstack/plugins/uptime.py
18
+
19
+Every plugin will have a ``cli()`` method that is the equivalent of
20
+``___main___`` in other Python scripts.
21
+
22
+Testing plugins
23
+---------------
24
+
25
+Add tests in the ``tests`` directory and follow the ``uptime`` example. Here
26
+are the contents of ``tests/test_plugin_uptime.py`` as an example:
27
+
28
+.. literalinclude:: ../../tests/test_plugin_uptime.py
29
+
30
+Running tests
31
+-------------
32
+
33
+There are two main sets of tests: pep8/flake8 tests and unit tests:
34
+
35
+.. code-block:: console
36
+
37
+    # PEP8 and flake8 checks
38
+    tox -e linters
39
+
40
+    # Unit tests
41
+    tox -e functional

+ 15
- 11
doc/source/index.rst View File

@@ -1,15 +1,19 @@
1
-Welcome to monitorstack's documentation!
2
-========================================
3
-
4
-.. toctree::
5
-   :maxdepth: 2
6
-   :caption: Contents:
1
+==============================
2
+Documentation for monitorstack
3
+==============================
7 4
 
5
+The monitorstack project provides a framework for writing monitoring plugins
6
+that output data in various formats for different monitoring systems.
7
+Developers can quickly add new monitoring plugins (along with tests) without
8
+worrying about how to format the data.
8 9
 
10
+Documentation sections
11
+----------------------
9 12
 
10
-Indices and tables
11
-==================
13
+.. toctree::
14
+   :maxdepth: 2
12 15
 
13
-* :ref:`genindex`
14
-* :ref:`modindex`
15
-* :ref:`search`
16
+   install
17
+   configure
18
+   usage
19
+   develop

+ 19
- 0
doc/source/install.rst View File

@@ -0,0 +1,19 @@
1
+Installation
2
+============
3
+
4
+The project is conveniently packaged as a Python package that is installed with
5
+``pip``.
6
+
7
+Installing from pypi with ``pip``
8
+---------------------------------
9
+
10
+*The pypi-based installation is coming soon.*
11
+
12
+Installing from git
13
+-------------------
14
+
15
+Install monitorstack with ``pip``:
16
+
17
+.. code-block:: console
18
+
19
+    pip install git+https://github.com/openstack/monitorstack

+ 128
- 0
doc/source/usage.rst View File

@@ -0,0 +1,128 @@
1
+Usage
2
+=====
3
+
4
+Run the ``monitorstack`` command without any arguments to review a list of
5
+available commands and options:
6
+
7
+.. code-block:: console
8
+
9
+    $ monitorstack
10
+    Usage: monitorstack [OPTIONS] COMMAND [ARGS]...
11
+
12
+      A complex command line interface.
13
+
14
+    Options:
15
+      -f, --format [json|line|telegraf|rax-maas]
16
+                                      Output format (valid options: json, line,
17
+                                      telegraf, rax-maas
18
+      -v, --verbose                   Enables verbose mode.
19
+      --help                          Show this message and exit.
20
+
21
+    Commands:
22
+      kvm                    Get metrics from a KVM hypervisor.
23
+      os_block_pools_totals  Get block storage totals from the available pools.
24
+      os_block_pools_usage   Get block storage usage from the available pools.
25
+      os_vm_quota_cores      Get nova cores quotas.
26
+      os_vm_quota_instance   Get nova instance quotas.
27
+      os_vm_quota_ram        Get nova ram quotas.
28
+      os_vm_used_cores       Get nova used cores.
29
+      os_vm_used_disk        Get nova used disk.
30
+      os_vm_used_instance    Get nova used instances.
31
+      os_vm_used_ram         Get nova used ram.
32
+      process                Check if a process is running.
33
+      uptime                 Get system uptime.
34
+
35
+Executing simple plugins
36
+------------------------
37
+
38
+The most simple plugins do not require any arguments. For example, to get the
39
+system uptime, use the ``uptime`` command to run the corresponding ``uptime``
40
+plugin:
41
+
42
+.. code-block:: console
43
+
44
+    $ monitorstack uptime
45
+    {
46
+      "variables": {
47
+        "uptime": "22613.26"
48
+      },
49
+      "message": "uptime is ok",
50
+      "meta": {
51
+        "platform": "Linux-4.10.5-200.fc25.x86_64-x86_64-with-fedora-25-Twenty_Five"
52
+      },
53
+      "exit_code": 0,
54
+      "measurement_name": "system_uptime"
55
+    }
56
+
57
+The default output type is json, but this is configured with the ``-f,
58
+--format`` option. Here is another example that outputs data in telegraf
59
+format:
60
+
61
+.. code-block:: console
62
+
63
+    $ monitorstack -f telegraf uptime
64
+    system_uptime platform=Linux-4.10.5-200.fc25.x86_64-x86_64-with-fedora-25-Twenty_Five uptime=23005.05 1490819061833774080
65
+
66
+Executing plugins with arguments
67
+--------------------------------
68
+
69
+The ``process`` plugin searches the current list of running processes to find
70
+any that match a string provided as an argument. Execute the plugin without any
71
+arguments for some usage help:
72
+
73
+.. code-block:: console
74
+
75
+    $ monitorstack process
76
+    Usage: monitorstack process [OPTIONS] PROCESS_NAME
77
+
78
+    Error: Missing argument "process_name".
79
+
80
+In this example, we want to ensure that the ``chronyd`` process is running:
81
+
82
+.. code-block:: console
83
+
84
+  $ monitorstack process chronyd
85
+  {
86
+    "variables": {
87
+      "chronyd": 1
88
+    },
89
+    "message": "process check is ok",
90
+    "meta": {
91
+      "platform": "Linux-4.10.5-200.fc25.x86_64-x86_64-with-fedora-25-Twenty_Five"
92
+    },
93
+    "exit_code": 0,
94
+    "measurement_name": "process"
95
+  }
96
+
97
+We can also see a negative result if we check for a non-existent process called
98
+``processdoesntexist``:
99
+
100
+.. code-block:: console
101
+
102
+  $ monitorstack process processdoesntexist
103
+  {
104
+    "variables": {
105
+      "processdoesntexist": 0
106
+    },
107
+    "message": "process failed -- Process processdoesntexist not found",
108
+    "meta": {
109
+      "platform": "Linux-4.10.5-200.fc25.x86_64-x86_64-with-fedora-25-Twenty_Five"
110
+    },
111
+    "exit_code": 1,
112
+    "measurement_name": "process"
113
+  }
114
+
115
+Executing plugins with configuration files
116
+------------------------------------------
117
+
118
+Many of the OpenStack plugins require a configuration file that specifies the
119
+URLs of OpenStack endpoints as well as valid credentials for those endpoints.
120
+For more information on the format of these configuration files, refer to the
121
+documentation on `configuration <configure.html>`_.
122
+
123
+Here is an example with the ``os_vm_quota_ram`` plugin with a configuration
124
+file in ``/home/user/openstack.ini``:
125
+
126
+.. code-block:: console
127
+
128
+  $ monitorstack os_vm_quota_ram --config-file=/etc/openstack/openstack.ini

Loading…
Cancel
Save