Written by: Foglight R&D Team
3/11/2009 6:57 AM

Hello again, this is Geoff Vona. I am the director of development for Foglight core. I've been working on Foglight in various capacities for the last 5 years.

One of the most remarkable things about Foglight 5 is its scripting capabilities. In this Dark Corners entry, we'll explore the degree to which scripting is incorporated in Foglight 5.

Motivation

Learn about scripting in order to

1. Automate or simplify complex administrative tasks.
2. Perform administrative tasks that aren't available in the user interface.
3. Create dashboards that take action.
4. Create more complex monitoring policies (rules, derived metrics).
5. Add standard functions to the system, for example statistical analysis functions.

Background and Architecture

Scripting isn't just a feature of Foglight 5. Foglight 5 has been built around a scripting core. This means that rather than an add-on, scripting tends to be the standard way of doing things with Foglight. For example, rules and derived metrics are all executed using scripts that run inside the server. Actions taken from the user interface are done using server scripts. Data transformation is done using server scripts.

We decided to make scripting a core function of Foglight by embedding a Groovy scripting engine inside the Foglight server. Scripting is a core service, accessible by any other service in Foglight.

About Groovy Groovy is a new language that runs on standard Java Virtual Machines. You can learn more about it here

While this is a powerful technique, obviously there are concerns. Allowing universal script access to all of the Foglight internals was not an option. In order to make sure that script actions are controlled, we defined a subset of the available functions called the Service Layer. The service layer functions are the public API to Foglight. All calls to the service layer must be properly authenticated and authorized. These calls are audited as well.

As shown above, the service layer is accessed by any script including the user interface. Any action performed by the user interface is actually performed by a Groovy script embedded in a script function or task. This is how the dashboarding UI is able to perform code-like actions. Yes, it is the secret sauce. :)

Running Scripts

Scripts are run in a number of ways:

• By executing a task in the user interface. For example, hitting an option in the Service Builder executes Groovy code to do things like add a new category
• By creating a derived metric or rule. The expressions inside derived metrics and rules can be simple checks like "A > 12" or "return A * 2;". However, the expression is actually a Groovy script. This script can be arbitrarily complex. A good example of a complex script is the availability derived metric.
• By executing a function. Function calls that are made inside derived metrics, rules or other Groovy scripts are actually Groovy scripts. For example, the avg() function is a Groovy function written by core development. It is possible to add new functions to Foglight in a .car file. Have a look at the Core-Script*.car file in FGLHOME/cartridge - it contains all the default script functions shipped with Foglight.

It is possible to run scripts directly. There are two ways to do this:

1. Using the Script Editor in the user interface
2. Using the command line.

Of course, Foglight scripts are not the same as pure Groovy scripts. There are two special objects to be noted:

• server: The server objects refers to the Foglight server. All of the service layer APIs are accessed through the server object.
• scope: If a script is bound to a topology object, then the scope variable refers to that object. This is used in rules and derived metrics. This isn't a mandatory object.

Running Scripts with the Script Editor

Select Script Editor on the Administration home page.

This will take you to the script editor.

The Script Editor has two modes of operation: global, and bound to an object. The easiest way to use it is to simply type or paste in your script in the dialog box at bottom and hit Run. This will run your script "globally", meaning not bound to any particular object. However, note that any "print" output will be sent to the log files.

In this example, a simple script to create a Host object instance called "monkey" was run. Note that the object is returned and linked at the bottom.

The second way to run a script is to select a specific object. Selecting an object will run the script using that object as its scope. This is most useful when testing rule or derived metric expressions.

To choose an object, you can either choose an instance using the pulldown

Or specify a query to choose a type set

Notice that running List Instances will actually specify a query. So choosing "Host" from the pulldown is the same as specifying "Host" in the query. These queries are the same as scoping queries, so this is a good way to test a scoping query to see what it returns.

In either case, selecting one of the returned instances will select that instance as the scoping object for the scrip. In script terms, this is the same as setting the value of the scope object.

Running a script bound to an object is really only important when creating rules or derived metrics. Most of the time it is fine to simply drop your script into the editor and hit Run.

Running Scripts on the Command Line

Only global scripts can be run on the command line. The syntax is pretty simple:

fglcmd -usr foglight -pwd foglight -srv YOURSERVER -cmd script:run -f c:\Work\Groovy\makeNewHost.groovy

Whatever is returned in the script editor will also be dumped out on the command line:

[foglight-5:Host:3b0578ef-a045-4321-8175-d032ab6b5b2f:1 datasource=foglight-5:foglight-5]

Any print messages will be sent to the log.

Accessing the Service Layer

The full set of service layer calls is documented inside the server itself. To access it, simply hit the information icon next to "Script":

There is also documentation and help wound into the script editor using the help() function. You can run help(server) to get a list of all the services accessible from the server object. The objects are listed in the script editor - click on them to see the APIs.

You can also run help() on an object. For example, to get a list of methods in the TopologyService, run help(server.get("TopologyService")) as shown below:

Scripting Example: Creating a Host

This script creates a host object. Let's take a closer look at how this is done:

topSrv = server.get("TopologyService");
shells = [];
host = topSrv.getObjectShell(topSrv.getType("Host"));
host.set("name", "monkey2");
shells.add(host)
objects = topSrv.mergeData(shells);

The first line uses the server object to retrieve a reference to the TopologyService.

The second line creates an empty array of any type. We're going to use this array to contain some objects that we're going to build.

The third line is key. It asks the Topology Service to create an "object shell" for an object of type Host. What we've done is asked for a template for an object of type Host. Since it is a template, we have to fill in the key properties. A Host object has one identity property - the name of the Host. We set that property on line four. (Determining that Host has a single identity property is a topic for another Dark Corner blog. :) )

Lines five and six bundle up the list of objects and send them to the Topology Service. The Topology Service merges the templates in and returns all the instances that were created.

You should be able to reuse this pattern to create other objects.

Some Cool Scripts

The great thing about using scripts as an extension mechanism is that it is easy to get started. Ideally, everyone will review a Groovy syntax guide, then read all the Service Layer documentation, plus the administration guide to see what Foglight extensions have been made to Groovy. Nobody has time for that kind of thing. Instead, create a library of helpful scripts, and start cutting-and-pasting. Learning by example will get you started much more quickly.

Script Examples Modify Your Foglight Some scripts are included in this blog. What the scripts do might be helpful for you. Keep in mind that these scripts do modify the Foglight environment. Please do not run these scripts on production Foglight servers without first making sure you know what is going to happen. You don't want your script learning to result in a problem!

A few tips to remember about Foglight scripts:

• Groovy is a loosely-typed object-oriented script language. It is similar to Java in general syntax, which means people with a C, C++ or C# background shouldn't have too much trouble.
• Remember to look at the service layer documentation to see what you can call. As with most languages, the most important knowledge you need is not syntax, but APIs.
• The server object is your gateway to the internal services
• Use the script editor to try out your scripts.
• Do you experimentation on a local instance. If you need to do script development against a production server, try creating a local federation instance. That way you'll have all the objects and data you need, but if you mess something up you can just start over. :)

delNormalAction.groovy.

This script deletes all actions bound to Normal severity. By default many Foglight rules have actions bound to the transition to the Normal state. This can lead to a lot of chatter as Foglight cheerfully sends you e-mail to tell you that your CPU utilization is normal again.

Keep in mind that this script permanently deletes the normal actions. Be careful.

import com.quest.nitro.service.sl.interfaces.rule.*;

def ruleService = server.get("RuleService");
for (rule in ruleService.getAllRules()) {
    try {
        print rule.getClass();
        print rule.getName(); 
        if (rule instanceof SeverityFamilyRule) {
	  SeverityFamilyRule sevRule = (SeverityFamilyRule)rule;
	  sevRule.getNormal().setFireActionMappings(new HashSet());
	  sevRule.getNormal().setExitActionMappings(new HashSet());
	  ruleService.saveRule(rule);
          print "Done Action DELETE for " + rule.getName();
        }
	else if (rule instanceof SimpleRule) {
	  SimpleRule simRule = (SimpleRule)rule;
	  simpleRule.getFire().setFireActionMappings(new HashSet());
	  simpleRule.getFire().setExitActionMappings(new HashSet());
	  ruleService.saveRule(rule);
          print "Done Action DELETE for " + rule.getName();
	}
    } catch (RuleNotFoundException e) {
    } catch (ClassCastException cce) {
	print cce;
    }
}

disableAllRules.groovy

This script will disable all rules in Foglight.

You should be able to re-enable by reversing the sense of the script. However, if you had some rules disabled before you run this script, you'll need to manually disable them after re-enabling.

import com.quest.nitro.service.sl.interfaces.rule.*;

def ruleService = server.get("RuleService");
for (rule in ruleService.getAllRules()) {
    try {
        print rule.getClass();
        print rule.getName(); 
	rule.setSuspended(true);
        ruleService.saveRule(rule);
        print "Done DISABLE for " + rule.getName();
    } 
    catch (ClassCastException cce) {
	print cce;
    }
}

serviceIntrospection.groovy

Given a service object as scope, this script will print out all the contents of the service. This is not all that useful, but it does show how to use a script to walk the data tree.

This script is view-only. It does not make any changes.

//Scope must be FSMServiceRoot
serviceList = scope.get("services")
for (service in serviceList) {
  objList = service.get("definition")
  print "Service " + service.get("name") + " contains " + objList.size() + " objects.\n"
}

getMatchingAuditInfo.groovy

This script returns all audit log entries that match a provided service name and operation. This can be handy for finding out who modified a rule, and when. Then you can track them down. :)

This script is view-only. It does not make any changes.

import java.util.Date;

def getMatchingAuditInfo = { serviceName, operationString ->
	message = "Audit entries matching " + serviceName + ":" + operationString + ":
";
	aus = server.get("AuditingService");
	aus.getAuditLog(new Date(0), new Date()).each() { entry ->
		if (entry.getServiceName().equals(serviceName) &&
		    entry.getName().contains(operationString)) {
			message += "" + entry.getServiceName() + ":" + entry.getOperationName() + "," + entry.getName() + " by " + entry.getUserName() + "
";
	        }
	}
	message
}
getMatchingAuditInfo.call("RuleService", "Info");

createAnyAgent.groovy

This script creates an agent instance. This is similar to the create host script from earlier in this article. It creates an instance of any agent. This can be handy for testing or for UI development if you don't have an agent working yet.

The agent ID needs to be unique or this script won't work. You need to change the agent name and ID every time this runs. Note also that this script creates a test host that contains the agent.

topSrv = server.get("TopologyService");
shells = [];
host = topSrv.getObjectShell(topSrv.getType("F4Host"));
host.set("name", "myTestAgent");
shells.add(host);

f4model = topSrv.getObjectShell(topSrv.getType("Foglight4Model"));
f4model.set("name", "Foglight4Model");
f4model.getList("IPMap").add(host);
shells.add(f4model);

agent = topSrv.getObjectShell(topSrv.getType("SQLServerAgent"));
agent.set("host", host);
agent.set("pluginName", "SQLServerAgent");
agent.set("agentInstance", "0");
agent.set("name", "SQLServerAgent");
agent.set("agentID", 72);
shells.add(agent);

host.getList("agents").add(agent)

// Merge the data contained in the shells into the topology
objects = topSrv.mergeData(shells);

Trackback Print

Location: Blogs Foglight Dark Corners