SirTune data collection statements: Difference between revisions

Latest revision as of 21:03, 8 August 2017

An optional DD card (or FILEDEF under CMS) called SIRTUNEI allows users to specify characteristics of the reporting run and to customize which reports are requested and how they are ordered.

The configuration statements take the form of control cards. There can be only one SirTune configuration statement per line, there are no line continuations, and a line beginning with an asterisk character (*) is treated as a comment and ignored.

Available SirTune data collection configuration statements are described in the subsections that follow. The minimum abbreviation allowed for each statement is indicated with uppercase characters, while optional characters are indicated with lowercase. Optional statement parameters are enclosed in brackets ([]). Alternatives are separated with a vertical bar (|).

ALLComp

This statement specifies that SirTune should collect compilation data for all procedures; it is the inverse of the PRECOMP statement.

The default for a single user run (NUSERS=1) is that SirTune collects compilation data for all procedures. The default for a multi-user run (NUSERS>1) is that SirTune collects compilation data only for precompiled procedures. It is unnecessary to specify ALLCOMP in a single-user run since it is the default.

If ALLCOMP is not used explicitly in a multi-user run, or if it is overridden by the PRECOMP statement in a single-user run, the report generator can produce line-by-line breakdowns for precompiled Application Subsystem (APSY) procedures only. Using the ALLCOMP statement makes it possible for the reporting module to provide line-by-line breakdowns for all User Language procedures executed in the job.

Specifying the ALLCOMP statement can significantly increase the size of the sample data set, and in extreme cases, it can adversely affect the performance of an Online. Because of this, it is generally recommended that you use only the ALLCOMP option when running SirTune against a single-user batch job, or when running multi-user jobs that do a lot of processing in non-APSY or non-precompiled procedures.

Note: SirTune cannot provide line-by-line breakdowns for SOUL programs not contained in procedures, including inline procedures in CCAIN, IODEV3, or BATCH2 input streams, or those entered at a terminal without use of the editor.

AUTHorize userid1 [userid2] ...

This statement specifies the user IDs from whom SirTune should accept MODIFY commands (under MVS) or SMSG commands (under CMS). The default is that MODIFY or SMSG commands to SirTune are not accepted from any user ID.

Since MVS provides no information about the user issuing a MODIFY statement, the only AUTHORIZE statement that makes any sense under MVS is:

AUTHORIZE *

This indicates that SirTune will accept MODIFY commands from any user that has the privilege to issue a MODIFY command (either an operator at a console or a user in SDSF).

Under CMS, an arbitrary number of user IDs can be specified, and the IDs can contain wildcard characters. For example:

AUTHORIZE BART HOMER*

The statement above indicates that SirTune should accept SMSG commands from user ID BART and from any user ID that starts with the characters H O M E R. For more information on wildcards, see SirTune statement wildcards.

SIRTUNEI can contain an arbitrary number of AUTHORIZE statements. The AUTHORIZE statements are cumulative, so the user IDs specified on an AUTHORIZE statement are added to the list of user IDs specified by all previous AUTHORIZE statements.

For more information on the commands that can be issued via MODIFY or SMSG by authorized users, see SirTune MODIFY and SMSG commands.

CMSout vmid [ddname]

This statement has meaning only under CMS. It specifies the user ID of the virtual machine (vmid) running the SIRTUNED load module, and it specifies the DD name (ddname) that virtual machine is to use for the sample dataset. The default for vmid is SIRTUNED, and the default for ddname is the user ID of the virtual machine running SirTune.

For example, this statement indicates that there is a SIRTUNED service machine with user ID HOHO that should use DD name MARGE for the sample dataset:

CMSOUT HOHO MARGE

The CMSOUT statement makes it possible to run multiple SIRTUNED service machines, because it allows SirTune in each Model 204 service machine to indicate the user ID of its SIRTUNED service machine. This is not a generally recommended mode of operation, however, because of the extra overhead of running multiple virtual machines.

COLLect state [extra_data]

This statement makes it possible to increase the quantity of data collected by SirTune. While collecting extra data increases the size of the sample data set, it also makes it possible to produce extended reports.

The default for COLLECT in multi-user runs is COLLECT RUNG, which means that data is only collecting for running users (users consuming CPU), and no extra data is collected. The default for COLLECT in single-user runs is COLLECT ALLN BLKU DISKIO, which means that the only user for which data is not collected is waiting PSTs. Data is always collected for running users, regardless of the COLLECT statements in SIRTUNEI.

state is a list of one or more blank-delimited user states. SirTune will collect sample data for a user in any of the states indicated by COLLECT statements at the moment a sample is collected.

For example, if the following is specified, SirTune will collect sample data for any user that is swapping into or out of a server at the instant a sample is collected:

COLLECT SWPG

To be able to produce a report for a particular state, data must be collected for that state with SirTune. For example, if you want to produce a report for STATE SWPG, you can ensure the appropriate data will be collected by SirTune by placing this statement in SIRTUNEI:

COLLECT SWPG

For a discussion of available states and their meanings, see SirTune user states.

In addition to requesting that sample data be collected for users in specific states, it is also possible to request extra data to isolate the cause of certain wait types. The only valid values for extra_data are DISKIO and/or CFR.

Specifying DISKIO as a parameter on a COLLECT statement indicates that SirTune should collect data for every wait on Model 204 disk I/O. This data allows the reporting module to produce the DISKIO reports. These reports allow breakdowns of waits on Model 204 disk I/O by file, table, and groups of pages within tables.

Specifying DISKIO on a collect statement implies the BLKIN parameter. That is, this statement:

COLLECT DISKIO BLKIN

is functionally equivalent to this:

COLLECT DISKIO

Specifying CFR as a parameter on a COLLECT statement indicates that SirTune should collect data for users with "Critical File Resource" activity. Critical file resources are used to provide concurrency control among updating and retrieving operations on the same file. Contention on critical file resources can exacerbate performance problems, sometimes dramatically.

The CFR data allows the reporting module to produce the CFRROOT, STATE CFRHxxx, and STATE CFRBxxx reports. These reports allow breakdowns of:

The root causes of critical file resource waits
Activities that result in the holding of critical file resources

Since critical file resources are used to provide multi-user concurrency control, the CFR parameter is meaningless in a single-user run.

COLLECT statements are cumulative. That is, this sequence:

COLLECT SWPGI COLLECT BLKIN COLLECT BLKON

is functionally equivalent to this:

COLLECT SWPGI BLKIN BLKON

and it results in data being collected for all users in state SWPGI, BLKIN, or BLKON. There is no limit to the number of COLLECT statements in SIRTUNEI.

The first COLLECT statement in SIRTUNEI for a single-user run is treated as an override to the single-user default. That is, if the following is the first COLLECT statement in SIRTUNEI for a single-user run:

COLLECT RUNG

it would turn off data collection for all other user states in the single-user default and for DISKIO data.

EXClude [start_time end_time] [days_of_week]

This statement makes it possible to limit the times in which sample data is collected. Note that compilation data is always collected, whether or not sample data is being collected.

start_time and end_time can have the format HH, HH:MM, or HH:MM:SS, where HH represents an hour of the day, MM represents minutes, and SS represents seconds. The maximum allowable time is 24 or 24:00 or 24:00:00, which corresponds to midnight.

For example, the following indicates that no sample data should be collected from midnight through 8 AM every day of the week:

EXCLUDE 0 8

The following indicates that no sample data should be collected from 11:30 AM through 1:30 PM every day of the week:

EXCLUDE 11:30 13:30

The following indicates that no sample data should be collected from 30 seconds before 12 noon through 50 seconds after 1 PM every day of the week:

EXCLUDE 11:59:30 13:00:50

If start_time is greater than end_time, the times are assumed to wrap. For example, the following means that no sample data should be collected between 11 PM and 1 AM:

EXCLUDE 23:00 1:00

days_of_week is a blank-delimited list of days of the week. The following are valid days of the week, with the minimum abbreviations in uppercase:

SUNday
MONday
TUEsday
WEDnesday
THUrsday
FRIday
SATurday

For example, the following indicates that no sample data should be collected all day Sundays and Saturdays:

EXCLUDE SUNDAY SAT

The following indicates that no sample data should be collected from 6:30 PM through midnight on Mondays through Fridays:

EXCLUDE 18:30 24:00 MOND TUES WEDN THU FRIDAY

In addition to the days of the week, the following groupings are also available in a days_of_week list:

WEEKDay = Monday, Tuesday, Wednesday, Thursday, Friday
WEEKEnd = Saturday, Sunday
ALL = Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday

For example, the following indicates that no sample data should be collected all day Saturday through Sunday:

EXCLUDE WEEKE

The following indicates that no sample data should be collected on any day of the week:

EXCLUDE ALL

The following indicates that no sample data should be collected between 10 AM and 12 noon on Sunday, Saturday, and Monday:

EXCLUDE 10 12 WEEKEND MONDAY

The following indicates that no sample data should be collected between 11 PM and midnight on all days of the week:

EXCLUDE 23:00 24:00 ALL

Note that the statement above is identical to this:

EXCLUDE 23:00 24:00

If no INCLUDE or EXCLUDE statements occur in SIRTUNEI, sample data is collected as if INCLUDE ALL had been specified.

The order of INCLUDE and EXCLUDE statements in SIRTUNEI is important: If the first INCLUDE or EXCLUDE statement in SIRTUNEI is EXCLUDE, it is treated as if it were preceded by an INCLUDE ALL. That is, data will only not be collected over intervals explicitly indicated by EXCLUDE statements.

For example, if this is the only INCLUDE or EXCLUDE statement in SIRTUNEI:

EXCLUDE 0 9

sample data will be collected between 9 AM and midnight every day of the week. No data will be collected at other times. If SIRTUNEI contains the following sequence, data should be collected on Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday:

EXCLUDE WEEKEND INCLUDE SATURDAY

If SIRTUNEI contains the following sequence, data should be collected on every weekday from 8 AM to 5 PM and on Fridays from 10 PM to midnight:

EXCLUDE WEEKEND EXCLUDE 0 8 EXCLUDE 17 24 INCLUDE 22 24 FRIDAY

Note that there is no harm in including a range that has already been excluded. For example, the following

EXCLUDE 0:00 7:00 EXCLUDE 4:00 10:00

is the same as

INCLUDE 0:00 10:00

The INCLUDE/EXCLUDE statements are only honored if sampling is set to AUTO (automatic) mode, either by default or by a SAMPLE statement or a MODIFY or SMSG SAMPLE command. When sampling is in manual mode, INCLUDE/EXCLUDE statements have no effect.

Generally, you should use the INCLUDE/EXCLUDE statements to avoid collecting data for time intervals in which there is nothing interesting likely to be happening, that is, periods of low activity. The only real cost of this is the disk space and the minor amount of CPU consumed collecting this sample data.

If you are only interested in collecting data at peak hours, say 10 AM to 11:30 AM and 1:30 PM to 4 PM on weekdays, simply put the following in SIRTUNEI:

INCLUDE 10 5 WEEKDAY EXCLUDE 11:30 13:30

INClude [start_time end_time] [days_of_week]

This statement makes it possible to limit the times in which sample data is collected. Note that compilation data is always collected, whether or not sample data is being collected.

start_time and end_time can have the format HH, HH:MM, or HH:MM:SS where HH represents an hour of the day, MM represents minutes, and SS represents seconds.

The maximum allowable time is 24 or 24:00 or 24:00:00, which corresponds to midnight. For example, the following indicates that sample data should be collected from 8 AM through 6 PM every day of the week:

INCLUDE 8 18

The following indicates that sample data should be collected from 8:30 AM through 5:30 PM every day of the week:

INCLUDE 8:30 17:30

The following indicates that sample data should be collected from 10 seconds before 9 AM through 10 seconds after 5 PM every day of the week:

INCLUDE 8:59:50 17:00:10

If start_time is greater than end_time, the times are assumed to wrap. For example, the following means that sample data should be collected between 11 PM and 1 AM:

INCLUDE 23:00 1:00

days_of_week is a blank-delimited list of days of the week. The following are valid days of the week, with the minimum abbreviations in uppercase:

SUNday
MONday
TUEsday
WEDnesday
THUrsday
FRIday
SATurday

For example, indicates that sample data should be collected all day Mondays and Tuesdays:

INCLUDE MONDAY TUE

The following indicates that sample data should be collected from 8:45 AM through 5:45 PM on Mondays through Fridays:

INCLUDE 8:45 17:45 MOND TUES WEDN THU FRIDAY

In addition to the days of the week, the following groupings are also available in a days_of_week list:

WEEKDay = Monday, Tuesday, Wednesday, Thursday, Friday
WEEKEnd = Saturday, Sunday
ALL = Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday

For example, the following indicates that sample data should be collected all day Monday through Friday:

INCLUDE WEEKD

The following indicates that sample data should be collected all day on every day of the week:

INCLUDE ALL

The following indicates that sample data should be collected between 10 AM and 12 noon on Sunday, Saturday, and Monday:

INCLUDE 10 12 WEEKEND MONDAY

The following indicates that sample data should be collected between 11 PM and midnight on all days of the week:

INCLUDE 23:00 24:00 ALL

Note that the above statement is identical to this:

INCLUDE 23:00 24:00

If no INCLUDE or EXCLUDE statements occur in SIRTUNEI, sample data is collected as if INCLUDE ALL had been specified.

The order of INCLUDE and EXCLUDE statements in SIRTUNEI is important: If the first INCLUDE or EXCLUDE statement in SIRTUNEI is INCLUDE, it is treated as if it were preceded by an EXCLUDE ALL (that is, data will only be collected over intervals explicitly indicated by INCLUDE statements).

For example, if this is the only INCLUDE or EXCLUDE statement in SIRTUNEI:

INCLUDE 9 17

sample data should be collected between 9 AM and 5 PM every day of the week. No data should be collected at other times. If SIRTUNEI contains the following sequence:

INCLUDE WEEKDAY EXCLUDE TUESDAY THURSDAY

Data should be collected on Monday, Wednesday, and Friday. If SIRTUNEI contains the following sequence:

INCLUDE 8 17 TUESDAY EXCLUDE 11 14 INCLUDE 12 13 TUESDAY

Data should be collected on Tuesdays from 8 AM to 11 AM, 12 noon to 1 PM, and 2 PM to 5 PM.

Note: There is no harm in INCLUDE'ing a range that has already been included. For example, the following range
INCLUDE 9:00 13:00 INCLUDE 12:00 17:00

is the same as

INCLUDE 9:00 17:00

The INCLUDE/EXCLUDE statements are only honored if sampling is set to AUTO (automatic) mode, either by default, or by a SAMPLE statement or a MODIFY or SMSG SAMPLE command. When sampling is in manual mode, INCLUDE/EXCLUDE statements have no effect.

Generally, you should use the INCLUDE/EXCLUDE statements to avoid collecting data for time intervals in which there is nothing interesting likely to be happening, that is, periods of low activity. The only real cost of collecting data in periods of low activity is wasted disk space and a minor amount of CPU consumed collecting the sample data.

If you are only interested in collecting data at peak hours, say 10 AM to 11:30 AM and 1:30 PM to 4 PM on weekdays, simply put the following statements into SIRTUNEI:

INCLUDE 10 11:30 WEEKDAY INCLUDE 1:30 4 WEEKDAY

INTerval num_sec

This statement is used to set the sampling rate, thus making it possible to limit the amount of sample data collected. The default for num_sec is 1, which means that sample data is collected at one-second intervals.

The values specified for num_sec have a maximum resolution of 1/100 of a second so that:

INTERVAL 3.1415929

Is identical to:

INTERVAL 3.14

This also means that the lowest legal value for num_sec is 0.01.

The objective in setting the sampling interval should be to collect sufficient data to produce statistically significant results, without collecting unnecessarily huge amounts of data. Setting the sampling interval extremely low can also produce biased results. Generally, sampling intervals greater than 0.1 seconds should avoid any biasing problems.

A reasonable rule of thumb is that 10,000 samples are sufficient to produce accurate reports. Thus to collect data on a batch job that generally takes half an hour to complete, samples should be collected every 1800/10000 seconds. To accomplish this, place the following statement into SIRTUNEI:

INTERVAL 0.18

If data is to be collected over 8 hours of a production ONLINE run, the default sampling interval of 1 second would result in 8*3600 or 28,800 samples being collected. In this case, it would not be unreasonable to place the following statement into SIRTUNEI to reduce the number of samples collected to 14,400:

INTERVAL 2

MIXed

Status: This parameter is deprecated as of Version 7.2. If it is specified as an input parameter, it is ignored.

This statement indicates that SirTune should issue all messages in mixed-case. The default is to issue messages in mixed-case except on Japanese operating systems. On these systems, the default is to issue all messages in uppercase only. This option should be used on Japanese operating systems when mixed-case messages are desired.

NOSeq

This statement indicates that SirTune should not consider characters in columns 73 through 80 of SIRTUNEI as part of its input. If SIRTUNEI has RECFM=F and LRECL=80, SirTune ordinarily assumes that characters in columns 73 through 80 are sequence numbers, and therefore it ignores them. If SIRTUNEI has any other format, SirTune considers all characters in the input record as part of the SirTune statements.

PGM pgm_name

Effective in version 1.5 of SirTune and lower, this statement is ignored in versions after 1.5.

The PGM statement makes it possible to specify the name of the Model 204 ONLINE load module to be loaded by the SIRTUNE module. The default for pgm_name is ONLINE under MVS, and it is M204ONLN under CMS.

Thus, if SIRTUNE is to collect data for a job that should be run with BATCH204, put the following statement into SIRTUNEI:

PGM BATCH204

If the name of the load module for which SIRTUNE is to collect data is ONLINE22, put the following statement into SIRTUNEI:

PGM ONLINE22

PREComp

This statement specifies that SirTune should only collect compilation data for precompiled APSY procedures; it is the inverse of the ALLComp statement.

The default for a single-user run (NUSERS=1) is that SirTune collects compilation data for all procedures. The default for a multi-user run (NUSERS>1) is that SirTune collects compilation data only for precompiled procedures. It is unnecessary to specify PRECOMP in a multi-user run, since it is the default.

When PRECOMP is in effect, either because of an explicit PRECOMP statement or as the result of multi-user run defaults, the reporting module can produce line-by-line breakdowns for precompiled APSY procedures only.

SAMPle ON | OFF | AUTO

This statement places SirTune in manual sampling mode. In this mode, SirTune ignores INCLUDE and EXCLUDE statements until a SAMPLE AUTO command is issued via a MODIFY or SMSG command issued by an authorized user. The default for this statement is SAMPLE AUTO, which places SirTune under the control of INCLUDE and EXCLUDE statements.

For example, to have SirTune come up so that no sample data is collected until a user issues a (MODIFY or SMSG) SAMPLE command to turn sampling off or to put sampling in AUTO mode, simply place the following statement into SIRTUNEI:

SAMPLE OFF

To have SirTune come up so that sample data is collected until a user issues a MODIFY or SMSG SAMPLE command, place the following statement into SIRTUNEI:

SAMPLE ON

Note: If SAMPLE OFF is specified in SIRTUNEI and there are no AUTHORIZE statements in SIRTUNEI, it will be impossible to collect any sample data for the course of the run, because no user will have the authority to issue the MODIFY or SMSG SAMPLE command to set sampling to ON or to AUTO.

UPper

This statement indicates that SirTune should issue all messages in uppercase only. The default is to issue messages in mixed-case, except on Japanese operating systems. On these systems the default is to issue all messages in uppercase only.

This option should be used on systems where mixed-case messages might not be displayed correctly on terminals or printers.