Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

manifest

improvements in readme
  • Loading branch information...
commit f3490908df938a224912c1ccc25757b5a2aaa3a4 1 parent e493d8d
@raulgarreta raulgarreta authored
View
2  MANIFEST.in
@@ -0,0 +1,2 @@
+include MANIFEST.in
+recursive-include kitsune/templates *
View
136 README.rst
@@ -14,6 +14,12 @@ Description
A Django Admin app to perform host checks. A control panel will be added to the Admin in order to configure hosts, checks and monitor check results.
+Screenshots:
+
+.. image:: http://www.tryolabs.com/static/images/kitsune_jobs.jpg
+
+.. image:: http://www.tryolabs.com/static/images/kitsune_job.jpg
+
********
Features
********
@@ -23,26 +29,35 @@ Add hosts to monitor.
* Checks
-Add jobs with checks to be performed
+
-Schedule
+
-Check to be performed
+
-Host to check
+
-Select users or groups to be notified
+
-Configure notification rules
+
-Select how to render results
+
-Set amount of log history to keep
* Custom Checks
--You can implement your own checks by implementing a subclass of
+-You can implement your own checks by implementing a subclass of `kitsune.base.BaseKitsuneCheck`
* Nagios Checks
-A builtin check is provided that wrapps any Nagios check.
+
-You can use any existing Nagios check within django-kitsune
* Logs
-Log and list check results
* Result Renderers
--Can implement renderers by implementing a subclass of
+-Can implement renderers by implementing a subclass of `kitsune.renderers.KitsuneJobRenderer`
+
-Returns a html with the corresponding result that will be rendered within result listings.
* List Checks
@@ -50,8 +65,11 @@ Add hosts to monitor.
* Notification Rules
-Notifications through e-mail.
+
-Configure who to notify: Groups or Users.
+
-Configure when to trigger a notification.
+
-Configure the frequency of notifications to avoid spam emails :)
* All configurations are made through a graphic UI within admin panel.
@@ -62,7 +80,7 @@ Requirements
************
* Python 2.6 and higher.
-* Nagios plugins: `sudo apt-get install nagios-plugins`
+* Nagios plugins: `sudo apt-get install nagios-plugins` (if you want to use Nagios checks).
************
Installation
@@ -79,8 +97,118 @@ Configuration
Kitsune can be configured via the following parameters, to be defined in your project settings file:
-* ``KITSUNE_RENDERERS``: List of modules that contain renderer classes, eg:: ['myproject.myapp.renderers']
+* ``KITSUNE_RENDERERS``: List of modules that contain renderer classes, eg:: `KITSUNE_RENDERERS = ['myproject.myapp.renderers']`.
+
+Kitsune comes with a default renderer `kitsune.renderers.KitsuneJobRenderer`.
+
+
+*****
+Usage
+*****
+
+Add a new Host
+--------------
+
+Add a Nagios check
+------------------
+
+For example, to add a check_disk, do the following steps::
+
+1. Within Admin go to Kitsune -> Jobs -> Add job
+2. Fill the necessary fields, eg::
+
+* Name: check_disk
+* Host: select a job from the combobox
+* Command: select nagios wrapper: kitsune_nagios_check
+* Args: you must provide a special parameter `check` with the name of the nagios check eg: check=check_disk.
+
+Then provide the necessary nagios check arguments, in this case: -u=GB -w=5 -c=2 -p=/
+
+To sum up, the string of arguments will be: `check=check_disk -u=GB -w=5 -c=2 -p=/`
+
+3. Select the result Renderer, eg: KitsuneJobRenderer
+4. Configure scheduling options, eg: Frequency: Hourly, Params: `interval:1`.
+
+This will schedule the check to be run every 1 hour.
+
+5. Configure log options, last logs to keep specifies the last N logs to keep.
+6. Configure Notification rules.
+
+Every check returns a status code of 0=OK, 1=WARNING, 2=CRITICAL ERROR, 3=UNKNOWN ERROR with its corresponding status message.
+
+With notification rules you must set the:
+
+* Threshold (the status code to be reached)
+* Rule type,
+
+Last time: triggered when last result reached the threshold.
+
+N last times: triggered when last N results reached the threshold.
+
+M of N last times: triggered when M of the last N results reached the threshold.
+
+Rule N and Rule M parameters.
+
+Notification frequency:
+* Interval unit, Interval value sets the maximum frequency to receive email notifications. These are useful to avoid filling admin inbox with notification mails.
+* User/Group specifies the users or group of users to be notified. These must be staff users and shall be created within admin.
+
+
+Add a custom check
+------------------
+
+In order to implement a custom check, you must implement a class that is subclass of kitsune.base.BaseKitsuneCheck.
+
+Within this class, you must implement the method check(self, *args, **options). For example::
+
+from kitsune.renderers import STATUS_OK, STATUS_WARNING, STATUS_CRITICAL, STATUS_UNKNOWN
+from kitsune.base import BaseKitsuneCheck
+
+class Command(BaseKitsuneCheck):
+ help = 'A simple test check.'
+
+ def check(self, *args, **options):
+ self.status_code = STATUS_OK
+
+ if self.status_code == STATUS_OK:
+ self.status_message = 'OK message'
+ elif self.status_code == STATUS_WARNING:
+ self.status_message = 'WARNING message'
+ elif self.status_code == STATUS_CRITICAL:
+ self.status_message = 'CRITICAL message'
+ else:
+ self.status_message = 'UNKNOWN message'
+
+With *args and **options you will receive the arguments and options set from the Args string.
+
+Modules that implement checks are Django management commands, and must live within management.commands package of an app within your project.
+
+Add a custom renderer
+---------------------
+
+Renderers are in charge to render the results within the admin panel. They will take the status code and status message and return a html.
+
+If you want to implement your own renderer, you must implement a class that is sublcass of kitsune.renderers.KitsuneJobRenderer.
+
+You must implement to methods: get_html_status(self, log) that receives a log and and returns a html for status code.
+
+get_html_message(self, log) that recevies a log and returns a html for status message.
+
+For example::
+
+from django.template.loader import render_to_string
+from kitsune.renderers import KitsuneJobRenderer
+from kitsune.base import STATUS_OK, STATUS_WARNING, STATUS_CRITICAL, STATUS_UNKNOWN
+class MyJobRenderer(KitsuneJobRenderer):
+
+ def get_html_status(self, log):
+ return render_to_string('kitsune/status_code.html', dictionary={'status_code':int(log.stderr)})
+
+ def get_html_message(self, log):
+ return 'All OK!'
+
+Then you must specify where to get this renderer with the KITSUNE_RENDERERS at your project settings (see bellow).
***************
Acknowledgments
View
2  kitsune/management/commands/kitsune_test_check.py
@@ -19,7 +19,7 @@ class Command(BaseKitsuneCheck):
help = 'A simple test check.'
- def check(self):
+ def check(self, *args, **options):
self.status_code = STATUS_OK
if self.status_code == STATUS_OK:
View
4 setup.py
@@ -12,8 +12,8 @@
author='Raul Garreta - Tryolabs',
author_email='raul@tryolabs.com',
url='https://github.com/tryolabs/django-kitsune',
- #packages=['django-kitsune'],
packages=find_packages(),
- #package_dir={'django-kitsune': 'kitsune'},
+ include_package_data=True,
+ zip_safe=False
)
Please sign in to comment.
Something went wrong with that request. Please try again.