Differences between revisions 7 and 8
Revision 7 as of 2010-05-07 17:52:09
Size: 4880
Editor: ahasenack
Revision 8 as of 2019-05-06 16:43:57
Size: 0
Editor: bryanquigley
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
= Custom Graphs =
In addition to the default graphs Landscape has in its monitoring module, it is possible to create custom graphs. With custom graphs, all the admin needs to do is provide a script which will output the number that needs to be plotted. Landscape will take care of sending the script to selected computers, run it every five minutes and plot the result for you.

{i} '''Note:''' Custom Graphs will only work with landscape-client version 1.0.29 or higher and Script Execution must be [[https://help.landscape.canonical.com/RunningScripts#Enabling%20script%20execution|enabled]].

= Creating a graph =
When you first click on the "Custom Graphs" icon in sidebar, you are presented with a blank page with the custom graph listing. Initially, no custom graphs are available.


This presents us with a page very similar to the one from the Landscape Script Library. After all, a custom graph is basically that: a script that is run on the client machine:

 * '''Title:''' a name that represents this graph, such as "HTTP requests per second"
 * '''Interpreter:''' whatever interpreter you wish to use. The default is for a shell script
 * '''Code:''' the actual code which will gather the information you want plotted. We will talk more about this later
 * '''User:''' this selects the Linux user the script will run as on the client machine. Depending on what you is being plotted, you may need an user with specific privileges
 * '''Y-axis title:''' the title of the "Y" (vertical) axis of the graph. This should be the name of whatever you are plotting
 * '''Tags''' or '''All computers:''' this selects which machines will receive this graph script and run it. You can select '''All computers''', which covers all the current and future computers you might have added to Landscape, or some specific tag you already have attached to the computers you want. If left blank, the graph script will not be sent to any computer.

Once you click on "Save", things will start happening. The graph script will be sent to the computers and after a while, typically half an hour, data will start showing up in the Monitoring section of Landscape.

 {i} All custom graphs scripts are scheduled to run every 5min on the client computers.

== Custom Graph script requirements ==
A Custom Graph script has certain requirements that need to be fulfilled in order for Landscape to be able to use it as a data source for a monitoring graph:
 * it must output a single numeric value, integer or floating point, positive or negative
 * it must exit with exit code zero. Any other exit code is treated as an error
 * the number must be written to stdout (standard output). For example, a simple `echo` command
 * if there is output written to stderr (standard error), the run is considered a failure and no data will be plotted regardless of what was written to stdout
 * the script must not take longer than 10s to complete
Here is a simple example that shows how to plot the current load average:

cat /proc/loadavg | cut -d " " -f 1

More complicated graphs can also be created. For example, here is one to plot the 5min average network traffic of the "eth0" interface. This is a bit trickier because we need to store the previous value in order to calculate the average:
function calc() {
    echo "scale=2; $1" | bc

interval=$((5 * 60))
[ -f "$oldfile" ] && old=`cat $oldfile`

curr=`grep $interface /proc/net/dev | awk -F" " '{print $1}'|cut -d : -f 2`

if [ -z "$old" ]; then
echo $curr > $oldfile
calc "($curr-$old)/$interval"

== Other Custom Graphs Examples ==
Please see the [[/Examples|examples]] page for other sample scripts.

= Checking out the graph =
To see the newly created custom graph, select the computers to which the graph was sent and click on "Monitoring" in the bottom toolbar.

There is a new header called "Custom Graphs" right at the top. If you click on it, the newly created graph will be there. As with the other default graphs, you can export its data as CSV and adjust the period it displays.

You may need to wait a bit before actually seeing any data being plotted, because the script runs every 5min.

= Custom Graphs errors =
It's possible a custom graph script could fail to execute. If that happens, the full error message is reported back to the Landscape server and shown to the administrator both in the Custom Graph page and in the Monitoring one.

Here is an example of a graph which has errors:


We can see the exact error message by clicking on the "errors" link:


In this case, it was a simple syntax error in the shell script.