Configuration parameters for OMEGAMON monitoring agents as a data source

OMEGAMON® runtime environment member RKANPARU(KAYOPEN) configures the collection tasks of OMEGAMON monitoring agents. The member contains configuration parameters that select collections and set their destinations: the OMEGAMON persistent data store (PDS), OMEGAMON Data Broker, both, or none.

Collection tasks send attributes to the PDS or OMEGAMON Data Broker — Figure 1. OMEGAMON Data Provider collection configuration parameters control where attributes are sent

Selecting versus creating collections

These parameters select collections; they do not create collections.

Historical collections are a prerequisite for using OMEGAMON Data Provider. Before configuring OMEGAMON Data Provider, you need to create historical collections.

To create historical collections, you use the OMEGAMON enhanced 3270 user interface (e3270UI) or the Tivoli® Enterprise Portal (TEP). For more information about creating historical collections, see the OMEGAMON documentation for e3270UI and TEP.

Tip: You can specify these parameters to select collections before you create the corresponding collections. Configuring these parameters first means that, when you create the collections, collection tasks immediately send the attributes to the appropriate destinations.

Format

broker:
  name: <string>
collections:
  - product: k<pp> # Product code (example: km5)
    table: <table_name>
    interval: <minutes> # 0 matches any interval
    destination: # Either or both
      - pds
      - open
  - ... # More collections

The OMEGAMON Data Provider collection configuration member is a YAML document. The configuration parameters and their values conform to YAML syntax.

Tip: To check your configuration parameters, use the OMEGAMON Data Provider configuration validator.

Parameter names and values are case-insensitive, with one exception: the broker name is case-sensitive.

Character encoding

Collection tasks use EBCDIC code page 1047 to interpret the characters of the configuration member.

The code page is significant only if you use characters outside of the invariant subset of EBCDIC: characters that have different byte values in different EBCDIC code pages. For example, square brackets ([ ]) have different byte values in EBCDIC code pages 037 and 1047.

If you do use such characters, then when you edit the configuration member on z/OS®, ensure that your terminal code page is set to EBCDIC code page 1047. For example, in your terminal emulator settings. Otherwise, you risk introducing byte values that your terminal displays as one character but that represents a different character when interpreted using EBCDIC code page 1047.

Tip: To avoid such code page issues, only use characters in the invariant subset of EBCDIC. In particular, do not use square brackets.

To avoid square brackets in YAML, use the block sequence YAML syntax shown in this documentation, not flow sequences. Block sequences are delimited by newlines and hyphens, whereas flow sequences are enclosed in square brackets.

Location

If you choose to specify this optional configuration member, then it must be member name KAYOPEN in the RKANPARU library of your OMEGAMON runtime environment (RTE).

If you omit this member, then OMEGAMON Data Provider is dormant and attributes from historical collections are sent to PDS only.

Attention: The KAYOPEN member is not managed by PARMGEN or Monitoring Configuration Manager. Some actions of PARMGEN and Monitoring Configuration Manager, such as the GENERATE action of Monitoring Configuration Manager, delete RKANPARU library members. PTF UJ93077 for APAR OA64681 (2Q23) excludes members with the name pattern KAY*, such as KAYOPEN, from being deleted. If your site does not yet have that PTF applied, then you must maintain your primary copy of KAYOPEN in a different location of your choice and, after each GENERATE action, copy KAYOPEN to the RKANPARU library.

A sample member is supplied in TKANSAM(KAYOPEN).

Parameter descriptions

broker

Contains a single child key:

name

The name of the Zowe™ cross-memory server that runs the OMEGAMON Data Provider to which you want to send data.

This name is the value of the NAME runtime parameter of the JCL EXEC statement for the KAYSIS01 program (corresponding default procedure and job name: KAYSIS01).

Example value: ODP_BROKER

collections

Specifies a block sequence of historical collections. Each entry in the sequence is marked by a dash and space.

Each entry selects a historical collection that you have created in OMEGAMON and specifies destinations for that collection.

Each entry uses a combination of three values to select a historical collection: product code, table name, and collection interval.

To send data from a collection to OMEGAMON Data Broker, you must select the collection and specify the destination open.

product

The 3-character kpp product code of the monitoring agent that owns the table.

table

The table name. For example, ascpuutil (Address Space CPU Utilization).

interval

The collection interval in minutes or the special value 0 (zero).

The value 0 acts as a wildcard; it selects all historical collections for the table, regardless of collection interval.

Examples of minute values:

1: Every minute
5: Every 5 minutes
15: Every 15 minutes
30: Every 30 minutes
60: Every hour
1440: Once per day

To select a collection, either specify the wildcard value 0 or the number of minutes that matches the specific collection interval.

For example, to select a collection that has a collection interval of 1 day, specify interval: 1440.

Specifying interval: 0 offers flexibility: it means that you can change the collection interval of a collection without having to specify that different interval value here and then restart or modify running OMEGAMON monitoring agents.

If you have multiple collections for the same table, but with different collection intervals, then you can choose to send them all to the same destinations with a single entry that specifies interval: 0, or you can specify multiple entries with specific collection intervals.

destination

Specifies a sequence of destinations for the table.

The sequence can contain either or both of the following values:

open: Send data from this collection to OMEGAMON Data Broker.
pds: Send data from this collection to the persistent data store.

If you want to view attributes from this collection in the OMEGAMON enhanced 3270 user interface (e3270UI) or the Tivoli Enterprise Portal (TEP) user interface, or store the attributes in Tivoli Data Warehouse, then you must include pds as a destination.

To pass attributes directly through to OMEGAMON Data Broker without storing them on disk (in the PDS), specify open as the only destination.

For an overview of the choice of destinations, see OMEGAMON monitoring agents as a data source for OMEGAMON Data Provider.

You can specify destinations either in a block sequence, delimited by line breaks and hyphens:

destination:
  - open
  - pds

or in a flow sequence, delimited by commas and wrapped in square brackets:

destination: [open, pds]

Precedence of entries that select the same collections

If more than one entry in the collections sequence specifies the same combination of product name, table name, and collection interval, then the last entry takes precedence. That is, collections will be sent to the destinations specified by the last entry.

Entries with a specific interval value take precedence over entries with the wildcard interval value of 0.

Default destinations of unselected collections

The following conditions determine the default destination for collections that are not selected by any of the entries in the collections sequence:

Condition	Destination
No entries select that combination of product code and table name.	PDS only.
One or more entries select that combination of product code and table name, but none of those entries select that collection interval.	None. The collection is discarded. Data from that collection is not sent to either the PDS or OMEGAMON Data Broker.

Applying configuration changes

After editing this configuration member, you need to apply changes to the jobs that run the affected OMEGAMON monitoring agents.

You must either restart the jobs or enter an MVS™ MODIFY system command to reload their collection configuration.

Example: All collection intervals to both destinations

The following example selects collections for two tables; both tables are from the z/OS monitoring agent, product code km5.

broker:
  name: ODP_BROKER
collections:
  - product: km5
    table: ascpuutil
    interval: 0
    destination:
      - open
      - pds
  - product: km5
    table: km5msucap
    interval: 0
    destination:
      - open
      - pds

This example selects all collections for these tables, regardless of collection interval.

This example sends all selected collections to both the PDS and OMEGAMON Data Broker.

Collections for all other tables are sent to PDS only.

Example: Specific collection intervals

The following example only selects collections with the cited collection intervals.

broker:
  name: ODP_BROKER
collections:
  - product: km5
    table: ascpuutil
    interval: 1
    destination:
      - open
      - pds
  - product: km5
    table: km5msucap
    interval: 5
    destination:
      - open
      - pds

For table ascpuutil, this example only selects a collection that has a collection interval of 1 minute.

For table km5msucap, this example only selects a collection that has a collection interval of 5 minutes.

Collections for tables ascpuutil and km5msucap with other collection intervals are discarded.

Collections for all other tables are sent to PDS only.

Example: Multiple specific collection intervals

The following example sends collections for the same table, but with different collection intervals, to different destinations.

broker:
  name: ODP_BROKER
collections:
  - product: km5
    table: ascpuutil
    interval: 1
    destination:
      - open
  - product: km5
    table: ascpuutil
    interval: 5
    destination:
      - pds

A collection for table ascpuutil with a collection interval of 1 minute is sent to OMEGAMON Data Broker only.

A collection for table ascpuutil with a collection interval of 5 minutes is sent to the PDS only.

Collections for table ascpuutil with other collection intervals are discarded.

Collections for all other tables are sent to PDS only.

Example: All collection intervals to the PDS but only a specific collection interval to OMEGAMON Data Broker

Suppose that you want collections for a table to be sent to the PDS regardless of collection interval. However, you only want a collection for that table to be sent to OMEGAMON Data Broker if the collection has a specific collection interval.

The following example demonstrates using the special interval value 0 to select all collection intervals, and then using a separate entry for the same table to override that behavior for a specific collection interval.

broker:
  name: ODP_BROKER
collections:
  - product: kc5
    table: kcpplx
    interval: 0
    destination:
      - pds
  - product: kc5
    table: kcpplx
    interval: 1 # Specific value takes precedence over wildcard (0)
    destination:
      - pds
      - open

All collections for CICS® (kc5) table kcpplx are sent to the PDS, regardless of collection interval.

A collection for that table with a collection interval of 1 minute is sent to OMEGAMON Data Broker.

Collections for all other tables are sent to PDS only.