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

IBM Tivoli Monitoring, Version 6.3 Fix Pack 2

Private history

Private history is the collection and short-term storage of data from a local monitoring agent. Define historical collection in a private situation configuration file for an agent, then use the Agent Service Interface to view the short-term history.

Private history is configured in the private situation configuration file

Local historical data collection is defined in the local private situation configuration file for each attribute group that you want to save historical data for. You can define private history with or without private monitoring situations. There can be only one active history data collection per application table (attribute group).

Use the <HISTORY> tag to specify each attribute group that you want to collect historical data for. Optionally, you can use the EXPORT parameter to specify an interval in minutes for exporting data to the Tivoli Data Warehouse. You can also export data for analytical consumption using the USE parameter.

Use the <WAREHOUSE> tag to specify a Warehouse Proxy agent to which historical data is exported.

See Private situation XML specification.

Agent Operation Log

All XML validation error messages are saved to the Agent Operation Log. The private history is completely separate and independent of historical data collection and the Tivoli Data Warehouse configuration within IBM Tivoli Management Services. Each private short-term history table data resides in its own history binary file.

Short-term history file names

The table name for an attribute group is also the history binary file name prefixed with PVTHIST_; one unique history binary file per table. As part of the private history configuration, you can set the RETAIN attribute to manage the history file size. You can configure an alternative private history file location with the CTIRA_HIST_DIR agent configuration parameter.

Short-term history file directory

The agent outputs all private history files to this subdirectory:

  • <install_dir> \TMAITM6\logs

  • <install_dir>/<arch>/<pc>/hist

You can configure an alternative private history file location with the CTIRA_HIST_DIR agent configuration parameter.

Short-term history file maintenance

The short-term history file conversion utilities, such as krarloff (KPDXTRA on z/OS), are provided to move data out of the historical files to delimited text files.

z/OS considerations

The Persistent Data Store (PDS) facility of the Tivoli Enterprise Monitoring Server on z/OS provides a mechanism for Tivoli Monitoring applications to access historical data in the same manner as SQL table data. OMEGAMON XE products leverage the PDS to store and retrieve historical data through the PDS component without use of Tivoli Management Services.

The PDS dictionary contains application table definitions.

  • Each table is identified by an application name, usually the application product code, table name, and assigned file group.

  • Table column definitions follow the table definition and include column name, data type, and data length. Table columns are related to the table using the same identifier.

The following sample PDS dictionary table definition is from the Tivoli OMEGAMON XE for Mainframe Network product KN3 table KN3BPG: 

    CREATE ID=N303 APPL=KN3      TABLE=KN3BPG     GROUP=KN3
ADDCOL ID=N303 COL=TMZDIFF    TYP=INTEGER    LEN=4    REQ
ADDCOL ID=N303 COL=WRITETIME  TYP=CHARACTER  LEN=16   BIT=72   REQ
ADDCOL ID=N303 COL=ORIGINNODE TYP=CHARACTER  LEN=32   REQ
ADDCOL ID=N303 COL=SYSID      TYP=CHARACTER  LEN=4    REQ
ADDCOL ID=N303 COL=TIMESTAMP  TYP=CHARACTER  LEN=16   REQ
ADDCOL ID=N303 COL=CATDESC    TYP=INTEGER    LEN=2    REQ
ADDCOL ID=N303 COL=CATPCT     TYP=INTEGER    LEN=4    REQ
ADDCOL ID=N303 COL=POOLNAME   TYP=CHARACTER  LEN=4    REQ
ADDCOL ID=N303 COL=CATEGORY   TYP=INTEGER    LEN=4    REQ
ADDCOL ID=N303 COL=SAMPLES    TYP=INTEGER    LEN=4    REQ
ADDCOL ID=N303 COL=INTERVAL   TYP=INTEGER    LEN=4    REQ

A table belongs to a PDS group and a number of VSAM files are allocated for a PDS file group for storing table data. The PDS OVERRIDE statement can be used to modify the table or group assignment (or both), and properties. The KN3 group specification is illustrated here: 

    OVERRIDE TABLE=KN3BPG APPL=KN3 WRAP=0 GROUP=KN3
GROUP=KN3 FILE=DSN:CCAPI.COMMON.NV.CIDSSP13.RKN3HIS3
GROUP=KN3 FILE=DSN:CCAPI.COMMON.NV.CIDSSP13.RKN3HIS2
GROUP=KN3 FILE=DSN:CCAPI.COMMON.NV.CIDSSP13.RKN3HIS1

The PDS stores table data using the application name, table name, WRITETIME, and any indexed columns as the VSAM file key. For Private History, using KN3BPG table – VTAM_Buffer_Usage_By_Category as an example, the following two configuration steps are required:

  1. Add application tables that require history data collection as new tables to PDS dictionary, in data set RKANPARU member KN3PDICT:

    1. Make a copy of the KN3BPG table definition.

    2. Change TABLE=KN3BPG to TABLE=ZN3BPG.

    3. Change ID=N303 to a unique ID (for example, N399).

  2. Add application tables OVERRIDE statement in data set RKANPARU member KN3PG.

    1. Copy the table KN3BPG OVERRIDE statement, if any.

    2. Change TABLE=KN3BPG to TABLE=ZN3BPG.

After completion of the two configuration steps, Private History can be configured and retrieved by adding the following information to <pc>_situations.xml as shown in this example: 

    <PRIVATECONFIGURATION>
 <HISTORY TABLE="VTAM_Buffer_Usage_By_Category" Interval="15" Retain="24" />
</PRIVATECONFIGURATION>

Service Interface Request example: 

    <HISTREAD>
  <SQLTABLE>
    <TABLENAME>KN3BPG</TABLENAME>
    <FILTER><![CDATA[ *VALUE WRITETIME  *GE 1090728020000000 *AND 
      *VALUE WRITETIME  *LE 1090728080000000]]&gt;</FILTER>
    <OUTLIMIT>5000</OUTLIMIT>
  </SQLTABLE>
</HISTREAD>

Both enterprise- and private history table data are stored and read by the PDS from the same VSAM datasets using the unique key. Alternatively, you can assigned private history to its own PDS file group and allocate separate VSAM dataset for the private history group.


Parent topic:

Agent-based services

Related reference:

Private situation XML specification
Agent Service Interface - History
Convert short-term history files to delimited flat files

+

Search Tips   |   Advanced Search