PM/API Dynamic Data | Application Programming Reference | Teradata Vantage - 17.10 - PM/API Dynamic Data - Advanced SQL Engine - Teradata Database

Teradata Vantage™ - Application Programming Reference

Advanced SQL Engine
Teradata Database
Release Number
Release Date
July 2021
Content Type
Programming Reference
Publication ID
English (United States)

When you issue a request through the Monitor partition, current and dynamic data is reported. PM/API requests place data in a global repository (in memory), not in an intermediary spool file (on disk). AMP, PE, node, and session-level usage data are each collected in independent data collection global areas.

As a result, changes in the resource collection rate have no impact on session-level data, and vice versa. Any MONITOR request, except MONITOR VIRTUAL CONFIG, MONITOR PHYSICAL CONFIG, and IDENTIFY, may cause the memory repository to be updated on demand (specifically, once each collection period). All users share the data in the repository, which is used to generate responses to both queries and CONTINUE requests.

If, after issuing a PM/API request, the Monitor partition session returns an error parcel with empty error text, run the Database Initialization Program (DIP) option 1 (DIPERR), wait up to 60 minutes to reload the error text cache in the Monitor partition. After the error text cache is reloaded, the error parcels will have the proper error texts. For instructions on how to run DIP, see Teradata Vantage™ - Database Utilities, B035-1102.

Monitoring Rates

You should be aware of the rate at which your PM/API client application requests performance data. If a PM/API client application requests data more frequently than the corresponding data collection rate, an individual request could potentially include data from one collection period mixed in with data from a subsequent collection period initiated by a different MONITOR user because common global data is shared.

However, the impact need not be detrimental. The data collected from one request when compared with the next request may not show a change in resource usage. Follow the simple rule that the PM/API client application must request data at the same rate, or a less frequent rate, than the rate at which the database collects that data.

The monitoring rate is a PM/API collection rate that sets the interval in seconds at which resource usage data is collected within memory.

A physical monitoring rate is the same as a virtual monitoring rate.

There are significant differences in the way resource usage and session utilization data are collected and reported by the MONITOR partition. For details, see Data Collection and Collection and Logging Rates.

Session-Level Data

Session-level data is collected cumulatively. The collection period is used to limit the frequency of this update.

For example, if you set the SET SESSION RATE to 120 seconds and issue a MONITOR SESSION request every 120 seconds, session usage data is collected and cumulatively totaled every 120 seconds.

Session-level data is lost in the event of a system outage.

Data reported includes data for the beginning 120 seconds as well as for subsequent intervals.

For more information on how session usage data is collected, see System-Level Monitoring.

Resource Usage Data

Resource usage data is collected based on activity during a collection period and does not reflect cumulative data for a sequence of collection periods. For example, if you set the SET RESOURCE RATE to 120 seconds and issue a MONITOR VIRTUAL RESOURCE or MONITOR PHYSICAL RESOURCE request, resource usage data is collected at 120-second intervals.

If you do not examine the data within 120 seconds or enable resource usage tables for logging, it is lost when overwritten by data collected during the next 120-second collection interval.

Features of Using Resource Usage Data

Resource usage data features are:
  • Access is via SQL, not C or some other programming language
  • More detailed
  • Written to tables so past data values are available
  • Can be accumulated over a long period of time and can be used for the following:
    • Examining trends and patterns
    • Planning system upgrades
    • Deciding when to add new applications to heavily utilized systems
    • Building baseline resource usage profiles for operations

Logging Resource Usage Data

You can retain collected data for subsequent historical analysis by enabling one or more resource usage tables for logging. The table and type of PM/API request are listed below. For details on the resource usage tables and pre-defined report macros, see Teradata Vantage™ - Resource Usage Macros and Tables, B035-1099.

To control the resource usage logging option (for example, setting the logging rate and enabling one or more log tables or subtables), use the ctl utility. For instructions on using ctl, see Teradata Vantage™ - Database Utilities, B035-1102.

PM/API Request Table






ResUsageSldv (Storage Devices)





Collection and Logging Rates

You can control the rate at which resources are monitored (collected) and, if you enable resource logging, the interval at which a data row is to be inserted into the log table.

Setting Collection Rates

The following collection rates can be set:
  • Global session monitoring
  • Local session monitoring
  • Resource monitoring

For more information on these types of rates, see Data Collection.

Setting Logging Rates

You can enable logging of collected data into the resource usage tables. In this case, you also set a logging rate that specifies how often a data row is to be inserted.

Logging is not required to collect and retrieve current data, but it does preserve data that would otherwise be lost at the next collection interval.

If you decide to enable logging, set the logging rate. The resource logging rate, also referred to as the physical or virtual resource logging rate, sets the interval in seconds at which resource usage data is written to the resource usage tables (see Data Collection). The rate is saved on disk every time it is altered. Use the SET RESOURCE RATE request to set this rate (see SET RESOURCE RATE).

The resource logging rate:
  • Can be set within the range of 0 and 3600 seconds.
  • With a value of zero indicates that logging is not being performed.
  • Returns the value ResLogging in the MONITOR PHYSICAL SUMMARY and MONITOR VIRTUAL SUMMARY requests.
A physical resource logging rate is the same as a virtual resource logging rate.