Foglight 6.0.0 - Administration and Configuration Guide

Building Script Agents

A script agent is a special type of agent that is used to execute a script on a monitored host. The script can be in any language, but it must be written in a way that provides specifically formatted output to STDOUT. Creating script agents is the easiest mechanism for bringing custom data into Foglight®. Once the script agent data are in the system, Foglight treats them the same way as any other data collected by any other agent type. Data collected by script agents can then be used in rules, derived metrics, dashboards, and other Foglight components.

Custom script agents interact with the Agent Manager through the Foglight collector executable. Script-based custom agents output data to standard output (STDOUT). The Foglight collector reads this data and retransmits it to the Agent Manager.

The output format is straightforward:

There are two types of scripts: Type 1 and Type 2 scripts. Foglight calls Type 1 scripts every time they need to collect data. In Type 1 scripts, the collector executes the script, then stands by for a time period specified in the agent properties. When the standby period ends, the collector becomes active and reruns the script. Type 1 scripts are useful for collecting data that does not require calculations from multiple collection periods. Sample Type 1 scripts are available in the server installation directory: Type1_NT_Script.bat (Windows) and Type1_Unix_Script.sh (Unix).

Type 2 scripts control their own collection frequency cycle. In Type 2 scripts, the Foglight collector executes the script and remains open. The script controls the standby period instead of the agent properties. Type 2 scripts perform data calculations before the data enters the database and measure changes between collection periods. A sample Windows Type 2 script is available in the server installation directory: Type2_NT_Script.bat.

Type 2 scripts are more complex because the script writer must handle looping and honor the sampling interval from the server. This might be necessary if the length of the loop is important for calculating rates. For the purposes of getting started, use Type 1. This will minimize the complexity. Switch to Type 2 once you have a reason for hand-coding the loop.

You can use the Build Script Agent dashboard to upload custom agent script to the server. To access this dashboard, from the navigation panel, click Dashboards > Administration > Tooling > Script Agent Builder.

Using the Query Language

The Query Service gives users and Management Server services a way to make queries about topology objects and monitored metrics using the Foglight query language. Query language is used in rule conditions and derived metric expressions.

Typically, when working with rules and derived metrics, you first write a topology query to scope on a specific subset of the topology model, then write a script that performs a mathematical operation against that data subset. Metric queries retrieve metric values from one or more objects over a specified period of time. They cannot be used to set the scope of rules and derivations, but rather to query the database for the value of a particular metric over a specific period of time.

Retrieving Data with the REST API

The Foglight REST API is an application programming interface (API) that uses HTTP requests to GET, PUT, POST, and DELETE data. REST APIs are protected by authentications, which means you need retrieve an access token before using REST APIs. For more information about the Foglight REST API, refer to the Foglight REST API Reference Guide.

Retrieving Data with Scripts and Queries

In some cases, you may be required to run scripts, at the request of Quest Support, or for other maintenance functions. You can use the Script Console dashboard to test sample scripts. This dashboard is accessible to users with the Administrator and Cartridge Developer roles only. To access this dashboard, from the navigation panel, click Dashboards > Administration > Tooling > Script Console.