wiki:SetupStory
Last modified 5 years ago Last modified on 04.10.2013 12:54:11

Example scenario of deployment

Introduction

For several reasons I can't provide sandboxed instance of DashWiki for you to check it out yourself. I feel I should provide some overview of how it works and how it looks like, though, so I wrote this scenario.

The story assumes I have some monitoring system deployed already or I will have one soon. I'll put a placeholder interface script at appropriate place for the story to be easily reproducible. Small discussion about interfaces to monitoring systems can be found below the story.

What I expect from this DashWiki instance is a quick overview of situation in systems under monitoring (that's what dashboards are for, in fact). I don't want to be tied by what monitoring system thinks is possible to include in dashboard (Nagios, I'm looking at you). I want to be able to evolve my dashboard along with monitoring itself and I want to have a possibility to include data from other monitoring systems I happen to deploy in future.

The story

My environment

In the scenario we'll use Debian Squeeze (with Django 1.2 coming from distribution).

There are four hosts: onyx, granite, basalt and hematite, all under domain atled.pl. DashWiki will be deployed on onyx, with rest being monitored servers.

Hello World

The first thing to do is to deploy DashWiki. The procedure is described in SetupGuide; it boils down to installing Django and a web server, running the deployment script and setting up file permissions.

Welcome page should look like this:

Let's create first user called root:

dashwiki$ ./manage.py useradd root root@example.com.invalid
User root created with password Ahx4caed

Note the password was automatically generated. You can reset it with userpw command.

Now it's good time to login and to create first page. Let it have following content:

= First page =

This is completely new instance of [[http://dashwiki.jarowit.net/ DashWiki]].

Let's see if this web application is **awsome**.

After saving you should see this:

You can find more formatting options on MarkupSyntax page.

First macro

Now a word about macros. Macros are the single most important reason DashWiki was written at all.

Macro is a way of retrieving information from an external system. It's similar to the concept of function call in programming languages, except DashWiki provides markup language instead of programming language. Macro has a name, a list of arguments (possibly empty), some body (plugin parameters combined with protocol make up for this) and returned value. More about macros is here.

Returned value is quite fancy here. It may be a string or an image, but it may also be a list of strings. If macro returns a list, you may use it in enumerated list: element holding macro call will be repeated for every element in the result.

To see all this let's define a macro (Macros -> Create new macro). For now the macro will return static list of servers, but it may easily be changed to retrieve list of servers from some sort of CGI script.

Use following fields values:

  • name set to servers
  • result type set to list
  • leave macro arguments empty
  • plugin parameters set to following JSON (it may be parametrized with macro arguments; see pfJSON description for details):
    {
      "value": ["onyx", "basalt", "granite", "hematite"]
    }
    
  • protocol set to static
  • URL set to none:// (it will not be used, but it needs to be non-empty)

"New macro" form will look like this:

Let's go to main page and add the list of servers there. Wiki source should be following:

= First page =

This is completely new instance of [[http://dashwiki.jarowit.net/ DashWiki]].

Let's see if this web application is **awsome**.

Machines in this network:

  * server __[[@servers]]__

Note how the single macro call [[@servers]] got expanded along with the rest of list element. This way you only need to define your dashboards once, and all the updates to your network will show automatically (of course if the script called by macro learns about new servers somehow).

Use remote data

Now we'll collect some status from the servers. We'll use CGI script for this.

#!/usr/bin/perl

use CGI qw{:standard};

print header(-type => "text/plain");

my $var = param('status');
if ($var eq 'uptime') {
  open my $f, "<", "/proc/uptime";
  my $uptime = <$f>;
  close $f;
  printf "%s\n", split / /, $uptime;
} elsif ($var eq 'load') {
  open my $f, "<", "/proc/loadavg";
  my $load = <$f>;
  printf "%s\n", split / /, $load;
}

Deploy this script so each server has it accessible under http://$server.atled.pl/cgi-bin/status.pl.

This is obviously just a placeholder for real-world monitoring or status collection system, but for the sake of presentation it will do.

Now it's time to define a new macro to use the script(s):

  • set name to status
  • set result type to string
  • set macro arguments to server_name,variable
  • plugin parameters leave empty
  • protocol set to HTTP
  • URL set to http://%(server_name)s.atled.pl/cgi-bin/status.pl?status=%(variable)s

This time the plugin parameters is unused, but in exchange the URL used and more, is parametrized with macro arguments (note the %(...)s syntax, similar to Python's format string; see pfURL description for details).

Now that we have a new macro, let's use it in dashboard:

= Status of machines =

Machines in this network:

||* server       *||* uptime (s)                     *||* load                        *||
||  [[@servers]]  ||  [[@status $servers, "uptime"]]  || [[@status $servers, "load"]]  ||

Table row is repeated in the same way as list element if macro returns a list. Also note how the current value of [[@servers]] is referenced in [[@status]] calls: [[@status]] macro will be called for every element returned by [[@servers]].

The result looks like this:

Conclusion

We have created a dynamically updated dashboard displaying uptime and load average of our servers. This dashboard is easily extended with new data to display, what is highly convenient if you have a real monitoring system instead of our tiny CGI mock-up script.

If the [[@servers]] macro called another CGI script or similar instead of returning static data, having new hosts displayed would require no extra action in dashboard. I would say it's a necessary feature when number of dashboards grows, as you shouldn't be forced to keep track of updating them all after each installation.

Dashboard may also display information retrieved from many different sources: you may combine quote of the day, newest Dilbert strip and load status collected by Nagios or Zenoss, all on the same page.

I have not covered adding graphs to DashWiki in this tour, but I'm sure you'll figure it now on your own.

API to monitoring systems

TODO

  • raw data access
    • RRD DB
    • text file
      • flat
      • JSON
      • YAML
    • SQL database
  • CGI
    • HTTP (possibly REST)
    • XML-RPC
  • specialized API servers
    • no generic one at the moment
  • xmlrpcd

Attachments