4.2 Defining the System Logger in the IMSplex

< Day Day Up >

4.2 Defining the System Logger in the IMSplex

There are several definitions required in CQS and in z/OS to implement CQS use of the System Logger. There are no System Logger-related definitions in IMS itself.

4.2.1 Subsystem (CQS) definitions

CQS definitions of the log streams are contained in CQS PROCLIB member CQSSGxxx (the CQS global PROCLIB member). Only the log stream name is defined - not the logger structure name, nor any other characteristics of the log stream. Example 4-2 is an example of a CQSSGxxx PROCLIB member for a CQS with both a full function shared queue and a fast path EMH shared queue.

Example 4-2: Sample log stream definition in CQS

    STRUCTURE(STRNAME=MSGQ.STRUCTURE       OVFLWSTR=MSGQ.OVFLW.STRUCTURE       LOGNAME=MSGQ.LOG.STREAM       SRDSDSN1=CQS.MSGQ.SRDS1       SRDSDSN2=CQS.MSGQ.SRDS2)    STRUCTURE(STRNAME=EMHQ.STRUCTURE       OVFLWSTR=EMHQ.OVFLW.STRUCTURE       LOGNAME=EMHQ.LOG.STREAM       SRDSDSN1=CQS.EMHQ.SRDS1       SRDSDSN2=CQS.EMHQ.SRDS2)

Note that there is only one CQSSGxxx global PROCLIB member in the shared queues group. All CQSs use the same member (or members which are identical). The LOGNAME parameter must match the LOGSTREAM NAME parameter in the LOGR policy.

4.2.2 System Logger definitions

System definitions for the log stream and logger structure are in two places. The log stream and its characteristics are defined in the LOGR Policy in the LOGR Couple Data Set (CDS). LOGR list structure definitions are in both the CFRM CDS (defines the structure to XES), and the LOGR policy (defines the relationship between the log stream and the structure).

LOGR structure definition

When a Coupling Facility list structure is used as interim storage for a log stream (always the case for CQS), then that structure must be defined in the active CFRM policy. The policy defines the name and size of the structure, as well as some other characteristics. Example 4-3 is an example of the definition of the LOGR structure for the full function message queues in the CFRM policy. A similar definition would be required for the EMH queue logger structure.

Example 4-3: Sample LOGR structure definition

    DATA TYPE(CFRM)       DEFINE POLICY NAME(POLICY1)          STRUCTURE NAME(MSGQ.LOGR.STRUCTURE)           SIZE(100000)           INITSIZE(50000)           DUPLEX(ENABLED)           ALLOWAUTOALT(NO)           REBUILDPERCENT(1)           PREFLIST(CF01,CF02)           EXCLLIST (MSGQ.STRUCTURE)

The meanings of these parameters are briefly described below with considerations for CQS and IMS shared queues. For a more complete description of the parameters themselves, see Chapter 2, "System Logger fundamentals" on page 7 and z/OS MVS Setting Up a Sysplex, SA22-7625.

NAME

Defines the name of the CFRM policy. This policy must be active for the definitions to be effective. The CFRM policy is activated using the command:

    SETXCF START,POLICY,TYPE=CFRM,POLNAME=POLICY1

INITSIZE

This is the initial size of the structure, in 1024-byte increments. Since this structure will almost always become full before a structure checkpoint is taken, the actual size does not matter too much. Eventually, all log records in the structure will have to be offloaded regardless of the size. A smaller structure means that less memory is needed in the Coupling Facility and in the central processor (CPC) to duplex the structure in a dataspace. If you have memory constraints, making it smaller will require more frequent offloads, but have little effect on the overall performance. Making it larger will reduce the number and frequency of offloads, but in the end, the same amount of data will be offloaded. You might also use a target offload frequency (for example, once every 30–60 seconds during peak transaction volumes) to set the size and HIGHOFFLOAD values (described below). A 50 megabyte logger structure size is suggested as a reasonable size at which to begin. If the structure needs to be made larger to reduce the number of offload processes, the structure size can be altered up to its maximum size set using a SETXCF START,ALTER command.

SIZE

This is the maximum size to which the structure can be altered. Note that, unlike CQS and the message queue structures, the System Logger does not alter the size of the structure from its current size. It must be done by the user using the command:

    SETXCF START,ALTER,STRNM=structure-name,SIZE=new-size

DUPLEX

Indicates whether the structure may be duplexed, using system-managed duplexing, for availability. ENABLED means that the structure is automatically duplexed when it is allocated. ALLOWED means that it is not done automatically by XES, but can be turned on by the operator if desired using the command:

    SETXCF START,REBUILD,DUPLEX,STRNAME=MSGQ.LOGR.STRUCTURE

ALLOWAUTOALT

Indicates whether the system may automatically alter the structure size and/orentry-to-element ratio. This should always be set to NO for logger structures, since the System Logger monitors and alters the structure itself. Allowing the system to automatically alter the structure size may produce undesired results.

REBUILDPERCENT

Indicates that if connectivity to the structure is lost by more than this percentage, it should be rebuilt on another Coupling Facility where the connectivity is better. This should be set to 1 (percent) so that it will always be rebuilt on another Coupling Facility if connectivity from one of the systems fails.

PREFLIST

Identifies the Coupling Facilities which are candidates to contain this structure. For rebuild or duplexing to work, there must be at least two.

EXCLLIST

Requests that the structure not reside on the same Coupling Facility as other structures named in the parameter. We recommend that you put the logger structure on a different Coupling Facility than the shared queue structure to avoid a single point of failure. This does not prevent the logger structure from being allocated on the same Coupling Facility if there is no other CF available.

Note that there is nothing in this definition to indicate that the structure is a list structure, or that it is to be used by the System Logger (unless you interpret this from its name). The name (MSGQ.LOGR.STRUCTURE) must match the name defined in the LOGR policy.

LOGR policy definition

The log stream, and the structure used by the log stream, is defined in the LOGR policy. The LOGR policy relates the log stream with the logger structure, and defines the characteristics of the log stream and structure. Example 4-4 shows an example of the portion of the LOGR policy defining the CQS log stream and logger structure for the full function message queue (MSGQ) structure.

Example 4-4: Sample LOGR policy definition

    DATA TYPE(LOGR)       DEFINE STRUCTURE          STRUCTNAME(MSGQ.LOGR.STRUCTURE)          AVGBUFSIZE(512)          MAXBUFSIZE(65276)          LOGSNUM(1)       DEFINE LOGSTREAM          NAME(MSGQ.LOG.STREAM)          STRUCTNAME(MSGQ.LOGR.STRUCTURE)          HLQ(IMSPLEX0)          STG_DUPLEX(YES)          STG_SIZE(50000)          STG_DATACLAS(STAGING)          DUPLEXMODE(COND)          LOGGERDUPLEX(COND)          LS_SIZE(256000)          LS_DATACLAS(OFFLOAD)          HIGHOFFLOAD(50)          LOWOFFLOAD(0)          AUTODELETE(NO)          RETPD(0)          Other SMS parameters

It is important that the LOGR structure be defined in the (active) CFRM policy before the LOGR policy is updated to contain your new log streams. It is also necessary to define, in the LOGR policy, the logger structure first and then the log stream. The following are short descriptions of the parameters in the LOGR policy. For a more complete description, see Chapter 2, "System Logger fundamentals" on page 7 and z/OS MVS Setting Up a Sysplex, SA22-7625.

DEFINE STRUCTURE

You must define the logger structure to be used by the log stream. The following parameters are used by the System Logger to set some of the characteristics of the logger structure when it is first allocated (first connect time). Not all possible parameters are shown in this example.

STRUCTNAME: This name must match the name in the CFRM policy and in the log stream definition to follow.
AVGBUFSIZE: This parameter is the average size of a (CQS) log record and is used by the System Logger to set the initial entry-to-element ratio. Only a few CQS log records log the content of the message. Many only log the fact that a message has been read and moved to another queue, or has been deleted. Some log system events, like structure checkpoint started or ended. Most of these other log records tend to be small but numerous and can make the average size of a log record small. This is a difficult number to predict but the good news is that the System Logger will monitor this ratio every 30 minutes and adjust the ratio if necessary. We recommend, therefore, that you set this value to 512 (bytes) and let the System Logger adjust it if necessary.
MAXBUFSIZE: This value determines the maximum size log record that can be written to the log stream. It also determines the size of the data elements in the structure. Any value less than or equal to 65276 will cause the System Logger to allocate the structure with 256-byte data elements. Values over this will result in 512-byte data elements and should be avoided (waste of space). For IMS full function or fast path EMH, there is no reason to specify any value other than 65276.
LOGSNUM: This determines how many log streams can share the LOGR structure. For CQS, this number should always be one. You should not share a LOGR structure with both the full function and fast path EMH log streams. Their usage of structure resources is likely to be very different.

DEFINE LOGSTREAM

The following parameters define the characteristics of the log stream. Not all possible parameters are shown in this example.

NAME: This is the name of the log stream. It is the only name known to CQS and must be the same as the LOGNAME parameter in CQSSGxxx.
STRUCTURENAME: This is the name of the logger structure that this log stream will reside in. It must be the same as the name defined in the DEFINE STRUCTURE command in this LOGR policy, and must have been defined in the CFRM policy.
HLQ: Defines a high level qualifier for the log stream offload data set names and the staging data set names. In the above example, the staging data set name and the offload data set names will have a high level qualifier of IMSPLEX0.
STG_DUPLEX: This determines whether the interim log stream will be duplexed to a staging data set or to a dataspace. While it is not desirable to use staging data sets for this log stream, the only way to specify the attributes of the staging data sets is if you specify STG_DUPLEX (YES). Therefore we recommend specify STG_DUPLEX(YES) and DUPLEXMODE(COND).
STG_SIZE: The System Logger will always duplex the log stream, but you have the choice of whether to duplex it in a dataspace or on DASD in a staging data set. This parameter sets the size of the staging data set in 4K increments. Because of the way space is used in the staging data set ("Sizing interim storage" on page 265), this should be several times the size of the structure to avoid unnecessary offloads, and to allow maximum use of the allocated structure size. Note that the structure size specified in the CFRM policy is in 1K increments.
STG_DATACLAS: This parameter specifies the name of the SMS data class that is to be used when allocating the staging data set. Staging data sets should have VSAM share options set to (3 3), so the data class specified on this parameter should have those share options specified.
DUPLEXMODE: This parameter is used when STG_DUPLEX(YES) is set and determines the conditions under which the log stream should be duplexed to the staging data sets. DUPLEXMODE(COND), for conditional, means to use the staging data sets only if the system's connection to the Coupling Facility contains a single point of failure. A single point of failure exists if the CF is volatile (no power backup) or if it resides on the same CPC as the z/OS system connecting to it. We recommend setting this value to COND, which will use the staging data sets only if the dataspace and the structure are failure dependent.
LOGGERDUPLEX: This parameter determines whether the System Logger will use its own duplexing method (staging data set or dataspace) if the structure is being duplexed in the Coupling Facilities. COND means that if the structure is duplexed, and the two structure instances are failure isolated from each other, then the System Logger will not duplex to either the staging data set or a dataspace. Since the default is UNCOND, you may want to code this parameter as COND if the logger structure is being duplexed.
LS_SIZE: This parameter sets the size of the offload data set in 4K increments. At a minimum, the size should be set to a value large enough that you don't run out of your default maximum allocations (168) across two structure intervals. This is also a difficult number to optimize, but can be estimated by calculating the amount of data logged between structure checkpoints. This is dependent on the transaction rate and the amount of data logged per transaction. As an example, if you are running 1000 transactions per second, and log 2000 bytes per transaction (input plus output message length and a little bit more), then you are logging (about) two megabytes per second. This equates to 7.2 GB per hour. Since you need enough space for two structure checkpoint intervals, for every hour between checkpoints you need at least 14.4 GB of total offload data set space. This is in the neighborhood of 90 MB per data set, or LS_SIZE=22500. This should be considered the absolute minimum to contain the entire log stream. This is not a number that you want to fine tune. Make the offload data sets much larger than the minimum to avoid the possibility of the log stream filling up. It uses no more DASD space - it just uses fewer larger data sets.
LS_DATACLAS: This parameter specifies the name of the SMS data class that is to be used when allocating the offload data sets. Offload data sets should have VSAM share options set to (3 3), so the data class specified on this parameter should have those share options specified.
HIGHOFFLOAD: This parameter determines when the offload process is driven. When the percentage of data elements in use in the structure reaches this value, the offload process is driven. This number is not critical except that it should probably be between 50% and 80%. Do not go above 80% since space may not be freed up in the structure until it is successfully offloaded (see "High and low offload thresholds for funnel-type log streams" on page 274). You should be sure to leave enough room for logging to continue without running out of space while offload is processing.
LOWOFFLOAD: This parameter determines how much is offloaded. For CQS, this should be set to zero (0%). That means that offload should move all data entries on the structure at the time it is driven. New data entries that arrive after offload begins are not offloaded until the next cycle. Since CQS uses this data only for forward recovery of a message queue structure, which should be rare or never, there is no reason to leave any data in the structure.
AUTODELETE: Never specify YES for this (NO is the default). It may cause the System Logger to automatically delete offloaded data before CQS deletes it.
RETPD: This could be used if you have some reason for keeping CQS log records beyond their useful life. If so, you can specify this as the minimum number of days to keep a log record entry before deleting it, even though CQS may have already issued a delete for it. Setting the retention period to zero (0) or letting it default, means that deletion will be controlled strictly by CQS.

There are other parameters that can be specified in the LOGR policy, but most are not of interest to CQS or are determined by installation standards. Even some of the above may be determined by installation standards.

4.2.3 Security definitions

The log stream will be a protected resource defined in the Security Access Facility (SAF) LOGSTRM class. Each CQS userid must be permitted UPDATE access to the log stream. If you have any users who will be just reading the log stream, such as DFSERA10, they need READ access.

Example 4-5: Sample log stream security definition

 RDEFINE LOGSTRM MSGQ.LOG.STREAM UACC(NONE) PERMIT MSGQ.LOG.STREAM CLASS(LOGSTRM) ID(cqsuserid1) ACCESS(UPDATE) PERMIT MSGQ.LOG.STREAM CLASS(LOGSTRM) ID(cqsuserid2) ACCESS(UPDATE) PERMIT MSGQ.LOG.STREAM CLASS(LOGSTRM) ID(cqsuserid3) ACCESS(UPDATE) PERMIT MSGQ.LOG.STREAM CLASS(LOGSTRM) ID(readuser1) ACCESS(READ) PERMIT MSGQ.LOG.STREAM CLASS(LOGSTRM) ID(readuser2) ACCESS(READ)

The log stream name defined to RACF is the name specified on the NAME parameter of the DEFINE LOGSTREAM statement in the LOGR policy.

< Day Day Up >