Private situation XML specification

IBM Tivoli Monitoring > Version 6.3 Fix Pack 2 > Administrator's Guide > Agent-based services > Private situations
IBM Tivoli Monitoring, Version 6.3 Fix Pack 2

Private situation XML specification

Use the elements from the private situation XML specification to create private situations for an agent on your computer.

Default private situation path and file name

install_dir\localconfig\pc\pc_situations.xml

install_dir/localconfig/pc/pc_situations.xml

PCSICNFG in the RKANDATV data set
If you prefer to name the file differently or use a different path, use the IRA_PRIVATE_SITUATION_CONFIG and IRA_LOCALCONFIG_DIR agent environment variables to change the file name and path. For detailed information about the environment variables, see the "Environment variables" topic in the IBM Tivoli Monitoring Installation and Setup Guide.

Elements

XML tags are case-insensitive. All other parameters are case-sensitive. For example, you can enter <PRIVATESIT>, <PrivateSit>, or <privatesit>.
You can use the SITS.xsd schema file, located in the samples/PrivateConfigSamples directory on the Agent DVD image, to validate private situation XML files. However, the schema file requires the XML tag names to be in uppercase.
<PRIVATECONFIGURATION>
PRIVATECONFIGURATION is the root element identifying this XML as an agent private situation configuration document.
<PRIVATECONFIGURATION REFRESH="N">
<PRIVATESIT>
<SITUATION NAME="Check_Process_CPU_Usage"  INTERVAL="000500" />
<CRITERIA>
<![CDATA[ *VALUE NT_Process.%_Processor_Time *GE 65 *AND 
  *VALUE NT_Process.Priority_Base *NE 0 *AND
  *VALUE NT_Process.Process_Name *NE _Total]]>
</CRITERIA>
<CMD><![CDATA[netstat >.\logs\netstat.dat]]></CMD> 
<AUTOSOPT When="N" Frequency="N" /> 
</PRIVATESIT>
</PRIVATECONFIGURATION>
REFRESH=

This parameter is typically ignored. This parameter is only applicable when updating private situation configuration through the Agent Service Interface or when downloading from the Centralized Configuration server. This parameter is ignored when the agent processes the private situation configuration file directly from the localconfig directory at agent start up.

Specify "Y" or "Yes" to run only the newly inputted private situations. When specifying Y, all of the existing private situations are stopped and deleted, then only the newly inputted private situations are processed and started. The monitoring agent's operation log provides a list of the old private situations that were stopped and also lists the processed private situations that were started.

Specify "N" or "No" to run all existing private situations.

Only Y, Yes, N, or No values are valid. If you use other values, the entire current private situation configuration XML specifications are rejected.

For more information see the Activate= parameter in Configuration load list XML specification.
<PRIVATESIT>

Enclose each situation definition in PRIVATESIT begin and end tags.

<SITUATION>
Within each set of PRIVATESIT begin and end tags, add a set of SITUATION begin and end tags. Within each set of SITUATION begin and end tags, is the complete situation definition. Define the situation with these attributes:
NAME=

The situation name, which must begin with a letter and can be up to 31 letters, numbers and _ underscores, such as "Missing_Process_Helper_Harmless". Be aware that all situations, whether private or enterprise, must have unique names. Otherwise, actions invoked upon one situation are applied to the other situation with the same name.

INTERVAL=

Unless this is a pure-event situation, specify the sampling interval in HHMMSS format. Default: 001500 (15 minutes). Alternatively, use the <INTERVAL> element.

CRITERIA=
The situation formula. Alternatively, use the <CRITERIA> element.
<SITUATION NAME="High_CPU_Usage" INTERVAL="000500" 
CRITERIA="*VALUE NT_Process.%_Processor_Time *GE 65 
*AND *VALUE NT_Process.Priority_Base *NE 0 
*AND *VALUE NT_Process.Process_Name *NE _Total" />
DELETE=

Optional. Specify Y to delete the situation specified in the NAME= attribute. Use this attribute to dynamically remove a private situation without recycling the agent or deleting the local private situation XML file. If you specify a private situation name that is not defined or has already been deleted, no action is taken. You can specify multiple delete statements.

To dynamically refresh a private situation, include a delete statement before the new add statement. The order of specifications within a private situation XML file affect the final operational private situation definitions and configuration. The order in which the XML files are read is defined by the Centralized Configuration load list and does not follow alphabetical order.
This example deletes a single private situation:
<privateconfiguration>
<privatesit>
  <situation name="Check_Process_Name" delete="Y" />
</privatesit>
</privateconfiguration>
This example deletes multiple private situations:
<privateconfiguration>
<privatesit>
  <situation name="Check_Process_Name" delete="Y" />
</privatesit>
<privatesit>
  <situation name="Check_DiskSpace_Low" delete="Y" />
</privatesit>
</privateconfiguration>
This example refreshes a private situation by first deleting the situation and then adding the situation:
<privateconfiguration>
<privatesit>
  <situation name="Check_Process_CPU_Usage" delete="y" >
  </situation>
</privatesit>
<privatesit>
  <situation name="Check_Process_CPU_Usage" interval="000500" >
  </situation>
    <criteria>
    <![CDATA[*VALUE NT_Process_64.%_Processor_Time *GE 10 *AND 
             *VALUE NT_Process_64.Priority_Base *NE 1 *AND 
             *VALUE NT_Process_64.Process_Name *NE _Total]]>
      </criteria>
</privatesit>
</privateconfiguration>
<INTERVAL>

Specifies the situation sample interval in HHMMSS format. A value of 000000 (six zeroes) indicates a pure-event situation. For sampled-event situations, the minimum interval is 000030 (30 seconds) and the maximum is 235959 (23 hours, 59 minutes, and 59 seconds). Default: 001500 (15 minutes). This element is required if the INTERVAL attribute is not specified in the SITUATION element.

<CRITERIA>

The situation criteria is specified within this element and the <![CDATA[ ]]> element. Each expression has three parts, starting with *VALUE or *MISSING, followed by attribute-table-name.attribute-name, the logical operator (such as *EQ), and the attribute threshold value or, for the MISSING function, a comma-separated list of names. It is acceptable, but not required to begin the formula with *IF, as is done in enterprise situation formula syntax.

For the attribute, use the detailed attribute name in the format of attribute-table- name dot attribute-name. The product attribute file defines the agent product attribute tables and associated attributes, for example, knt.atr or kux.atr files residing in the ATTRLIB directory for a distributed agent installation.

Another way to find attribute names is by querying the table through the Agent Service Interface. Open ASI > Queries and select a table name. ASI returns a complete table schema including the table display name and display names for all table columns.
The Operator defines logical operation of filter value and data. The supported operators are: *EQ for equal, *NE for not equal, *GE for greater than or equal to, *LE for less than or equal to, *LT for less than, and *GT for greater than. Within the <CRITERIA> element, the command is enclosed in Character Data tags to exclude it from XML parsing. This example shows a formula that triggers an alert when the available disk space is 35% or below:
<CRITERIA> <![CDATA[*VALUE NT_Logical_Disk.%_Free *LE 35]]> </CRITERIA> 
For multiple expressions, use the *AND or *OR connector. All connectors in the formula must be the same, either all *AND or all *OR. Mixing logical *AND and *OR connectors is not supported. You can have up to nine *AND connectors or up to 10 *OR connectors in a formula, .

In a formula with multiple expressions, there can be no more than one *MISSING expression, it must be the last expression in the formula, and only *AND connectors can be used. (See the Tivoli Enterprise Portal User's Guide for a description of Check for Missing Items.)

Wildcards are not supported. For example, *VALUE NT_Process.Process_Name *EQ S* to find all processes that start with "S" is invalid in a private situation. Likewise, wildcards in a *MISSING list are invalid, such as NT_Process.Process_Name *EQ ('DB2*') to find all processes beginning with DB2.
Examples:
<CRITERIA>
<![CDATA[ *VALUE NT_Process.%_Processor_Time *GE 65 *AND 
  *VALUE NT_Process.Priority_Base *NE 0 *AND
  *VALUE NT_Process.Process_Name *NE _Total]]>
</CRITERIA>
<CRITERIA>
<![CDATA[ *MISSING NT_Process.Process_Name *EQ ('schedule','notepad')]]>
</CRITERIA>
<CRITERIA>
<![CDATA[ *VALUE Linux_Process.State *NE Running *AND 
*MISSING Linux_Process.Process_Command_Name *EQ ('MyHelp','myhelpw')]]>
</CRITERIA>
Enumerated attributes have a predefined set of values. You can specify either the enumeration symbol or the name. For example, both of these expressions with a process execution state of Stopped (T) are valid. If an SNMP alert is sent or an action taken, the symbol is used rather than the name:
<CRITERIA><![CDATA[ *VALUE Process.Execution_State *EQ Stopped]]></CRITERIA>
<CRITERIA><![CDATA[ *VALUE Process.Execution_State *EQ T]]></CRITERIA>
If the private situation uses any scaled attributes, their values must be normalized for proper evaluation. A scaled attribute value is used to specify how many positions to shift the decimal point to the left. For example, 55.255 is a valid value for an attribute that displays with a scale of 3. To normalize it, you would shift the decimal point right by three places to be 55255.

SCAL (Scale) Integer comparison value (example used is 5000)
Not defined (0) 5000
1 Seen as 500 or 500.0 but represents 5000
2 Seen as 50 or 50.00 but represents 5000
3 Seen as 5 or 5.000 but represents 5000

The attribute description topics for your product should specify whether the value is scaled. For distributed agents, you can also review the attribute file for scal in the attribute definition. For example, khd.atr for the Warehouse Proxy agent has a work queue insertion rate attribute with scal 2. Location of kpc.atr files: <install_dir>\TMAITM6\ATTRLIB; <install_dir>/platform/<pc>/tables/ATTRLIB, where platform is the operating system and pc is the product code.
This example shows a hexadecimal integer as the comparison value:
<CRITERIA><![CDATA[ *VALUE Disk.Mount_Point_U *EQ '/opt' *AND 
*VALUE Disk.Space_Used_64 *GT 0x80000000 ]]></CRITERIA>
The <CRITERIA> element is required if CRITERIA is not specified in the <SITUATION> element.
*REGEX

IBM Tivoli Monitoring frequently requires text scan and pattern matching upon event and sample data, such as name, address, message, and log record. You can add the Regular Expression predicate filter function to enhance agent monitoring capability and applicability. The *REGEX predicate function specification syntax is defined as:
*REGEX attribute_name operator "Regular Expression"
where,

attribute_name is the select filter fully-qualified attribute name.

operator is the logical operation of the filter value and data. The supported operators are: *EQ (meaning value equal), and *NE (meaning value not equal).

" " are regular expression delimiters. You can also use other characters for delimiters such as @ @ if the " character is needed in the expression. For example: *REGEX attribute_name operator @Regular Expression@

Regular Expression specifies the desired regular expression definition.
The following example shows *REGEX predicate function usage. In this example, the company ABC wants to inspect user input for P.O. Box information, in order to raise an event because ABC cannot ship to post boxes.
<privateconfiguration>
<privatesit>
<SITUATION NAME="Check_Valid_Address" INTERVAL="000030" >
  </SITUATION>
<criteria>
<![CDATA[*REGEX ABCCUSTOMER_PROFILE00.Address 
    *EQ "(?:Post (?:Office )?|P[. ]?O\.? )?[Bb]ox\b"]]>
</criteria>
<DISTRIBUTION>ICVR5A05:ABC00</DISTRIBUTION>
</privatesit>
</privateconfiguration>
The *REGEX predicate function can be used in combination with additional predicate functions as show in the following example.
<privateconfiguration>
<privatesit>
<Situation Name="Check_Valid_Address" Interval="000030" />
<criteria>
<![CDATA[*VALUE ABCCUSTOMER_PROFILE00.Weight  *GE 5 *AND 
    *REGEX ABCCUSTOMER_PROFILE00.Address  
    *EQ $(?:Post (?:Office )?|P[. ]?O\.? )?Box\b$ ]]>
</criteria>
<Distribution>ICVR5A05:ABC00</Distribution>
</privatesit>
</privateconfiguration>
As a general rule, *REGEX filters on application column data in data row storage buffer. Therefore, the begin input (^ or \A) or end of line ($ or \Z) anchor do not apply and are unnecessary when matching at the beginning or end of column data.
Usage notes:

Integer attributes are not supported in the regular expression predicate.

Enumerated attributes are supported in the regular expression predicate, however, the actual column attribute value must be used in constructing the regular expression itself. The enumerate value substitution in regular expressions that requires automated modification of the expression itself, is unsupported.
For example, the attribute Day_Of_Week in the table Local_Time have the enumerated character string values of Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, but have the actual column value of 00, 01, 02, 03, 04, 05, 06. The actual column values must be used in the regular expression construction.

A regular expression containing attributes of unsupported data types such as, integer, integer-64, integer enumeration, and hexadecimal string, are flagged as an error and the private situation definition is rejected.

Regular expression implementation varies slightly according to the supporting engine. The private situation *REGEX predicate filter function leverages the ICU Regular Expression engine and its specifications. See the ICU User Guide for more information.
<CMD>
Optional. Defines the action command or script to invoke when the situation criteria are true. Within the <CMD> element, the command is enclosed in Character Data tags to exclude it from parsing. This example shows a system command that displays the timestamp in a message box at the agent when the situation becomes true. Without the CDATA tagging, the & ampersand and {} brackets would be considered an error by the XML parser.
<CMD>
<![CDATA[ net send &{Local_Time.Timestamp}  ]]>
</CMD>
tags.
<AUTOSOPT>
This is required if an action <CMD> is specified. It defines the action command execution options, WHEN (X), FREQUENCY (Y), WHERE (Z). The default is NNN:

WHEN= Optional. "Y" to run the command for each item; or "N" to run the command on only the first row of data returned that meets the situation criteria. If the attribute group returns multiple rows of data and more than one row satisfies the condition, you can choose to issue the command on only the first row that meets the criteria or once for each row that meets the criteria. Default: "N".
FREQUENCY= Optional. "Y" to issue the command every time the situation evaluates to true; or "N" to issue the command when the situation is true, but not again until the situation evaluates to false, followed by another true evaluation. Default: "N".
WHERE= "N" to run the command at the agent. Default: "N" Because there is only one possible setting for "where", you do not need to include it in the AUTOSOPT element.
<AUTOSOPT When="Y" Frequency="Y" />
<DISTRIBUTION>

Required for products with subnodes (subagents). Specifies a managed system name or a list of managed system names separated by a semi-colon (;). There is no default value.

If you are using the <HISTORY> tag, nest the <DISTRIBUTION> tag within <HISTORY>.

<LSTDATE>

Optional. Situation last updated timestamp. If it is unspecified then the current data time is automatically generated. The format is CYYMMDDHHMMSSmmm (as in 1100715074501000 for July 15, 2010 at 07:45:01) where:

C = Century (1 for 21st)

Y = Year

M = Month

D = Day

H = Hour

M = Minute

S = Second

m = millisecond

<LSTUSRPRF>
Optional. This is the ID of the user who last updated this situation definition. If it is unspecified then the current logon user ID is used. Example:
<LSTUSRPRF>SYSADMIN</LSTUSRPRF> 
<LSTRELEASE>
Optional. Specifies the situation version. Example:
<LSTRELEASE>V622</LSTRELEASE> 
<SITINFO>
Optional. Defines the situation qualifiers for EIF events. Enclose in the <![CDATA[ ]]> element. Alternatively, it defines qualifiers for EIF events using parameters. Multiple qualifiers are delimited by a semicolon (;).

ATOM= Optional. For multiple-row attribute groups. This is the catalog COLUMN name to use as the display item, which causes an event to be generated for each subset of rows with the same display item value.
COUNT= Optional. This is called "situation persistence" in the Tivoli Enterprise Portal. Specify the number of intervals that the situation must remain true before an event is opened. Valid values are positive numbers greater than 0.
SEV= Optional. The severity to assign to the EIF event: Fatal, Critical, Warning, Minor, Harmless, Informational, or Unknown.
TFWD=[Y|N] Optional. Y is the default. If you want to send only SNMP alerts and no EIF events, set this attribute to N.
TDST= Optional. Specify one or more EIF receiver destinations to send the event to. You can enter up to five valid destination server IDs, each separated by a comma (,). Valid destinations are defined in the pc_eventdest.xml file. If no TDST parameter is specified, the EIF event is sent to all default event destinations defined (destination entries with a default="Y" setting) in the event destination configuration file.
Examples:
<SITINFO><![CDATA[SEV=Fatal;~;]]></SITINFO>
<SITINFO><![CDATA[SEV=Critical;TFWD=Y;TDST=1,3;]]></SITINFO>
<SITINFO><![CDATA[SEV=FATAL;COUNT=2;ATOM=NTEVTLOG.COMPUTER;]]></SITINFO>
<HISTORY>
Optional. Use the history element to specify each attribute group that you want to collect historical data for. The agent does not support multiple <HISTORY> specifications for the same TABLE.

TABLE= Required. This parameter specifies the application attribute group name.
EXPORT= Optional. This parameter specifies the interval in minutes for exporting historical data to the Tivoli Data Warehouse. The minimum export interval is 1 minute and the maximum is 1440 (24 hours). Valid export intervals are 1, 5, 15, 30, and values divisible by 60; an interval greater than 60 could be 120, 180, 240, and so on, up to 1440. The export interval must also be divisible by the INTERVAL parameter value. If you enter an invalid value, no historical data is collected nor exported for the specified attribute group. Default: none.
Note: If used in conjunction with the USE=A parameter, the following export integers are valid: 1, 2, 3, 4, 5, 6, 10, 12, and 15.
INTERVAL= Optional. This parameter specifies the historical data collection interval in minutes. The minimum collection interval is 1 minute and the maximum is 1440 (24 hours). Valid intervals are values that divide evenly into 60 or are divisible by 60: an interval below 60 could be 1, 2, 3, 4, 5, 6, 10, 12, 15, 20, and 30; an interval greater than 60 could be 120, 180, 240, and so on, up to 1440. If you enter an invalid value, no history is collected for the specified attribute group. Default:"15".
INTERVALUNIT= Optional. This parameter specifies the INTERVAL parameter time unit. The valid definitions are M (minutes) or S (seconds). When S is specified, the INTERVAL parameter value is interpreted as seconds and the valid value range is between 1 and 60. This parameter must be divisible by 60. In addition, S is only allowed in conjunction with parameter USE=A, otherwise, the history specification is rejected. Default: "M".
RETAIN= Optional. Retain defines the short-term history data retention period in hours. The default is 24 hours and the minimum retention period is one hour. There is no limit other than that imposed by storage space on the computer. After the retention limit has been reached, the oldest data samples are deleted as new samples arrive. Default: "24".
Specify "0" to delete the short-term history file after the data has been exported to a comma-separated (CSV) file that is used for analytic usage.
USE= Optional. The parameter defines special history data disposition. It is only valid when defined in conjunction with the EXPORT parameter, otherwise it is ignored. Currently, the only valid definition is A (analytic). Default: none.

In private situations use only external names (same as display names). Private situations using internal names fail. Examples:

The Windows OS agent collects NT_System table data every 15 minutes and maintains 96 data rows (four times per hour for 24 hours) in the history file.
<HISTORY TABLE="NT_System" />
The UNIX OS agent collects System table data every 5 minutes and maintains 3 days of short-term history.
<HISTORY TABLE="System" Interval="5" RETAIN="72"  />
The Windows OS agent collects NT_Logical_Disk table data every minute.
<HISTORY TABLE="NT_Logical_Disk" INTERVAL="1"  />
The <DISTRIBUTION> element is required for subnode environments. For example, the Universal agent collects TS2TCPIOQ00 table data every 10 minutes and maintains 1 day of short-term history on the subnode named SYSGTCPIOQ:TS200.
<HISTORY TABLE="TS2TCPIOQ00" INTERVAL="10" RETAIN="24" >
<DISTRIBUTION>SYSGTCPIOQ:TS200</DISTRIBUTION>
</HISTORY>
The Linux OS agent collects KLZ_Disk table data every 5 minutes with the data exported every 15 minutes.
<HISTORY TABLE="KLZ_Disk" INTERVAL="5" EXPORT="15" />
The Windows OS agent collects NT_Logical_Disk table data every thirty seconds and exports to the Warehouse Proxy agent every minute. The agent maintains one hour of short term history data in the local binary file. This history collection is designated for a stream analytic application.
<HISTORY Table="NT_Logical_Disk" Interval="30" IntervalUnit="S" 
  Retain="1" Export="1" Use="A" /> 
<WAREHOUSE>
Optional. Use the warehouse element to specify the location of the Warehouse Proxy agent to which historical data is exported. The agent does not support multiple <WAREHOUSE> specifications.
LOCATION=

This parameter specifies the location of each Warehouse Proxy agent to which historical data is exported. A primary location and multiple secondary locations can be specified with each separated by a semicolon (;). This location is only used by the agent when it has full autonomy and the KHD_WAREHOUSE_LOCATION parameter is not specified.

Specify a registered listening address of the Warehouse Proxy agent that will transfer historical data from the agent to the Tivoli Data Warehouse. The syntax is family protocol:network address[port number]. Review the warehouse proxy agent’s RAS1 trace log to determine the registered addresses.
The following RAS1 log excerpt shows the warehouse proxy agent registering a listening address:
khdxrpcr.cpp,621,"register_interface") Registering 
   "Candle_Warehouse_Proxy": ip.pipe:#9.44.255.253 [63358]
In order for historical data to be successfully exported, the monitoring agent must have the same communications protocol enabled that was specified for the warehouse proxy location. See "Monitoring your operating system via a System Monitor Agent" in the IBM Tivoli Monitoring Installation and Setup Guide for more information on the KDC_FAMILIES_OVERRIDE parameter.
Examples:
<WAREHOUSE LOCATION="ip.pipe:DEPT-XP[63358]" />
<WAREHOUSE LOCATION="ip.pipe:#9.44.255.253[63358]" />
Parent topic:
Private situations
Related reference:

Private history
Agent Service Interface - History
Agent Service Interface - Situations
IBM Tivoli Monitoring Command Reference
UTF-8 encoded XML files

+
Search Tips | Advanced Search

SCAL (Scale)	Integer comparison value (example used is 5000)
Not defined (0)	5000
1	Seen as 500 or 500.0 but represents 5000
2	Seen as 50 or 50.00 but represents 5000
3	Seen as 5 or 5.000 but represents 5000