Help Docs
Release Notes
Subscribe to release notes

Subscribe By RSS
Subscribe By Email

How to Debug Your Groovy Script

When you create an embedded Groovy script in your LogicMonitor account, keep in mind that it will be run inside the same JVM as your Collector. The guidelines are as follows:

  • Scripts are meant to be light-weight.
  • When integrated into a Datasource, they need to execute within 1 minute.
  • They also must fit within the memory resources of the Collector JVM.
  • Scripts with errors can interfere with the collector's stability.

If the script you are developing may require iterations to get it working, we recommend that you set up a sandbox environment for debugging. By installing a new collector that you use just for datasource development and script debugging, you will have the room to develop code and see how it interacts with your collector.

Using the Eclipse Java/Groovy IDE

Refer to the following to use Eclipse with the Collector Java/Groovy libraries.

Using the Collector Debug Window

A groovy script within a LogicMonitor Datasource will run directly on the Collector machine, using the version of Java and Groovy provided in that environment. To run in this very same environment, we have provided a built-in command !groovy in the Collector debug window.

Step 1. Go to the Setting tab -> Collectors

Step 2. Click the wrench icon of the collector (ideally start with your sandbox collector), and choose "Run debug command ..."

Acess Collector Debug Window
Step 3. Enter !groovy as shown below:

Step 4. A dialog with a big text edit box will pop up. Please edit your code there, then click "Submit"

Step 5. The collector will execute the script and show the return value and output in the debug window.

You can repeat steps 3 through 6 until you get the script right. After you finish debugging the script, there are two ways to make a copy of it:

  1. Copy and paste the source code from the edit box
  2. Copy the auto-generated file /tmp/test.groovy which contains this same code

Testing your script in a Datasource

The following explains how to create a datasource to test your script using your sandbox collector.

Step 1Create a new datasource with the desired name, group and polling interval. Then set its Collector method to 'script' as shown below. In our example, we named our datasource 'GroovyTest' and left the Collect every (polling interval) at the default setting of 3 minutes. We also entered 'JVM' for the Group to help keep our datasources organized.

Groovy Test datasource
Step 2. Choose a host/device that is monitored by your sandbox collector. Configure your datasource to match this host/device using the Applies To function wizard. The function system.displayname == "finance" matches the host that is monitored by the sandbox collector in our example:

Show Collector Hosts
If you don't have anything monitored by your sandbox collector, first add a host/device.

Step 3. Set the Script Type to 'Embedded groovy code' as shown:

Groovy Test upload script
Then enter your code in the datasource Groovy Script field. In our example, we wrote a minimal script that just prints the number "3" as shown above.

Step 4. Select the 'Add Normal datapoint' button, and choose "execution time of script in milliseconds" for the source of the datapoint as follows:

Groovy script datapoing response time
In our example, we named this datapoint ElapseTime. These datapoint source options can provide helpful feedback to see how your script is running. If your script uses exit codes, add another datapoint to monitor this return value. You can also monitor the content of standard output if your script prints values. Since our example script does print a value, we added a datapoint named Three to capture this output as well:

Groovy Test datapoints
Step 5. Once you have created a datasource and associated it to a host/device (monitored by your sandbox collector), you can check to see if it is executing properly.

From the Device Tree

Select your host/device on the Devices tab. After the polling interval completes, you should start seeing data on the graph for your new datasource. In our example, the graph for the instance of our 'GroovyTest' datasource was as follows:

Groovy Test device graph
As you can see above, we are getting valid numbers back for both datapoints. Since we wrote a one-line script, the ElapseTime rounds down to 0 milliseconds.

From the Settings Tab

Go to the Setting tab -> Collectors, click the wrench icon of your sandbox collector, and select 'Check collector events...' as shown:

Check Collector Events
If everything is running fine, you won't see any recent messages in the event log. In our example, we added a host named "finance" to be monitored from our sandbox collector. The most recent event in our log (dated 3/5/15 at 15:01:31) had to do with the default datasources that applied to that host:

Check Collector Events Log

Datasource Script with Syntax Error Example

Now that you have seen an example of a script datasource working properly, how about what happens when we introduce a syntax error? We modified our 'GroovyTest' datasource by adding an extra line as follows:

Groovy Test script syntax error
After pressing 'Submit' to update our datasource, our GroovyTest instance stops getting consistent values. Checking the raw data for this instance, we see 'No Data' returned at the next polling interval:

Groovy test No data
Next we check the event log for our sandbox collector:

Check Collector Events syntax error
As we can see above, the event log now shows the result of attempting to run the script containing a syntax error. When looking at this event log, you can see if a script is causing the collector to have issues running consistently.

Another symptom to watch out for is if you see the "Agent is restarted" description repeating every few minutes. A script datasource can crash the collector, causing it to restart every polling cycle. If you see a repeating crash/restart behavior, disable the datasource (i.e., comment out its Applies To function) until you have a fix for your script.