13.2.9 Applying a definition file for custom monitoring items for JP1/ITSLM linkage

Organization of this subsection

(1) Editing and applying a definition file for custom monitoring items
(2) Definition file for custom monitoring items (monitoringitems.cfg)

(1) Editing and applying a definition file for custom monitoring items

Open the definition file for custom monitoring items (monitoringitems.cfg) in a text editor.
Edit the file.
Save and close the file.
Log on to JP1/ITSLM.
Set configuration information in JP1/ITSLM.

Change the configuration information to synchronize the monitoring items between PFM - Manager and JP1/ITSLM.
Open the Monitor settings window and set the monitoring items in JP1/ITSLM.

The monitoring item definitions are applied.

Make sure that the contents of the edited definition file for custom monitoring items have been applied correctly. If not, a specified value might be wrong. Check the common message log and the log output by JP1/ITSLM.

For details on how to set configuration information, see the chapter that describes how to set configuration information for monitored services (linking with Performance Management) in the manual Job Management Partner 1/IT Service Level Management.

To Page Top

(2) Definition file for custom monitoring items (`monitoringitems.cfg`)

(a) Storage location of the definition file for custom monitoring items

When PFM - Manager is on a physical host

In Windows:: installation-folder\ITSLM\
In UNIX:: /opt/jp1pc/ITSLM/

When PFM - Manager is on a logical host

In Windows:: environment-directory\jp1pc\ITSLM\
In UNIX:: environment-directory/jp1pc/ITSLM/

(b) Input rules for writing a definition file for custom monitoring items

The following rules apply to the definition file for custom monitoring items (monitoringitems.cfg):

Specify setting values in the format label-name=setting-value.
All blank characters (spaces, tabs, vertical tabs, or form feed characters) before or after the label name or setting value are ignored.
Character strings beginning with a hash mark (#), excluding leading blank characters, are treated as comments.
CR, LF, or CRLF are accepted as line feed codes, but you must use the same line feed code consistently within the file. If you use more than one type of line feed code, errors might occur in items that are actually correct. Also, the line number indicating the location of an error in an error message might differ from the line number displayed in an editor.
Lines consisting only of a line feed code, or of a line feed code preceded by a blank character, are ignored.
The value of an optional label is assumed to be unspecified if you omit the entire label or if you write the label name without writing the value. In the latter case, the label name must be followed by an equals sign (=).
If something does not follow the input rules, such as a [[Monitoring Item]] subsection without an [Agent] section, the entire definition file for custom monitoring items is invalid.
If the Product label is missing or if a value is unspecified in an [Agent] section, the [Agent] section itself and all [[Monitoring Item]] subsections under it are invalid.
If a label is written more than once in a [[Monitoring Item]] subsection, the [[Monitoring Item]] subsection is invalid.
If a mandatory label is missing or if a value is incorrectly specified in a [[Monitoring Item]] subsection, the [[Monitoring Item]] subsection is invalid.
Labels can be written in any order within a [[Monitoring Item]] subsection. Changing their order has no effect on operation.
If the values set for a PFM - Agent or PFM - RM type, data model version, record, and field match the definition of a default monitoring item, the default monitoring item is ignored and only the values set for the custom monitoring item are valid.
If the same definition is set multiple times for a PFM - Agent or PFM - RM type, data model version, record, and field, only the first definition closest to the top of the file is valid.

(c) Example of a definition file for custom monitoring items

The following is an example of how to write a definition file for custom monitoring items.

ITSLM Monitoring Items Definition File Version=0001
ITSLM Monitoring Items Definition File Code=Shift_JIS
[Agent]
Product=T8.0                   --- Agent for Platform (Windows) 8.0
[[Monitoring Item]]
Record=PI                                 --- System Overview record
Field=PCT_PHYSICAL_MEMORY               --- % Physical Mem field
Key Field=               --- Single instance records can be omitted
Display Name.ja=Physical memory usage
Display Name.en=Physical Mem Usage
Display Unit.ja=        --- When unspecified, the value of Display 
                              Unit.en is used.
Display Unit.en=%
Threshold=High
[[Monitoring Item]]     --- Write multiple monitoring items 
                               as required
Record=PI_LOGD
Field=PCT_DISK_USAGE
Key Field=INSTANCE      --- Mandatory for multi-instance record
      :
[Agent]                  --- Write the product ID and data
                              model version of the next Agent
Product=U7.8
[[Monitoring Item]]
Record=PI
Field=PCT_PHYSICAL_MEMORY
      :

(d) Format of a definition file for custom monitoring items

Table 13‒4: Format of a definition file for custom monitoring items (`monitoringitems.cfg`)
Item			Description
Section	Subsection	Label name	Description
--	--	`ITSLM Monitoring Items Definition File Version`	Syntax version of the monitoring items definition file. Setting value: `0001` Specification: Mandatory
--	--	`ITSLM Monitoring Items Definition File Code`^#4	Character encoding in which the monitoring items definition file is written. Setting value: One of the following: `Shift_JIS`: Double-byte characters (SJIS) or single-byte characters (7-bit ASCII character set) `EUC-JP`: Double-byte characters (EUC) or single-byte characters (7-bit ASCII character set) `UTF-8`: Double-byte characters (UTF-8) or single-byte characters (7-bit ASCII character set) `C`: Single-byte characters (7-bit ASCII character set) only. `Display` `Name.ja` and `Display` `Unit.ja` settings are ignored. Specification: Mandatory
`[Agent]`	--	--	Represents the section name and cannot be changed. Write a separate section for each PFM - Agent and PFM - RM product ID and data model version.
	--	`Product`	PFM - Agent or PFM - RM type or data model version Setting value: `product-ID` `data-model-version` `product-ID`: Specify in upper-case characters the product ID of the agent for which you are defining an alarm. `data-model-version`: Specify the version and revision numbers in decimal notation joined by a period (`.`). Specification: Mandatory^#1
	`[[Monitoring Item]]`	--	Represents the subsection name and cannot be changed. Write a separate subsection for each monitoring item you are defining. A maximum of 54 monitoring items can be defined for each product ID and data model version. If you specify more than 54 valid monitoring items, the 55th and subsequent definitions will be ignored.
		`Record`	The record to be monitored Setting value: Specify the record ID^#2 of the record to be monitored in 1 to 7 single-byte characters. Specification: Mandatory
		`Field`^#3	The record field to be monitored. If the same record and field is specified more than once, the definition closest to the top of the file will be used. Setting value: Specify the PFM - Manager name of the monitored field in 1 to 50 single-byte characters. Specification: Mandatory
		`Key Field`^#3	Information that uniquely identifies the collected records. You can specify key fields only for multi-instance records. If specified for a single-instance record, the value will be ignored. Setting value: Specify the PFM - Manager name of the field to be used for filtering. You can specify a maximum of 10 key fields delimited with commas (`,`). Blank characters before or after a comma are ignored. Specify the PFM - Manager name of each field in 1 to 50 single-byte characters. Specify the ODBC key field of the record. Specification Single-instance record: May be omitted (ignored if specified) Multi-instance record: Mandatory Note Suppose that the ODBC key fields of the `PD_PDI` record of PFM - Agent for Platform (Windows) is `PD_PDI_INSTANCE`,`PD_PDI_ID_PROCESS`. As the PFM - Manager name of this field, specify `INSTANCE`,`ID_PROCESS`.
		`Display Name.ja`	Monitoring item name (Japanese) to be displayed in JP1/ITSLM Setting value: Specify the display name (Japanese) in 1 to 64 bytes, using single-byte or double-byte characters. Specification: If omitted, the character string specified for `Display` `Name.en` is used.
		`Display Name.en`	Monitoring item name (English) to be displayed in JP1/ITSLM Setting value: Specify the display name (English) in 1 to 64 single-byte characters. Specification: Mandatory
		`Display Unit.ja`	Monitoring item unit (Japanese) to be used in JP1/ITSLM Setting value: Specify the unit (Japanese) in 1 to 32 bytes, using single-byte or double-byte characters. Specification: If omitted, the character string specified for `Display` `Unit.en` is used.
		`Display Unit.en`	Monitoring item unit (English) to be used in JP1/ITSLM Setting value: Specify the unit (English) in 1 to 32 single-byte characters. Specification: Mandatory
		Threshold	Threshold type Setting value: Specify either of the following: `High`: A threshold where a larger value indicates a decline in performance or an abnormality. `Low`: A threshold where a smaller value indicates a decline in performance or an abnormality. Specification: Mandatory

Legend:: --: Not applicable.

The specifiable range of value is subject to the following conditions:

PFM - Agent and PFM - RM must be version 10-00 or later.
For the PFM - Agent and PFM - RM you are defining, you must specify the latest data model version that can be used with alarms and reports.

The following example illustrates this condition.

PFM - Agent for Sample is not a real product.

Assume the following product versions.

Host A

PFM - Agent for Sample version 1000: Data model version 8.0 (where data model versions 3.0 to 8.0 can be used with alarms and reports)

Host B

PFM - Agent for Sample version 1005: Data model version 8.2 (where data model versions 3.0 to 8.2 can be used with alarms and reports)

In this example, data model version 8.0 is required to link with PFM - Agent for Sample on host A, and data model version 8.2 is required to link with PFM - Agent for Sample on host B. (Linkage cannot be established if data model version 3.0 or 8.0 is specified because 8.2 is the latest data model version of PFM - Agent for Sample on host B.)

For details on record IDs, see the appropriate PFM - Agent or PFM - RM manual.

Field: Only a numerical field can be defined as a monitoring item linked with JP1/ITSLM.
Key Field: Only an exact-match character string comparison can be defined as a key field for filtering.

Table 13-5 Specifiable data types (Field and Key Field) describes which field data types can be specified for monitoring items and key fields.

If the specified character encoding differs from the encoding used to write the file, text display in JP1/ITSLM might be garbled and correct items might be identified as errors. Also, the line number indicating the location of an error in an error message might differ from the line number displayed in an editor.

Table 13‒5: Specifiable data types (Field and Key Field)
Data type		Size	JP1/ITSLM linkage		Remarks
Field	C and C++	Size	Field	Key Field	Remarks
char	char	1	Y	Y	--
char(n)^#	char[ ]	n	N	Y	A non-numeric cannot be specified as a monitoring item.
double	double	8	Y	N	A floating point number cannot be specified as an exact-match key.
float	float	4	Y	N	A floating point number cannot be specified as an exact-match key.
long	long	4	Y	Y	--
short	short	2	Y	Y	--
string	char	1	Y	Y	Not intended as numeric type, but can be used as numeric type when one byte in length.
string(n)^#	char[ ]	n	N	Y	A non-numeric cannot be specified as a monitoring item.
time_t	unsigned long	4	Y	N	Elapsed time in milliseconds cannot be specified as an exact-match key.
ulong	unsigned long	4	Y	Y	--
utime	utime (structure)	8	N	N	A structure cannot be specified as a monitoring item or key field.
word	unsigned short	2	Y	Y	--
(Not applicable)	unsigned char	1	Y	Y	--

Legend:

Y: Can be specified.

N: Cannot be specified.

--: Not applicable.

#:

Where n = 2.