Developers Guide

This document contains some quick notes that are needed to get started with developing in Adagios. It's a work in progress and anyone is welcome to make changes to the guide.

If you want to implement a new feature, go through the Roadmap to make sure you are not conflicting with someone else's work.

Sending us patches

We use github pull requests to receive patches. If you are not familiar with them, read on for a short explanation of the process.

If you are only commiting trivial patches you can browse to the files here on github and click edit.

You will be asked to fork the repo (do that!) and after you have saved your changes you will have a copy of our code on your repository.

When you have saved, click the "pull request" button in your repository and it will open up an issue on our and and ask for merging the patch.

Code style guide

Adagios python code should conform with PEP8 with the following exceptions:

• Line length should generally not exceed 120 chars. Exceptions to this are long strings (like long-lined nagios configuration strings or error messages) where line concatenation does not increase readability. If breaking up strings, use python string concatenation, not line continuations.

Before sending patches, run it through pep8 check by running:

pep8 yourfile.py --max-line-length=120

Casing

CONSTANT_NAME variable_name
function_name method_name
PackageName module_name ClassName

Setting up your dev environment

Make sure you have all the dependencies installed on your machine and optimally have gotten adagios to work. You will need a set of nagios configuration under /etc/nagios but if you are not working on the status views it should be optional to have nagios installed and running.

# Clone our repo
git clone http://github.com/opinkerfi/adagios.git

# Start the django web server
cd adagios/adagios
python manage.py runserver 0.0.0.0:8000

Testing

Most of the complex code logic lies in underlying libraries like pynag.

We use Django's unit tests for smoke-testing views. Please do not commit your code if you break any of the unit tests.

Unit tests themselves live within every django app so for examples tests for the status module live in /status/tests.py. You can run the unit tests from the command line with:

python manage.py test
Creating test database for alias 'default'...
.................
----------------------------------------------------------------------
Ran 17 tests in 2.906s

OK
Destroying test database for alias 'default'...

If you create any new views, you are also responsible for creating unit tests for them.

Additionally it is recommended that you test adagios inside a clean docker instance: Running Adagios inside docker

Configurables and settings.py

The main entry point for a user to configure any settings or twiddly knobs is by editing adagios.conf and its web front-end at /adagios/misc/settings.

If you find yourself in the need of creating a config setting or a constant somewhere it usually belongs in settings.py. Keep the following guide-line in mind when adding a new configuration variable:

• Use lower_case names for variable to differentiate adagios configuration variables from django settings.
• Put a sensible default value (i.e. something that works out of the box)
• At a new entry, with description in adagios/etc/adagios/adagios.conf
• Add a new member and help_text in adagios.misc.forms.AdagiosSettingsForm

Understanding the Web API

Adagios has a web API that can be browsed under /adagios/rest/. At the backend it is just a collection of python methods that return JSON compatible data.

The rules of the web api is as follows:

• All calls to backend methods are done via POST (even though some of them are only fetching data)
• You can browse all available methods by opening /adagios/rest/ in a browser, and clicking a method will give you an HTML form that is a good start for testing the web api

How to add new methods to the rest interface

open up the relevant python file (like /rest/status/ points to adagios.status.rest.py) and create a new method like so:

def test_method(somestring=''):
    """ Just a web api test. Returns a string """
    if somestring: 
         return "You just sent me a string"
    else:
        return "Hello world"

Thats it! After that you can browse for it under /adagios/rest/json/test_method and try it out.

Calling the web api from javascript

The api also autogenerates javascript for us which returns asynchronous promise objects. Use it like so:

<script>
parameters = {};
parameters['somestring'] = "this is a test";
adagios.rest.status.test_method(parameters)
    .done(function(data) {
        alert(data);
    })
    .fail(function(data) {
        alert("Got error while calling test_method");
    });
</script>

Creating your own extensions

This chapter is a short guide how to get up and running with your own extension to adagios. Extensions are in the form of "Django apps" so if you are already familiar with Django and apps in django then there are a few surprises here.

There is already an example extension in the adagios tree called "myapp". And if you just want to get started with coding you can dive right into adagios.myapp.views.hello_world() to get started.

Enabling an extension can be done by editing adagios.conf (or a subsequent adagios/conf.d) for example, enable myapp by editing /etc/adagios/adagios.conf and adding the following line:

plugins['myapp'] = 'adagios.myapp'

restart your web server and you should see "myapp is working ;)" top menu option displayed beside okconfig.

In this case 'adagios.myapp' can be any django app that is in your python path, so if your application lives outside the adagios repository, make sure it is in python path.