diff --git a/doc/source/tutorials/index.rst b/doc/source/tutorials/index.rst index ed15139..c1b9128 100644 --- a/doc/source/tutorials/index.rst +++ b/doc/source/tutorials/index.rst @@ -7,3 +7,4 @@ Tutorials getting_started developing_the_api running_the_tests + monitoring_with_your_custom_plugin diff --git a/doc/source/tutorials/monitoring_with_your_custom_plugin.rst b/doc/source/tutorials/monitoring_with_your_custom_plugin.rst new file mode 100644 index 0000000..7c63afc --- /dev/null +++ b/doc/source/tutorials/monitoring_with_your_custom_plugin.rst @@ -0,0 +1,83 @@ +.. role:: bash(code) + :language: bash + +Monitoring with your custom plugin +################################## + +Surveil is compatible with Nagios plugins. It is trivial to write a custom plugin to monitor your applcation. In this guide, we will create a new plugin and configure a new Host that uses it in Surveil. + +1. Test the check_example plugin +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The first step to create a plugin is to successfully test the check_example plugin. This plugin +will serve as a base file to create your own plugin. + +Create virtual environment and install requirements: :: + + virtualenv env + source env/bin/activate + cd tools/docker/alignak_container/plugins/check-example + pip install -r requirements.txt + +Install the check_example plugin: :: + + python setup.py develop + +Run the plugin: :: + + check_example + +The output should look like this: :: + + DISK OK - free space: / 3326 MB (56%); | /=2643MB;5948;5958;0;5968 + +2. Modify the plugin +~~~~~~~~~~~~~~~~~~~~ + +The next step is to modify the plugin to meet your needs. In order to do this, +please refer to the `Nagios plugin API documentation `_. + + +3. Create a host using this plugin +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Now that you are done developing your plugin, it is time to use it in Surveil. + +Creating a command +------------------ + +Before you can use your plugin in a host/service configuration, you need to create an Alignak command: :: + + surveil config-command-create --command_name check_example --command_line "check_example" + +Creating a host +--------------- + +Create a host with the following command: :: + + surveil config-host-create --host_name check_example_host --address savoirfairelinux.com + +Creating a Service +------------------ + +Create a service with the following command: :: + + surveil config-service-create --host_name check_example_host --service_description check_example_service --check_command "check_example" --max_check_attempts 4 --check_interval 5 --retry_interval 3 --check_period "24x7" --notification_interval 30 --notification_period "24x7" --contacts admin --contact_groups admins + +Reload the config +----------------- + +Reload the config this will tell Alignak to reload the new config with the new host :: + + surveil config-reload + +Show the new service +-------------------- + +Show the service list with this command: :: + + surveil status-service-list + + +You should see the service you just add in the list with the correct status (this could take a minute a two for the +result to show) diff --git a/tools/docker/alignak_container/Dockerfile b/tools/docker/alignak_container/Dockerfile index b4058e5..97e7afc 100644 --- a/tools/docker/alignak_container/Dockerfile +++ b/tools/docker/alignak_container/Dockerfile @@ -108,10 +108,18 @@ RUN sh -c 'gpg --recv-keys --keyserver keyserver.ubuntu.com 2320E8F8 && gpg --e apt-get update && \ apt-get install -y --force-yes monitoring-packs-sfl-generic-host monitoring-packs-sfl-linux-system-nrpe +## Add check example plugin +ADD plugins/check-example /plugins/check_example +RUN virtualenv /plugins/check_example/env +ENV PATH=$PATH:/plugins/check_example/env/bin +RUN /plugins/check_example/env/bin/pip install -r /plugins/check_example/requirements.txt +RUN cd /plugins/check_example && sudo /opt/surveilplugins/env/bin/python setup.py install && ln -s /opt/surveilplugins/env/bin/check_example /usr/lib/alignak/plugins/ + ## configuration ADD setup.sh /setup.sh RUN rm -rf /etc/alignak ADD etc/alignak /etc/alignak + RUN chown -R root:alignak /etc/alignak ### Supervisor diff --git a/doc/source/tutorial_hello_world.rst b/tools/docker/alignak_container/plugins/check-example/check_example/__init__.py similarity index 100% rename from doc/source/tutorial_hello_world.rst rename to tools/docker/alignak_container/plugins/check-example/check_example/__init__.py diff --git a/tools/docker/alignak_container/plugins/check-example/check_example/check_example.py b/tools/docker/alignak_container/plugins/check-example/check_example/check_example.py new file mode 100644 index 0000000..aedf68d --- /dev/null +++ b/tools/docker/alignak_container/plugins/check-example/check_example/check_example.py @@ -0,0 +1,30 @@ +# Copyright 2014 - Savoir-Faire Linux inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + +import sys + + +class Plugin(object): + + def run(self): + print("DISK OK - free space: / 3326 MB (56%); | /=2643MB;5948;5958;0;" + "5968") + sys.exit(0) + + +def main(): + Plugin().run() + +if __name__ == "__main__": + main() diff --git a/tools/docker/alignak_container/plugins/check-example/requirements.txt b/tools/docker/alignak_container/plugins/check-example/requirements.txt new file mode 100644 index 0000000..f229360 --- /dev/null +++ b/tools/docker/alignak_container/plugins/check-example/requirements.txt @@ -0,0 +1 @@ +requests diff --git a/tools/docker/alignak_container/plugins/check-example/setup.py b/tools/docker/alignak_container/plugins/check-example/setup.py new file mode 100644 index 0000000..b812ac9 --- /dev/null +++ b/tools/docker/alignak_container/plugins/check-example/setup.py @@ -0,0 +1,38 @@ +# Copyright 2014 - Savoir-Faire Linux inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + +from __future__ import with_statement + +import setuptools + + +description = 'An Alignak plugin' +long_description = (''' .. ''') + + +setuptools.setup( + name='check_example', + version="1.0", + packages=setuptools.find_packages(), + author="Vincent Fournier", + author_email="vincent.fournier@savoirfairelinux.com", + long_description=long_description, + description=description, + platforms=['any'], + install_requires=[], + entry_points=""" + [console_scripts] + check_example = check_example.check_example:main + """, +)