Welcome to part 2 of my series on Foglight customisation. In this series we’re going to learn how to create our own models, dashboards, functions and lots of other bits and pieces. The example project we’re using to do this is a Todo list application. The usefulness of a Todo list in Foglight is left as an exercise for the reader (good luck with that).
Concept
Our Todo list application is going to be a simple beast, with one list for everyone, holding simple details such as task name, description, due date, and status. Although this might seem a little too simplistic it will let us create a nice dashboard and a couple of rules without getting too drowned in modelling.
Models in Foglight
Foglight is different to most monitoring tools, the data we collect is held in object-oriented models rather than flat tables. What does that mean? Well it allows us to use Foglight for modelling any kind of data, link data types together in a hierarchy, and quickly extend it’s capabilities with very little effort .
The general method for creating your own Foglight extensions is to decide on the data structure & create your definition, populate the model using agents (or in this case, scripts) and then build dashboards and rules against the data. In this post we’ll be covering the first 2 steps.
Where to work
Because Foglight has been designed to be quickly extended and customised by our users the tools you need are already available to you. Today, we’ll be using the Add Topology Type dashboard (administration -> data -> Add Topology Type) to import our data types, and the Script Editor (Administration -> Tooling -> Script Editor) to populate them and look at the data.
Files
As I mentioned earlier, the first thing we need to do is create the data model for the information we want to store. The fields we’ll be storing for our Todo items are
Name
Description
Completed (a boolean value)
Due date (a date value we can use in rules)
Foglight models are written in xml, and the type definition will look like this:
Note that I’ve added an identity field to the task name, this will define this object in the model, think of it as a primary key.
The above definition will allow us to create “task” objects, but since these don’t belong to anything else they would be orphaned objects, what we need to do is create a tasks model in Foglight to group them all together:
As you can see, I’ve created a TasksModel object, which is made up of many “task” objects. Notice that this new type extends CollectionModelRoot. This is a special class in Foglight that is used to anchor all the model roots together in the data browser. This is an important step because now we can get to our data easily though the data browser in model roots, and use much simpler queries in our dashboards.
So now we’ve got all the pieces together (you can get the complete text here) we can go to the Add Topology Type dashboard to import. As you can see you can either upload a file, or type (copy/paste) your own definition in. You can also use this dashboard to check that your dashboard is valid xml.
So once you’ve uploaded or copied in your definition, your new task list model is ready to go, all we need to do now is populate it with some data.
Population
Typically Foglight models are populated by data sent in by agents. Since we will be populating our Todo list using a dashboard we need some scripts to create our objects for us. Luckily, Foglight has many API’s and functions available to us to help out. For this section, we’ll be working in the script editor.
The magic function we’ll be using to create or edit our objects is:
def createOrUpdateObject(typeName, propertyValues) {
topSvc = server.TopologyService;
def type = topSvc.getType(typeName);
objShell = topSvc.getObjectShell(type);
propertyValues.each ({propertyName, propertyValue ->
def prop = type.getProperty(propertyName);
if (!prop.isMany()) {
objShell.set(prop, propertyValue);
}
else if (propertyValue instanceof Collection) {
objShell.getList(prop).addAll(propertyValue);
}
else {
objShell.getList(prop).add(propertyValue);
}
});
return topSvc.mergeData(objShell);
}
This function is written in groovy (the scripting language that is built into Foglight). If you’re not the programming type, then it’s probably enough for you to know that this function lets us create objects using syntax like this:
def Task1 = createOrUpdateObject("task", [name:"taskName", taskDescription:"taskDesc", completed:"taskCompleted",due:"taskDue"]);
We create a task object and tell Foglight the values for the parameters (you would only need to change the sections in double quotes). If you’d like to know more, I’d recommend you read the excellent post by the functions original author (see further reading below).
So to create some tasks in our model, paste the function above into the script editor and add these two lines below to create a task and update the taskModel with the new object, and click execute.
def Task1 = createOrUpdateObject("task", [name:"my First Task", taskDescription:"make a cool model", completed:"false",due:"19/10/2011"]);
taskModel = createOrUpdateObject("TasksModel", [name:"TasksModel", Tasks:[Task1]]);
To find your new objects, find “task” in the drop down at the top of the screen, or type “task” into the query box, and hit the button. All instances of the task object will appear below. Clicking on one loads the object into the script editor
As you can see our object has more properties than we declared, this is because our object is an extension of the TopologyObject class, and so we inherit the properties of that class.
Summary
In this post we’ve built a model for our todo list and written a quick script to create our objects. We’ve run through everything at quite a reckless pace in an effort to show some value quickly and not get us lost in the theory. I’d strongly suggest you follow the link in further reading if find yourself interested in the mechanics of what we’ve just done.
Tune in for the next exciting episode, where we will start to put together a dashboard to display our tasks and build on the script above to build it into a dashboard form.
Further Reading
As mentioned above, Geoff Vona has written an excellent article about the theory of models in Foglight, and its him I borrowed (stole) the create objects function from. So if this blog has been interesting, I strongly urge you to read the original post as it covers the principles here in much greater depth. http://foglight.org/Blog/tabid/55/EntryID/133/Default.aspx
This post is the first part of a series of tutorials for creating Foglight models, dashboards, and custom cartridges. For the rest of this series please visit the fglTasks page, you can find a complete list of my foglight posts here