Dashboards

Multisite Dashbaords

Since version 1.1.12 Check_MK Multisite supports dashboards. Generally spoken a dashboard combines various contents (Multisite views, performance graphs and other things) into one page. What makes Multisite's dashboard special in comparison with other GUIs is its smart layout algorithm. It automatically adapts a dashboard to the size and aspect of the screen that a user is viewing it with.

Multisite uses an example dashboard as the central main overview:

Creating your own dashboards

Customizing dashboards can be done in two ways:

1. Modifying the builtin default dashboard "main".
2. Creating additional dashboards with other names.

In the first case all users will see your modified dashboard instead of the builtin one. In the second case your additional dashboards can be called via the relative URL dashboard.py?name=<NAME>. If you refer to this from another application then do not forget to add the server name and full path, for example http://demo.mathias-kettner.de/demo/check_mk/dashboard.py?name=main. A good place for such links is the Custom Links snapin.

The dashboards are defined as plugins to Multisite. You can find the definition of the builtin dashboard in share/check_mk/web/plugins/dashboards/builtin.py (the exact location of your share directory depends on your installation):

builtin_dashboards["main"] = {
    "title" : _("Main Overview"),
    "dashlets" : [
        {
            "title"      : _("Host Statistics"),
            "url"        : "dashlet_hoststats.py",
            "position"   : (1, 1),
            "size"       : (10, 6),
            "shadow"     : True,
            "background" : True,
            "refresh"    : 60,
        },
        {
            "title"      : _("Service Statistics"),
            "url"        : "dashlet_servicestats.py",
            "position"   : (11, 1),
            "size"       : (10, 6),
            "shadow"     : True,
            "background" : True,
            "refresh"    : 60,
        },
        # Further dashlets...
}

Modifying that file directly is no good idea since an update of Check_MK will overwrite your changes. A better way is to create an own file in the same directory (if you are using OMD, then place this file in ~/local/share/check_mk/web/plugins/dashboards). If you just want to modify the main dashboard, a copy of the original file is a good starting point.

If you are using a manual non-OMD installation, then make sure that it does not begin with an a or b in order to make sure that it is read after the shipped file. Your own file can have any name as long as it ends with .py.

Structure of a dashboard definition

Each dashboard definition begins with builtin_dashboards["myboard"] = {. If you want to modify the builtin dashboard then substitute myboard with main.

From a Python point of view the dashboard definition is a dictionary with two keys:

• "title": the visible title of your dashboard
• "dashlets": a list of all dashlets the form your dashboard

The dashlets is what all in dashboards is about. A dashlet is a rectangular area showing some content. The configuration is again a Python dictionary with several mandatory and optional keys. An example is the dashlet with the statistics of all hosts:

        {
             "title"      : _("Host Statistics"),
             "url"        : "dashlet_hoststats.py",
             "position"   : (1, 1),
             "size"       : (10, 6),
             "shadow"     : True,
             "background" : True,
             "refresh"    : 60,
        },

What do the various keys mean? Some deal with the content, other with the styling and yet other with the position and dimension. Let's begin with the easier ones:

"title"	optional	The title to be displayed on top of the dashlet. It is optional. When the size of a dashlet is computed then the size of the title is substracted from the actual content of the dashlet. If you enclose your title with _(...) then it will be translatable into other languages.
"title_url"	optional	You can make the title clickable be defining an URL.
"shadow"	optional	If this is set to True (which is the default), then the dashlet will be surrounded by a drop shadow. The size of the shadow does not occupy any space when it comes to layout. Switch off the shadow by setting this to False
"background"	optional	If you set this key to False then the dashlet's background will be completely transparent. The default is True.
"refresh"	optional	Setting this to a number of seconds will make Multisite automatically repaint the contents of the dashlet that often. Don't make the refresh too often, in order to safe server and client ressources! Note: this key is only supported for the content types "url" and "urlfunc".

The following group of keys is alternative and defines the content of the dashlet. You need to specify exactly one of those:

"url"	define exactly one	The URL of an HTTP ressource providing the content of this dashlet. The content will be fetched with an AJAX request and be inserted as the inner HTML of a <div> element. This content type supports the "refresh" key.
"urlfunc"		This is the same as "url" but you specify a Python function. This function will be called without any arguments and must return the URL for the dashlet as a string. You can use this for making the URL dependent on some context like HTML GET variables.
"iframe"		The content of the dashlet will be an <iframe> showing the specified URL. This can be used in order to show information from third party applications. If the content does not fit into the size of the dashlet then scrollbars will appear. Note: the "refresh" will not apply here. The foreign page has to repaint itself if you need a regular update.
"view"		This is similar to "iframe" but an easy shortcut if you want to embed a Multisite view. Simply put the name of the view here. You can add filter variables in URL style by appending them with an &.
"content"		Display static HTML code. Directly put in your HTML code as value to this key. This is any easy way to add your company logo to a dashboard.

The Smart Layout Algorithm

What makes Multisite dashboards special is their capability to dynamically adapt to different screen sizes. This feature should more the compensate the (current) lack of a graphical dashboard editor. The basic idea behind this is that some dashlets are assigned dynamic dimensions and automatically grow to the maximum possible size while others have fixed sizes (like the host and service statistics in the default dashboard).

In order to make exact positioning easier, all coordinates are measured in multiple of 32 pixels. You can think of the dashboard having an invisible raster of squares of the size 32x32 pixels.

"position"	mandatory	The position of the dashlet given as a pair of two integers of X and Y, where (1,1) means that the top left corner of the dashlet will be positioned top left of the dashboard. (11,1) means a position of 320 pixels from the left and 0 from the top of the dashboard. A negative value changes the origin to the right or bottom border. So a dashlet with the position (-1,1) will have its right upper corner placed at the right upper corner of the dashboard and (-11,-2) will place the lower right corner of a dashlet at 320 pixels left of the right border and 32 pixels above the lower border.
"size"	mandatory	The size is where the smart layout comes into play. Each dimension of the dashlet (width or height) can either be set to a fixed number of raster units or to the values MAX or GROW. GROW means that the dashlet will grow in that dimension as far as possible without overlapping other dashlets. A dashlet that is positioned relative to the left border will grow towards the right border if GROW is specified as its width. For the other three directions this is working in the same way.

This is how the smart layout algorithm will determine the size of all dashlets.

1. The total size of the dashboard is determined by querying the size of the browser window.
2. All dashlets are positioned with their minimal possible size. For GROW dimensions the size 1 is assumed. For MAX dimensions the largest possible size is assumed. Dashlets with a fixed size start (and end) with that size.
3. Each dashlet with non-fixed dimensions that still has space to grow will be grown by one raster cell.
4. Step 3. is being repeated until now dashlet can grow any further.

This happens not only when the dashboard is being drawn initially but also if you resize your browser windows or change the browser's zoom level (Firefox: Ctrl-+ or -).

Two further notes about the layout:

• Dashlets will never overlap.
• If a dashlet cannot be positioned completely due to lack of place it will not be displayed at all.