Foglight for Databases 7.3.0 - Administration and Configuration Guide

Merging Host Objects

Merging two or more hosts refers to the ability to consolidate data for those host objects using host aliasing rules.A host aliasing rule includes one or more property matching filters that select the topology objects that are to be merged, along with the logical definition of the merge operation. Property matching filters can only reference a subset of the entire property set for a topology type such as String or Boolean properties.

Simple merging rules contain one stand-alone rule. They are used to merge one or more host objects, or to rename a host object in the model. Advanced merging rules consist of a group of individual rules that are executed in pre-defined order. They can merge one or more topology objects. For example, merging two agent instances involves a rule for transforming the instance name and another one for merging the two instances.

Merging rules are useful in situations when a host name changes and there is a need to consolidate the data under a single host object. Consider for example an Agent Manager installed on a host whose name is Toronto123. The host reports into Foglight as Toronto123, which creates a new Host object, Toronto123. The system administrator modifies the host’s configuration which causes Toronto123 to start reporting itself using its IP address, 10.1.234.56. When the Agent Manager collects information from the newly-renamed host, a new Host object is created on the server, with the name 10.1.234.56. After noticing the problem, the Foglight administrator solves it by creating an alias for the host, mapping it to its original name, Toronto123.

Use the Manage Host Aliasing Rules dashboard to create host aliasing rules or to manage the existing ones. To access this dashboard, from the navigation panel, click Dashboards > Administration > Tooling > Manage Host Aliasing Rules.

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.