Foglight for Databases 5.9.3 - Administration and Configuration Guide

<property name="MyDomainName" type="String"

<property name="AgentName" type="String"

</type>

<property name="MyAnnotations" type="String"

Manage Host Aliasing Rules

</type>

</types>

Validate the topology definition by clicking Validate.

The Alert message box appears, indicating that the topology definition is valid.


	NOTE: The validation process is limited. It validates the format of the type definition. Your XML may appear to be valid and still fail on import due to other errors such as naming conventions.

Close Click Import Topology.

The Alert message box opens, this time indicating that the topology import was successful.

Online-Only Topics

Learn more about:

•

•

Build Script Agents

•

Script Console

•

Query Language

Manage Host Aliasing Rules

Changing the priorities of host aliasing rules

Each host aliasing rule has a priority assigned to it. The Management Server processes host aliasing rules in the order of their priority, with the rules with higher priority being executed first.

The rule priority is specified as the final step. By default, Foglight assigns the lowest priority to a new rule. This value can be changed during or after the rule creation. This topic explains the process of changing the priority of the existing rules in the Manage Host Aliasing Rules dashboard.

Simple merging rules can consist of a single rule. Advanced merging rules consist of a group of individual rules that are executed in a pre-defined order. It is possible to change the group priority, but not the priority of an indi vidual rule within the group. For example, an advanced rule has the group priority of 4.0, and it consists of two individual rules, with their priorities set to 4.1 and 4.2 by default. While the priority of the rules within the group cannot be changed, increasing the group priority to 3.0 automatically increases the priority of the rules it contains to 3.1 and 3.2.

Figure 97. The Host Aliasing dashboard, showing the priority of various rule types.

Additionally, changing the priority of a rule can affect the order in which other rules are executed, as illustrated in the following table.

Table 69. An illustration of how changing the priority of a rule can affect rule execution order.
Rule	Priority before the change	Change	Priority after the change
A	2.0	None	2.0
B	3.0	Decrease by 1.0	4.0
C	4.0	None	3.0


	NOTE: In the above example, as the priority of rule B decreases to 4.0, the priority of rule C increases from 4.0 (the value now assigned to rule B) to 3.0.

To change the priority of a host aliasing rule:

On the navigation panel, under Dashboards, click Administration > Tooling > Manage Host Aliasing Rules.

On the Manage Host Aliasing Rules dashboard, locate the row containing the simple or advanced rule whose priority you want to edit.


	IMPORTANT: You can only edit the priority of a simple merging rule or an advanced merging rule consisting of individual rules. The priorities of individual rules with a group (advanced merging rules) are assigned automatically and as such cannot be changed. A priority action icon appears on the right of an editable priority . Clicking the Priority column of a rule that is a component of an advanced merging rule shows the following message: You cannot change the priority of a rule.

In that row, click the Priority column.

A dwell appears, allowing you to specify the rule priority.

In the dwell, change the rule priority, as required.


	IMPORTANT: Changing a rule priority can affect the order in which other rules are executed. Specifying a priority value that is already associated with another rule can change the priority of that rule, moving it up or down the priority list.

•

Use the arrow buttons to increase

or decrease

the priority indicator. Clicking an arrow button once changes the priority indicator by one (1.0).

•

In the Custom Priority box, type the rule priority, and click Apply.


	IMPORTANT: This value must be a valid integer number.

The dwell closes, and the list of rules in the Manage Host Aliasing dashboard refreshes, showing the newly-updated rule priority.

Renaming host aliasing rules

Simple and advanced merging rules can have their names changed, as well as the individual rules that are a part of a group (advanced merging rules).

To rename a host aliasing rule:

On the navigation panel, under Dashboards, click Administration > Tooling > Manage Host Aliasing Rules.

On the Manage Host Aliasing Rules dashboard, locate the row containing the host aliasing rule that you want to rename.

In that row, click the Rename column

The Change Rule Display Name Form dialog box appears.

Specify the new rule name.

In the Change Rule Display Name Form dialog box, in the New Name box, type the new rule name as you want it to appear on the Manage Host Aliasing dashboard, and click Rename.

The Change Rule Display Name Form dialog box closes, and the list of rules in the Manage Host Aliasing dashboard refreshes, showing the newly-updated rule name.

Deleting host aliasing rules

Simple and advanced merging rules can be deleted, as well as individual rules that are a part of a group (advanced merging rules).

To delete a host aliasing rule:

On the navigation panel, under Dashboards, click Administration > Tooling > Manage Host Aliasing Rules.

On the Manage Host Aliasing Rules dashboard, locate the row containing the host aliasing rule that you want to delete.

Mark the rule for deletion.

In that row, select the check box on the left of the rule name.

Remove the rule marked for deletion.

At the top of the rule list, click Delete.

The Confirm Delete dialog box appears.

Confirm the delete operation.

In the Confirm Delete dialog box, click Yes.

The Confirm Delete dialog box closes, and the list of rules in the Manage Host Aliasing dashboard refreshes, no longer showing the newly-deleted rule.

Getting started: create host aliasing rules

Creating a host aliasing rule is the process of creating property matching filters that select one or more host objects, and specifying a logical definition of the merge operation to either merge existing objects, or to create new ones. This is useful in situations when the regular merging process does not have information to match data objects as they are collected.


	NOTE: Property matching filters can only reference a subset of the entire property set for a topology type such as String or Boolean properties. To see a full set of properties that are included in Host or other types of topology types, view the Schema Browser dashboard; for more information about this dashboard, see the Foglight User Guide.

The merging process is in effect only while the merging rules exist and are active while the data consolidation resulted from a merging rule is permanent. For example, creating a rule that merges a source host with a target host results in the source host’s data being consolidated with the target host’s data, which is not only reflected in the data collection model, but also in any dashboards that display host-related data such as the Agents dashboard. When the rule is deleted, the data collected from the source host before the rule deletion still appears as collected by the target host, while the data collected after the deletion is stored under each individual host. For more information on how to delete rules, see Deleting host aliasing rules.


	IMPORTANT: Creating new topology objects does not delete any existing objects from the data model.

Based on their complexity, there are two types of host aliasing rules:

•

Rules for merging hosts

•

Rules for renaming or changing of host object properties

The button on the Manage Host Aliasing Rules dashboard invokes the New Merging Rule Introduction dialog box that shows three options, one for each rule type.

Figure 98. The New Merging Rule Introduction dialog box offers workflows for creating rules.

Choosing each option starts a unique flow. Its complexity depends on the rule type. For example, if you choose to merge one host object with another, you specify the names of the host object while the process of merging two or more topology objects which results in a simple rule. Merging two hosts based on a property matching logic requires you to specify a more complex property matching filter, and results in an advanced rule that contains two or more individual rules.

To create a host aliasing rule:

On the navigation panel, under Dashboards, click Administration > Tooling > Manage Host Aliasing Rules.

On the Manage Host Aliasing Rules dashboard, click

The New Merging Rule Introduction dialog box appears.

Choose the type of the rule that you want to create by clicking one of the following options in the New Merging Rule Introduction dialog box:

Table 70. Options available in the Merging Rule Introduction dialog box.
To	Click	For more information, see
Merge two host objects	Create a focused rule for a single host	Merging host objects
Change the name or another property of one or more host objects	Create a broad rule which works with many hosts	Edit host object properties
NOTE: Choosing this option results in a creation of one or more objects. It does not delete any of the existing objects whose properties are about to be changed.

When you make a selection, the New Merging Rule Introduction dialog box closes and the Host Aliasing dialog box appears. The appearance of the Host Aliasing dialog box depends on the rule type selection.

Merging host objects

Merging one host object with another consolidates the data collected by a source host under a target host. This is useful in situations when the regular merging process does not have information to match data objects as they are collected. This process involves specifying property matching filters to select the source and target hosts.

NOTE: Property matching filters can only reference a subset of topology type properties, such as String or Boolean properties. To see a full set of properties that come with the Host type, use the Schema Browser dashboard.

The merging process is in effect only while the merging rules exist and are active while the resulted data consolidation is permanent even if the merging rule that caused it is inactive or deleted.

Selecting the Create a focused rule for a single host option in the New Merging Rule Introduction dialog box invokes the Specify Target Host workflow for creating a host merging rule.

Figure 99. The Specify Target Host workflow guides you through the process.

To merge host objects:


	NOTE: This procedure continues from Getting started: create host aliasing rules.

Specify a target host object using a particular property value.

Ensure that the property you want to use for matching the host is selected. By default, in the Host Aliasing dialog box, the name property appears selected.

The Host Aliasing dialog box, with the Name property selected.

Optional — To use a different property, in the Host Aliasing dialog box, click Name: String. In the list that appears, click the row containing the desired property.

Select a property from the list.


	IMPORTANT: The list that appears shows only a subset of the entire property set for the selected object type. This is because property matching filters can only reference certain types of properties such as String or Boolean properties. To see a full set of properties that exist in the Host type, view the Schema Browser dashboard; for more information about this dashboard, see the Foglight User Guide.


	TIP: To look for a particular property, use the search filter at the top of the list.

The property list closes and the newly-selected property name and its data type appear in the Host Aliasing dialog box. For example, selecting the domainName property shows Domain Name: String in the dialog box.

The same property you select here to specify the target host is used to match the source host in Step 2.

Specify the value of the selected property that you want to use as a search filter.

In the Host Aliasing dialog box, in the box on the left of the Look up button, type the value that you want to search for in the host objects that exist in the data collection model. For example, to look for a host object whose name is mytargethost.mydomain.com, with the name property selected (Name: String, see Step a), type mytargethost.mydomain.com into the box.

Optional — To choose from the values of the selected property in the existing host objects, click Look up. In the Host Finder dialog box that appears, select the row containing the desired value, followed by closing the dialog box.

The Host Finder dialog box allows you to select a value for a chosen property.


	TIP: To look for a particular property value, use the search filter at the top of the list.

Close the Host Finder dialog box. The Host Aliasing dialog box refreshes.

In the Host Aliasing dialog box, click Next.

The Specify Source Host page contains the information about the target host.


	TIP: To select a different target host, click Previous to return to the Specify Target Host page.

Specify a source host object using the host object property you selected in Step 1, sub-Step a.

In the Host Aliasing dialog box, on the Specify Source Host page, type the value that you want to search for in the host objects that exist in the data collection model. For example, to look for a host object whose name is mysourcehost.mydomain.com, with the name property selected (Name: String, see Step 1, sub-Step a), type mysourcehost.mydomain.com into the box.

Optional — To choose from existing property values, click Look up. In the Host Finder dialog box that appears, select the row containing the desired value, followed by closing the dialog box.


	TIP: To look for a particular property value, use the search filter at the top of the list.

Click Close to close the Host Finder dialog box. The Host Aliasing dialog box refreshes.

In the Host Aliasing dialog box, click Next. The Host Aliasing dialog box refreshes.

The Manage Host Aliasing Rules dashboard refreshes, showing the newly-added rule.

The Summary page contains information about the source and target hosts. It also allows you to change the rule priority and to instruct Foglight to stop processing any rules with a lower priority when this rule executes (see the Stop processing lower priority rules when successful check box, disabled by default). By default, this rule is placed at the bottom of the priority queue. For example, if there are six existing host aliasing rules, this rule is assigned the priority of seven ‘7’. You can also change the priority at a later time. For more information, see Changing the priorities of host aliasing rules.

Optional — To change the rule priority or prevent the processing of the rules with the lower priority, use the Priority box and Stop processing lower priority rules when successful check box, as required.


	TIP: To select a different source host, click Previous to return to the Specify Source Host page.

In the Summary page, review the overview of the merge process.


	TIP: To select different hosts, click Previous to return to a previous page, as required.

In the Host Aliasing dialog box, click Finish.

The Host Aliasing dialog box closes, and the Successful message box appears, indicating a success.

Click OK to close the message box.

Edit host object properties

Changing the name or another property of one or more host objects can be done using literal or regular expressions. This process involves creating filters, to select one or more hosts, and specifying an expression for replacing the property value.


	NOTE: Property matching filters can only reference a subset of the entire property set for a topology type such as String or Boolean properties. To see a full set of properties that are included in Host or other types of topology types, view the Schema Browser dashboard; for more information about this dashboard, see the Foglight User Guide.

Renaming host objects creates new host objects without deleting the original host object. When the rule is created, it instructs Foglight to consolidate any data collected from the renamed hosts under the newly-created host objects.


	IMPORTANT: The property changing process is in effect only while its rules exist and are active while the resulted data consolidation is permanent. For more information, see Getting started: create host aliasing rules.

Selecting the option Create a broad rule which works with many hosts in the New Merging Rule Introduction dialog box invokes the Specify Matching Parameters workflow for creating a rule that changes the names or other host properties. The Host Aliasing dialog box includes several options that simplify the process of renaming host properties.

Figure 100. The Specify Matching Parameters page in the Host Aliasing dialog box.

From there, specify the current and target names, and review the summary of the merge process.

Table 71. Select an option to proceed with specifying matching parameters.
To	Select this option and click Next	For instructions, see
Remove characters from the end of host names	Remove characters from the end of a host name	To remove characters from the end of host names:
Replace characters in host names	Replace characters in a host name	To replace characters in host names:
Use a regular expression to rename hosts	Use a regular expression to convert a host name	To use a regular expression to rename hosts:
Change other host properties	Merge hosts by a property other than name	To change host properties:

To remove characters from the end of host names:


	NOTE: This procedure continues from Getting started: create host aliasing rules.

In the Specify Matching Parameters page of the Host Aliasing dialog box, select the option Remove characters from the end of a host name, followed by clicking Next.

The Host Aliasing dialog box refreshes, showing the page Remove characters from the end of a host name.


	TIP: To use a different type of matching parameter, click Previous to return to the Specify Matching Parameters page.

Specify the characters that you want to remove from the end.

In the Host Aliasing dialog box, in the Host Names start with box, type a literal expression containing one or more starting characters of the host name.

Table 72. Example of literal expressions matching.
Host	Select this host?	Expression	Host Selected?
my_host_1.company_a.com	Yes	my_host	Yes
my_host_2.company_b.com	Yes		Yes
test_host_3.company_c.com	No		No
test_host_4.company_d.com	No		No

In the Host Aliasing dialog box, in the Host Names start with box, type a literal expression containing the characters that you want to remove from the host name.

Table 73. Example of literal expression matching for truncating.
Selected host	Truncate host name?	Expression	Host name truncated?
my_host_1.company_a.com	Yes	company_a.com	Yes
my_host_2.company_b.com	No	company_a.com	No

The Host Aliasing dialog box refreshes.

By default, this rule is placed at the bottom of the priority queue. For example, if there are seven existing host aliasing rules, this rule is assigned the priority of eight ‘8’. You can also change the priority at a later time. For more information, see Changing the priorities of host aliasing rules.

To change the rule priority or prevent the processing of the rules with the lower priority, use the Priority box and Stop processing lower priority rules when successful check box, as required.


	CAUTION: Host aliasing rules include a system-level rule, adjustHostName, that automatically restores host names if the entire domain name is removed. This rule is hidden and as such does not appear in the browser interface. The rule includes a default priority of one '1', while newly created rules have a default priority of two '2' or lower, causing adjustHostName to override the removal of domain names. For example, if you have a host called example.mydomain.com, and want to remove the domain name, .mydomain.com from that host name, adjustHostName reverts the removal of the domain name. To successfully remove the entire domain name from the host name, you must prevent adjustHostName from executing. This can be done by selecting the Stop processing lower priority rules when successful option.


	TIP: To use a different replacement text or to select different hosts, click Previous to return to the Remove Characters from the End of a Host Name page.

In the Host Aliasing dialog box, click Finish.

The Host Aliasing dialog box closes, and the Successful message box appears, indicating a success.

Click Ok to close the message box.

The Manage Host Aliasing Rules dashboard refreshes, showing the newly-added rule.

To replace characters in host names:


	NOTE: This procedure continues from Getting started: create host aliasing rules.

In the Specify Matching Parameters page of the Host Aliasing dialog box, select the option Replace characters in a host name, followed by clicking Next.

The Host Aliasing dialog box refreshes, showing the page Replace characters in a host name.


	TIP: To use a different type of matching parameter, click Previous to return to the Specify Matching Parameters page.

Specify the replacement text.

In the Host Aliasing dialog box, in the Find box, type a literal expression that you want to replace.

Table 74. Example of finding hosts with characters that you want to replace with a literal expression.
Host	Select this host?	Expression	Host Selected?
my_host_1.company_a.com	Yes	company_	Yes
my_host_2.company_b.com	Yes		Yes
test_host_3.domain_c.com	No		No
test_host_4.domain_d.com	No		No

Alternatively, to select all hosts, select Any host.

In the Host Aliasing dialog box, in the Replace With box, type a literal expression containing the characters that you want to use as the replacement text.

Table 75. Example of replacing characters with a literal expression.
Selected host	Replace characters in the host name?	Expression	Characters in the host name replaced?
my_host_1.company_a.com	Yes	my_company	Yes
my_host_2.company_b.com	Yes	my_company	Yes

The Host Aliasing dialog box refreshes.

The Manage Host Aliasing Rules dashboard refreshes, showing the newly-added rule.

The Summary page in the Host Aliasing dialog box describes the character renaming logic. It also allows you to change the rule priority and to instruct Foglight to stop processing any rules with a lower priority when this rule executes (see the Stop processing lower priority rules when successful check box, disabled by default). By default, this rule is placed at the bottom of the priority queue. For example, if there are seven existing host aliasing rules, this rule is assigned the priority of eight ‘8’. You can also change the priority at a later time. For more information, see Changing the priorities of host aliasing rules.


	TIP: To use a different type of matching parameter, click Previous to return to the Specify Matching Parameters page.

In the Host Aliasing dialog box, click Finish.

The Host Aliasing dialog box closes, and the Successful message box appears, indicating a success.

Click Ok to close the message box.

To use a regular expression to rename hosts:


	NOTE: This procedure continues from Getting started: create host aliasing rules.

In the Specify Matching Parameters page of the Host Aliasing dialog box, select the option Use a regular expression to convert a host name, followed by clicking Next.

The Host Aliasing dialog box refreshes, showing the page Use a regular expression to convert a host name.


	TIP: To use a different type of matching parameter, click Previous to return to the Specify Matching Parameters page.

Specify the replacement text.

In the Host Aliasing dialog box, in the Regular Expression box, type a regular expression that selects the host names that you want to replace.

Table 76.
Host	Select this host?	Expression	Host Selected?
my_host_1.company_a.com	Yes	my_host*	Yes
my_host_2.company_b.com	Yes		Yes
test_host_3.domain_c.com	No		No
test_host_4.domain_d.com	No		No

For complete information about the regular expressions syntax in Foglight, see the Command-Line Reference Guide.

In the Host Aliasing dialog box, in the Replace Expression box, type a literal expression that you want to use as the replacement text.

Table 77.
Selected host	Rename host?	Expression	Characters in the host name replaced?
my_host_1.company_a.com	Yes	my_test_host	Yes
my_host_2.company_b.com	Yes	my_test_host	Yes

The Host Aliasing dialog box refreshes.

The Manage Host Aliasing Rules dashboard refreshes, showing the newly-added rule.


	TIP: To use a different type of matching parameter, click Previous to return to the Specify Matching Parameters page.

In the Host Aliasing dialog box, click Finish.

The Host Aliasing dialog box closes, and the Successful message box appears, indicating a success.

Click Ok to close the message box.

To change host properties:


	NOTE: This procedure continues from Getting started: create host aliasing rules.

In the Specify Matching Parameters page of the Host Aliasing dialog box, select the option Merge hosts by a property other than name, followed by clicking Next.

The Host Aliasing dialog box refreshes, showing the page Merge hosts by a property other than name.


	TIP: To use a different type of matching parameters, click Previous to return to the Specify Matching Parameters page.

Specify the property whose value you want to change.

In the Host Aliasing dialog box, click Select a Property.

A list appears, showing only those properties that can be changed.


	IMPORTANT: The list that appears shows only a subset of the entire property set for the host object. This is because property matching filters can only reference certain types of properties such as String or Boolean properties. To see a full set of properties that are exist in the Host type, view the Schema Browser dashboard; for more information about this dashboard, see the Foglight User Guide.

Click the row containing the property that you want to change.

The list closes and the Host Aliasing dialog box refreshes, showing the newly-selected property.

Specify the replacement text.

In the Host Aliasing dialog box, in the Regular Expression box, type a regular expression that translates into the property value that you want to replace.

Table 78. Examples of regular expressions.
Host	Select this host?	Expression	Host Selected?
myhost_a.xyz.mydomain.com	Yes	(xyz.*)\.mydomain.com	Yes
myhost_b.xyz.mydomain.com	Yes		Yes
myhost_c.123.mydomain.com	No		No
myhost_d.123.mydomain.com	No		No

For complete information about the regular expressions syntax in Foglight, see the Command-Line Reference Guide.

In the Host Aliasing dialog box, in the Replace Expression box, type a regular expression that you want to use as the replacement text.

Table 79. Examples of regular expressions.
Selected host	Rename host property?	Expression	Characters in the host name replaced?
myhost_a.xyz.mydomain.com	Yes	$1.quest.com	Yes
myhost_b.xyz.mydomain.com	Yes	$1.quest.com	Yes

The Host Aliasing dialog box refreshes.


	TIP: To select a different source host, click Previous to return to the Specify Source Host page.

In the Host Aliasing dialog box, click Finish.

The Host Aliasing dialog box closes, and the Successful message box appears, indicating a success.

Click Ok to close the message box.

The Manage Host Aliasing Rules dashboard refreshes, showing the newly-added rule.

Merging topology objects

Merging two topology objects consolidates the data collected by the two or more existing object instances of the same type. This process involves creating property matching filters to select the topology objects. This is useful in situations when the regular merging process does not have information to match data objects as they are collected.

NOTE: Property matching filters can only reference a subset of the entire property set for a topology type such as String or Boolean properties. To see a full set of properties that are included in Host or other types of topology types, view the Schema Browser dashboard; for more information about this dashboard, see the Foglight User Guide.

Renaming host objects does not create nor delete any topology objects from the schema. When created, advanced rules instruct Foglight to consolidate any data collected from the merged topology objects under the target object in the data model. Additionally, advanced rules are comprised of two or more simple rules that are executed in a pre-defined order.

The range and type of simple rules in an advanced rule depends on the nature and complexity of the advanced rule. Each simple rule is assigned a priority number that illustrates the order in which they are executed. These priorities cannot be changed for the simple rules, however, changing the advanced rule priority affects each individual rule. For more information abut changing rule priorities, see Changing the priorities of host aliasing rules .

IMPORTANT: The property changing process is in effect only while its rules exist and are active while the resulted data consolidation is permanent. For more information, see Getting started: create host aliasing rules.

Selecting the option Create an Advanced Rule in the New Merging Rule Introduction dialog box invokes the Select a Type workflow for creating a rule that merges two or more topology objects.

From there, you specify the current and target properties, and finally review the summary of the merge process, as described below.

To merge topology objects:

NOTE: This procedure continues from Getting started: create host aliasing rules.

Specify the type of topology objects that you want to merge.

In the Host Aliasing dialog box, on the Select a Type page, use the TopologyObject node to select the desired topology type.

TIP: When expanded, the TopologyObject node contains a structure that contains all topology types that exist in the Foglight schema and it illustrates their relationships. All topology types in Foglight descend from this type. If you know the type name, either full or partial, instead of looking through the entire tree, use the filter above the navigation tree. To find out more about the Foglight schema, use Schema Browser dashboard. For more information about this dashboard, see the Foglight User Guide.

For example, to select the Host type, use the search filter by typing Host into the text search box and clicking Search. In the list that refreshes, showing the entries that contain Host, click the Host node.

When you select the topology type, click Next.

The Host Aliasing dialog box refreshes, showing the Create Merge Filter page.

The Create Merge Filter page allows you to specify the property that is used as a filter.

TIP: To select a different topology type, click Previous to return to the Select a Type page.

Select one or more objects of the selected type that you want to evaluate for merging, based on a common property value.

Ensure that the property you want to use for matching the objects is selected. By default, in the Host Aliasing dialog box, the name property is selected.

Optional. To use a different property, in the Host Aliasing dialog box, click Name: String. From the list that appears, click the row containing a different property.

IMPORTANT: Selecting another topology type produces a different list of properties. The list that appears shows only a subset of the entire property set for the Host type. This is because property matching filters can only reference certain types of properties such as String or Boolean properties. To see a full set of properties that exist in the selected topology type, view the Schema Browser dashboard; for more information about this dashboard, see the Foglight User Guide.

TIP: To look for a particular property, use the search filter at the top of the list.

For example, to evaluate Host objects based on their domain name, select the row containing the domainName entry.

The property list closes and the newly-selected property name and its data type appear in the Host Aliasing dialog box.

Specify the value of the selected property that you want to use as the search filter.

In the Host Aliasing dialog box, in the box on the left of the Use Regex check box, type a literal or regular expression that you want to search for. If using a regular expression, select the Use Regex check box.

TIP: For complete information about the regular expression syntax in Foglight, see the Command-Line Reference Guide.

For example, to look for hosts whose domain name is mydomain.com, type mydomain.com into the box.

In the Host Aliasing dialog box, click Next.

The Host Aliasing dialog box refreshes, showing the Specify Transformation Parameters page.

The Specify Transformation Parameters page contains the information about the target host.

TIP: To use a different property type for selecting objects, click Previous to return to the Create Merge Filter page.

After selecting one or more topology objects of the same type based on a common property value, from that subset of topology objects, select one or more topology objects that you want to merge using another common property value.

For example, if you selected the hosts with .mydomain.com as the domain name in Step 2, and from those hosts you want to find the ones with my_host_* in their name (not the domain name) and merge them with the hosts that have test_host_* in the name.

Specify the property name.

In the Host Aliasing dialog box, click the value on right or Property to Apply and from the list that appears, select the property name.

TIP: By default, the value that appears on the right of Property to Apply illustrates the property selected to do an initial evaluation (see Step 1). For example, if you selected the domain name, Domain Name: String appears on the right of Property to Apply.

For example, is you selected Host objects based on their domain name in Step 1, you can now select one or more Host objects from that subset using their name. To do that, from the list that appears, select the row containing the entry name.

Specify the property value that you want to use to select one or more topology objects in order to merge them.

In the Regular Expression box, type a regular expression containing the property value.

TIP: For complete information about the regular expression syntax in Foglight, see the Command-Line Reference Guide.

For example, to select the Host objects whose names start with my_host, type my_host*.

Specify the property value that you want to use to replace the value specified in Step b.

TIP: Replacing a property value with another object’s value causes the selected objects to merge.

IMPORTANT: You can only use the existing values. Specifying a property value that cannot be matched with a topology object results in an error.

In the Replace Expression box, type a regular expression containing the property value.

TIP: For complete information about the regular expression syntax in Foglight, see the Command-Line Reference Guide.

For example, to merge the hosts whose name starts with my_host, as specified in Step b, with the hosts whose name starts with test_host, in the Replace Expression box, type test_host*.

In the Host Aliasing dialog box, click Next.

The Host Aliasing dialog box refreshes, showing the Select Alternative Properties page.

The Select Alternative Properties page allows you to add alternative properties whose values are used to select and merge objects when the previously specified properties (see Step b) return no matches. To add alternative properties, complete Step 4; otherwise, click Next and proceed to Step 5.

TIP: To select objects using a different property, click Previous to return to the Specify Transformation Parameters page.

Optional. Add any alternative properties whose values are used to select and merge objects when the previously specified properties (see Step 3, sub-Step b) return no matches. The rule processes the alternative properties in the order in which they are listed.

For example, if you intend to select Host objects whose name property starts with my_host (as specified in the example in Step 3, sub-Step b), in case that selection returns no matches, you can to instruct the rule to inspect the localName property as well.

In the Host Aliasing dialog box, click Add.

The Alternative Property Table Selector dialog box appears.

IMPORTANT: Selecting another topology type produces a different list of properties. The list that appears shows only a subset of the entire property set for the Host type. This is because property matching filters can only reference certain types of properties such as String or Boolean properties. To see a full set of properties that are exist in the selected topology type, view the Schema Browser dashboard; for more information about this dashboard, see the Foglight User Guide.

In the Alternative Property Table Selector dialog box, select the row containing the property that you want to add as an alternative property.

For example, when working with Host objects that are selected based on their name property, to select the localName property as an alternative property, select the row containing the localName entry.

IMPORTANT: You can only select a single property. Selecting multiple properties results in an error. To select another property, use the Add button.

The Alternative Property Table Selector dialog box closes, and the Host Aliasing dialog box refreshes, showing the newly-added alternative property.

In the Host Aliasing dialog box, click Next.

The Host Aliasing dialog box refreshes, showing the Summary page.

The Summary page in the Host Aliasing dialog box describes the object merging logic. It also allows you to change the rule priority and to instruct Foglight to stop processing any rules with a lower priority when this rule executes (see the Stop processing lower priority rules when successful check box, disabled by default). By default, this rule is placed at the bottom of the priority queue. For example, if there are seven existing host aliasing rules, this rule is assigned the priority of 8 (see the Priority box). You can also change the priority at a later time. For more information, see Changing the priorities of host aliasing rules.

Optional. To change the rule priority or prevent the processing of the rules with the lower priority, use the Priority box and Stop processing lower priority rules when successful check box, as required.

TIP: To select a different source host, click Previous to return to the Specify Source Host page.

In the Host Aliasing dialog box, click Finish.

The Host Aliasing dialog box closes, and the Successful message box appears, indicating a success.

Click Ok to close the message box.

The Manage Host Aliasing Rules dashboard refreshes, showing the newly-added rule.

Build Script Agents

Script types

There are two types of scripts:

•

Type 1 scripts. The Foglight collector calls these 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.

For a sample of a Type 1 script in this manual, see Type 1 script example.

Additionally, sample Type 1 scripts are also available from the Foglight Management Server installation directory:

Windows

<foglight_home>/scripts/agent/Type1_NT_Script.bat

Unix

<foglight_home>/scripts/agent/Type1_Unix_Script.sh

•

Type 2 scripts. These 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.

For a sample of a Type 2 script in this manual, see Type 2 script example.

Additionally, a Windows version of the Type 2 script is also available from the Foglight Management Server installation directory:

<foglight_home>/scripts/agent/Type2_NT_Script.bat

Type 1 script example

The following is an example of a Type I script:


	Sample Type 1 scripts are also available from the Foglight Management Server installation directory: Windows <foglight_home>/scripts/agent/Type1_NT_Script.bat Unix <foglight_home>/scripts/agent/Type1_Unix_Script.sh

if not "%ECHO%"=="" echo %ECHO%

if not "%OS%"=="Windows_NT" goto EXIT

if "%sample_freq%"=="" set sample_freq=60

echo LOG Start collecting data for NT at %sample_freq% seconds

echo TABLE NT

echo FooId.String.id = Bar

echo stringProp.String = This is a non-identity string property.

echo intProp.Integer = 30

echo countMetric = 40

echo timeMetric:second = 50

echo rateMetric:count/second = 50

echo fancyMetric:[4 kilobyte] = 50

echo intWithUnit.Integer:[minute] = 60

echo stringObs.StringObservation.obs = Hello World

echo FooId.String.id = Another Bar

echo stringProp.String = This is a non-identity string property.

echo intProp.Integer = 31

echo countMetric = 41

echo timeMetric:second = 51

echo rateMetric:count/second = 51

echo fancyMetric:[4 kilobyte] = 51

echo intWithUnit.Integer:minute = 61

echo stringObs.StringObservation.obs = abc

The following is an example of a Type 2 script:

Type 2 script example


	NOTE: A Windows version of the Type 2 script is also available from the Foglight Management Server installation directory: <foglight_home>/scripts/agent/Type2_NT_Script.bat

if not "%OS%"=="Windows_NT" goto EXIT

if not "%ECHO%"=="" echo %ECHO%

if "%sample_freq%"=="" set sample_freq=60

echo LOG Start collecting data for NT at %sample_freq% seconds

:Loop

echo LOG New sample is available

echo TABLE NT

echo FooId.String.id = Bar

echo stringProp.String = This is a non-identity string property.

echo intProp.Integer = 30

echo countMetric = 40

echo timeMetric:second = 50

echo rateMetric:count/second = 50

echo fancyMetric:[4 kilobyte] = 50

echo intWithUnit.Integer:[minute] = 60

echo stringObs.StringObservation.obs = Hello World

echo FooId.String.id = Another Bar

echo stringProp.String = This is a non-identity string property.

echo intProp.Integer = 31

echo countMetric = 41

echo timeMetric:second = 51

echo rateMetric:count/second = 51

echo fancyMetric:[4 kilobyte] = 51

echo intWithUnit.Integer:minute = 61

echo stringObs.StringObservation.obs = abc

"../bin/rapssleep" %sample_freq%

goto :Loop

:EXIT

Script syntax

When writing a script to create a custom agent, use the following syntax:

TABLE table_name

START_SAMPLE_PERIOD

field_name[.type[.{id|obs}]][:unit]=value

…

END_SAMPLE_PERIOD

…

END_TABLE

…


	NOTE: The ellipsis ‘…’ indicates that you can repeat the level.

A Canonical Data Transformation (CDT) dynamically converts the output data into the appropriate format (such as topology types and observations) that exist in the collection model. This mechanism dictates the syntax of the line of the code that specifies the field data immediately following the START_SAMPLE_PERIOD command, as shown in the above syntax block:

START_SAMPLE_PERIOD

field_name[.type[.{id|obs}]][:unit]=value

Table 80. Script elements and their definitions.
Script Element	Definition
END_SAMPLE_PERIOD	Sends the current collection sample to the database and completes the transaction.
END_TABLE	Closes the table.
field_name	Contains the name of the field under which to store the observation.
id	Indicates that the property should be treated as an identity.
LOG message	Sends a status message to Foglight Agent Manager logs with message specifying the message.
LOG severity message	Sends an error message to Foglight Agent Manager logs with message specifying the message and severity set to one of the following values: FATAL, WARNING, or CRITICAL.
NEXT_SAMPLE	Sends multiple rows of field data in a single transaction.
obs	Indicates that the specified topology type is an observation (such as StringObservation). NOTE: Currently, script agents only accept the .obs designation when the type is Metric or StringObservations. Other types are not supported as observations.
SLEEP sample_freq	In Type 2 scripts, this element ends the script and instructs the collector to wait for the specified time before executing the script again. NOTE: In NT operating systems, use the rapssleep command, as those systems do not have a sleep facility: rapssleep %sample_freq%
START_SAMPLE_PERIOD	Starts the data collection for the specified table and inserts field data using the line of code that immediately follows this command.
TABLE table_name	Opens the table with table_name specifying the name of the table. If an identity field is declared, append it to the table name.
type	Specifies the topology type if it is not a metric.
unit	Contains the name of the measurement unit to use for metrics. If a unit is not specified, Foglight uses “count” as the unit by default.

Understanding how script agents collect data

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.

Script agents work by running a prescribed script and processing the output. The actual agent is called JCollector. This agent runs the script, parses the output, and sends the resulting data table samples to Foglight.

Figure 101. Illustration of how a script agent communicates with Foglight.

There are two ways to make a script run:

•

Let JCollector call the script on the sampling interval (Type 1 scripts).

•

Allow JCollector to call the script once (Type 2 scripts). The script controls the sampling interval.

Type 2 scripts are more complex because the script author must handle looping and honour the sampling interval from the server. This might be necessary if the length of the loop is important for doing things like 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. For more details about Type 1 and Type 2 scripts, see Script types.

As mentioned before, JCollector runs the script and parses the output sent to STDOUT. It then sends that output back to the Management Server in the form of tables. There is a special Canonical Data Transformation (CDT) that interprets the data that is sent back. That CDT knows how to deal with the table elements, mostly by parsing the field/column names.

The standard model for a script agent is an agent containment model. An agent containment model means that the tables you send from your script agent are contained in an instance of your agent, and that agent is contained inside a host. This is usually good enough for getting started.

Script agent format

The output format is easy to understand:

The TABLE directive instructs the Collector to start a new table of data with the specified name. A single script agent can emit multiple tables. START_SAMPLE_PERIOD and END_SAMPLE_PERIOD allow you to insert rows into that table. One or more rows are allowed. The Field = Value entry specifies the name of a table column and its value. To find out more about syntax rules, see Script syntax.

For example, if you have a table of data with the following contents:

Table 81. Table of example data
Host	CPU	Memory	Disk
hostA	90	55	20
hostB	78	35	43

Then the script agent results appear as follows:

This simple example demonstrates how data tables are translated into script agent format. However, it is invalid because of non-numeric data in the Host column. This is covered later in this topic, and illustrates a classic pitfall while working with script agents in Foglight. For more information, see Script agent pitfalls: Converting string data.

Basic script agent example

In this example we create a basic script agent and confirm at the data it collects. The following listing contains a basic script.

echo TABLE NT

echo Field1 = 10

echo Field2 = 20

After uploading the script to the Management Server, the Management Server processes the script and creates a cartridge around it, resulting in a CAR file. The cartridge includes the script, the Collector agent, and the CDT used to process the data.

Creating a cartridge from a script involves several steps. First, you write an agent script and upload it to the Management Server using the Build Script Agent dashboard. The upload process automatically builds the agent package. Next, you deploy that agent package to the host, create an agent instance, and edit its properties, if required. For complete instructions on using the browser interface to create a script agent and enable its data collection, see Uploading custom agent scripts.

After a minute (which is the default sampling frequency), you can verify that the agent is collecting data using the Agents dashboard. The Agents dashboard can be accessed by clicking Homes > Agents on the navigation panel. On the Agents dashboard, applying the With Agents filter allows you to see monitored hosts with agents. Use that list to locate the host you deployed the script agent to, and your script agent. For more information about the Agents dashboard, see the Foglight User Guide.

If you cannot find your script agent on the Agents dashboard, you can retrieve its log from the Agent Status dashboard by selecting your script agent and clicking Get Log. For more information about retrieving agent logs, see Retrieve agent logs.

To verify that your script agent is collecting data, after locating the agent instance on the Agents dashboard, select the Data option. Choosing this option allows you to view the raw data. Applying the Metric Analyzer view allows you to see the metrics’ value and type. Then, choose the Data option to see the collected data in a selected table.

For the purpose of this exercise, use the script and process described above. The results on the Agents dashboard page should be similar to the following illustration.

Figure 102. A pictorial example of the scripting exercise described earlier.

As illustrated above, your script agent is collecting data and sending it to Foglight, you are getting data into Foglight. Remember that this data is in a table inside the agent instance. If you need additional tables, you need to create new agent instances.


	IMPORTANT: Iteration is built into script agents. If you want to change your script, to for example, add a new field, update the script, then complete the process of uploading the updated script and re-deploying the agent package to the host, as instructed above. You will notice that the cartridge version number is automatically increased. There is no need to recreate the agent instance. The existing instances automatically run the updated script after the upgrade.

Script agent pitfalls: Converting string data

We now go back to the data example shown in Script agent format, with the contents:

Table 82. Sample data for converting string data example.
Host	CPU	Memory	Disk
hostA	90	55	20
hostB	78	35	43

Then the script agent results based on the above table are as follows:

Uploading the script to the server, deploying the resulting agent package, and creating and enabling an agent instance results in the following type of data being collected: CPU, Memory, and Disk. Note that the Host column is missing from the set of collected data.

Figure 103. Example of data collected from the code sample above.

To find out what happened to the Host column, observe the contents of the server log file. You can download log files using the Log Analyzer dashboard. This dashboard is accessible through the navigation panel, under Management Server > Diagnostic > Log Analyzer. For more information about the Log Analyzer dashboard, see Monitor Server Performance. The pattern to look for with script agent errors is anything related to TopologyAdapter. The following section in the log file shows an error related to the Host entry in the script:

2009-07-21 07:45:41.187 ERROR [Data-3-thread-13215] com.quest.nitro.service.agent.TopologyAdapter - The value provided for the metric could not be converted to a double.

Value = hostA. Node path = [FglAM::host-1_0_0/CDT-1_0_0/topology-adapter.xml]/SPI:SPI/host:*/HostData:*/row:row/Host java.lang.NumberFormatException: For input string: "hostA"

What does this mean in plain language? It looks like the server is trying to convert the string-based host names provided for the Host field into doubles. This is because, by default, Foglight assumes all script agent entries are numeric time series data. In other words, Foglight is trying to convert these values to numbers. It is not working as expected, which explains why the Host values are not appearing as expected.


	TIP: This behavior is different than the one in Foglight 4. In Foglight 4, the values were not typed at all. They were placed into a table, and the typing occurred when a view was created to look at the data. In other words, Foglight 4 treated all values as strings. Foglight 5 attempts to convert the values to something meaningful right away, so the data can be rolled up and managed properly. To do that, we assumed that the vast majority of data would be metric data.

What this means is you need to do something special with your strings. The first thing we need to do is mark it as a String using the following statement:

Host.String = hostA

But there are actually a couple of options. The one you choose depends on what you want to accomplish.

Table 83. Key questions for determining how to prceed with a string conversion.
Question 1	Does the field uniquely identify the row of data? If it does, then we should mark it as an identity field. An identity field causes a new object instance to be created.
Question 2	Does the field change frequently? If a string changes frequently, then it should be marked as an observation. That way Foglight stores a new value every sample, and does not the changes. If a string changes infrequently, then it can be a property. A property has one value stored, and changes are tracked. To determine if something changes frequently, ask the following question: Could this value change each sample period in a typical use case? To understand these concepts, we need to expand our example.

An ExpandedHost example

In this example, we will assume that we are actually gathering the following data about a host:

Table 84. Example of collected host data.
Host	hostA	hostB
CPU	90	78
Memory	55	35
Disk	10	43
IP Address	10.4.22.10	10.4.21.14
State	Up	Down

In the above data sample, there are three string values: Host, IP Address, and State. We will now apply Question 1 and Question 2 to each of the entries:

Table 85. Apply the key questions to the string values.
	Identity field?	Changes frequently?
Host	Yes	No
IP Address	No	No
State	No	Yes

It is clear that the Host column contains the name of a host, and therefore defines its identity. We want to see a new instance of the data for each unique value of Host.

IP Address, on the other hand, is not an identity property. It is unlikely to change with each sample frequency. In most environments, IP Addresses are leased long-term. Marking IP Address as a property but not an observation makes sense.

Finally, the State column is not an identity property. However, it is possible that it could change from sample period to sample period. A host may not go down often, but when it does go down you want to know when. Tracking State as a string observation makes the most sense.

Here is the resulting script:

echo TABLE ExpandedHost

echo IPAddress.String = 10.4.22.10

echo CPU = 90

echo Memory = 55

echo Disk = 20

echo State.StringObservation.obs = Up

echo Host.String.id = hostB

echo CPU = 78

echo Memory = 35

echo Disk = 43

echo IPAddress.String = 10.4.21.14

echo State.StringObservation.obs = Down

As you can see, the state observation shows up with the other time-series metrics in the Property Viewer. At the moment, the Metric Analyzer view does not show observation data.

After uploading the script and re-deploying the agent package, on first look, the data you see in the Metric Analyzer for the script agent appears to be the same, consisting of cpu, disk, and memory.

Figure 104. The Choose a Table box allows you to switch between the two host instances, and display the metric for the chosen host.

Now we actually have two sets of entries: one for hostA, and another one for hostB. What we never really noticed before is that we were getting two values of the same metrics into the same table before. Now we have two separate table entries, one for each host. So we fix at least one problem by adding Host.String.id to the script.

But where are the IP Address and State columns? IP Address should be visible as a property.

Figure 105. To see the script agent properties, open the Property Viewer and scroll down until you see the ipAddress property in the viewer.


	TIP: To open the Property Viewer, in the Data Browser’s upper-right corner, click Views and select Property Viewer (Foglight:Object) from the list that appears:

We have so far accounted for two of our changes. But what happened to the State column? Observations are a special class of metric. They are, by nature, harder to display. A time-series metric of type double can be graphed. But a set of values for a String appears differently. In general, observations are a little more difficult to deal with than other types. You can still display them, write rules, and so on, but you have to use special techniques. So where is State?

Figure 106. The Property Viewer shows the State metric values if we scroll down further:

Common errors

The following error in the server log indicates that you declared a String as Field.String.obs instead of Field.StringObservation.obs:

2009-07-21 09:05:43.593 ERROR An unexpected error occurred which may cause undesired behavior. You may want to contact Quest Software Inc. customer support if you see this error again: Canonical data transform failed: java.lang. IllegalStateException: Error processing incoming data for node path:

[FglAM:: expandedhost-1_0_0/CDT-1_0_0/topology-adapter.xml]/SPI:SPI/expandedhost:*/HostData:*/row:row/State.String.obs:

java.lang.IllegalArgumentException: Type 'foglight-5:String:1' does not have a property with the name 'current'

You need to correct your script. This error is actually fatal to the processing of the agent data. You will not see any data pushed into the server, and more specifically, the agent entry will not appear on the Agents home page.

Next, if you see the following error:

2009-07-21 09:05:43.546 INFO The identity properties of topology type expanded host_Agent_Table_HostData have changed.

The instances of this type will be renamed.

There is no need to correct anything in your agent script. This error appears because during the processing of the data, the server came across your identity declaration. This caused the server to change the definition of the table. You might see this as part of your iterations.

Script agent field syntax

In script agents, data is sent to the server by specifying a series of field=value pairs. The syntax is as follows:

field[.type[.{id|obs}]][:unit]=value


	CAUTION: When using observations, script agents only accept the .obs designation when the type is Metric or StringObservations. Other types are not supported as observations.

As we work through this topic we explore how to use all elements of this syntax.

For detailed syntax description, see Script syntax.

How script agent data is represented in Foglight 5

In Foglight 4, data modeling was uniform for all collections. Data was gathered by agents and organized into tables. The tables were attached to an agent instance. The agents were attached to host instances.

Foglight 5 allows for many different kinds of data models, including the Foglight 4 model. To make transition easier, script agents make use of the Foglight 4 data model. This means that the data in a script agent is gathered by an agent, organized into tables attached to the agent, and the agent is attached to a host. This model is visualized below: it applies to Foglight 4 and Foglight 5:

This means that script agent data models look the same up to the agent. There is a host, and it contains a script agent.

The differences between Foglight 4 and Foglight 5 are visible at the table level. A Foglight 4 table is like a database table. Each new collection is a new row in the table. A Foglight 5 table is actually a data object. The columns in the collection are turned into properties, metrics or observations, depending on the type of information provided by the script agent.

This is a significant new bit of flexibility, but a bit tricky to fully understand. Let's consider a script agent that collects host data.

Table 86. Comparison of Foglight 4 and Foglight 5 Script Agent scripts.
Foglight 4 Script Agent	Foglight 5 Script Agent
@echo off @if not "%ECHO%"==" " echo %ECHO% @if not "%OS%"=="Windows_NT" goto EXIT echo TABLE ExpandedHost echo START_SAMPLE_PERIOD echo Host = hostA echo CPU = 90 echo Memory = 55 echo Disk = 20 echo END_SAMPLE_PERIOD echo START_SAMPLE_PERIOD echo Host = hostB echo CPU = 78 echo Memory = 35 echo Disk = 43 echo END_SAMPLE_PERIOD echo END_TABLE	@echo off @if not "%ECHO%"==" " echo %ECHO% @if not "%OS%"=="Windows_NT" goto EXIT echo TABLE ExpandedHost echo START_SAMPLE_PERIOD echo Host.String.id = hostA echo CPU = 90 echo Memory = 55 echo Disk = 20 echo END_SAMPLE_PERIOD echo START_SAMPLE_PERIOD echo Host.String.id = hostB echo CPU = 78 echo Memory = 35 echo Disk = 43 echo END_SAMPLE_PERIOD echo END_TABLE

Table 87. In Foglight 4, you get a table that looks like this:
Host	CPU	Memory	Disk
hostA	90	55	20
hostB	78	35	43

The problem with this table is that it creates one entry per host, causing you to do additional work to differentiate between different host instances.

This type of table in Foglight 5 results in creation of two objects of type ExpandedHost. The Host property is the unique identifier for the object because Foglight generates a new object instance will be generated for each new Host entry in the script agent. Each object has CPU, Memory and Disk metrics attached to it.

Figure 107. An illustration of host objects.

Each metric is a set of time-series data. This gives much more flexibility, at the cost of a bit of up front complexity. You can find each unique ExpandedHost instance easily. For each instance, you can query the metrics in any number of ways, pulling out average, minimum, maximum, standard deviation, or current value for any time range.

In the previous topics we worked through an example with three string values. It is worth repeating the results. The three string values were the host name, IP address and host state:

Table 88. String values and their properties.
	Identity field?	Changes frequently?
Host	Yes	No
IP Address	No	No
State	No	Yes

This lead to the following script agent entries:

echo IPAddress.String = 10.4.22.10

echo State.StringObservation.obs = Up

Here's the final reasoning:

Setting metric units

Table 89. Logic for determining data model behavior
Field	Collection Behavior	Script Agent Syntax	String Type	Data Model Behavior
Host	Never changes, defines identity for the collection	Host.String.id	Identity	An identity property called Host is added to the object. For each new value, a new object is created.
IP Address	Might change occasionally in some cases	IPAddress.String	Property	A property called IPAddress is added to the object, and a value is stored. If the value changes, a topology change event occurs.
State	Might change every collection	State.StringObservation.obs	Observation	Like a metric: one value is stored per collection

By default, any metric that comes into the system does not have a unit assigned. This means any numeric value have the unit count. This quite often does not matter early on in agent development. But without units, in the browser interface, you see this the following type of output in script agent views:

Figure 108. A script agent view without units defined.

The above graph should show a CPU usage percentage over time, however instead of percentage, the view shows the count, which is not very helpful.

In a script agent, it is possible to set the unit using the last part of the field syntax:

field[.type[.{id|obs}]][:unit]=value

The possible units are listed below:

Table 90. Possible units for use in script agents.
Scale	billion, billionth, million, millionth, thousand, thousandth, trillion, trillionth
Memory/Disk	bit, byte, exabyte, gigabyte, kilobyte, megabyte, petabyte, terabyte
Time	day, hour, microsecond, millisecond, minute, month, nanosecond, second, year
Math	percent
Default	count

Units can be combined to make meaningful rates. For example, a disk I/O rate can be assigned a unit of megabyte/minute using the following line:

DiskIO:megabyte/minute

A modified version of the script appearing in How script agent data is represented in Foglight 5 now includes units for CPU, Memory and Disk. It also includes a DiskIO metric that has a compound unit.

echo TABLE HostWithUnits

echo IPAddress.String = 10.4.22.10

echo CPU:percent = 90

echo Memory:megabyte = 55

echo Disk:gigabyte = 20

echo DiskIO:megabyte/minute = 13

echo State.StringObservation.obs = Up

echo Host.String.id = hostB

echo CPU:percent = 78

echo Memory:megabyte = 35

echo Disk:gigabyte = 43

echo DiskIO:megabyte/minute = 17

echo IPAddress.String = 10.4.21.14

echo State.StringObservation.obs = Down

It is therefore highly recommended that you put units in all of your metrics. It makes your gathered data much more readable in the user interface.

Figure 109. A view resulting from the above script now includes disk, diskIo, memory, and cpu metrics, each on a separate line in the graph.

Reserved words

Not all field names are available. Many field names are reserved. The reason for this is that script agents create objects for each TABLE entry. These objects extend a type called F4Table. This type already has properties defined. You are not allowed to replace those properties with new ones as this causes problems with how models hold together.

It is possible to figure out exactly what property names are reserved by looking at the type definitions for F4Table and its parent classes. The type hierarchy looks like this:

TopologyObject

F4Table

Figure 110. The full set of reserved names can be observed by looking at an instance of a script agent in the Data Browser:

It is also worth mentioning that starting in version 5.5.0, the property names that appear are proper words and are not the exact property names.

Table 91. A full list of the reserved names, based on an inspection of the types.
Object IDs	objectID, id, version, topologyObjectId, topologyObjectVersionId, topologyObjectVersion, effectiveStartDate, effectiveEndDate, lastUpdated
Object Identity	name, longName
Object Management	scheduleIds, isBlackedOut, annotations, parents
Alarms	alarms, aggregateAlarms, localState, aggregateState, localStateSeverity, aggregateStateSeverity, aggregateAlarmState, alarmWarningCount, alarmCriticalCount, alarmFatalCount, alarmTotalCount, alarmAggregateWarningCount, alarmAggregateCriticalCount, alarmAggregateFatalCount, alarmAggregateTotalCount, changeSummary, changeCount, aggregateChangeCount
Type and Size	topologyTypeName, topologyObjectSize
Host and Agent	monitoredHost, monitoringAgent

Here is a sample script that includes fields that conflict with reserved names:

echo TABLE BadFields

echo localState.String.obs=Up

echo CPU:percent = 90

echo id=3

echo version.String=3.2

echo name.String=Monkey