2.3 LOGR CDS and System Logger policy

< Day Day Up >

Because the System Logger uses sysplex services, any system that you wish to use System Logger on must either be in monoplex mode (PLEXCFG=MONOPLEX in IEASYSxx) or it must be a member of a multi-system sysplex (PLEXCFG=MULTISYSTEM in IEASYSxx). The requirements to be a member of either type of sysplex are described in z/OS MVS Setting Up a Sysplex, SA22-7625. In addition, the System Logger subsystem should be defined in the IEFSSNxx member, using the following statements:

    SUBSYS SUBNAME(LOGR) INITRTN(IXGSSINT)

The System Logger component manages log streams based on policy information that you place in the LOGR CDS. This can be a point of confusion, as you will often see references to the System Logger policy, the LOGR CDS (also called the System Logger CDS), or the System Logger inventory; these are not separate entities. While some other components of z/OS have multiple policies (CFRM and SFM, for example), the LOGR CDS contains the only System Logger policy. The System Logger policy contains CF structure definitions (if applicable), log stream definitions, and data describing the current status of all log streams. To understand and effectively manage System Logger, it is important to remember this difference between the LOGR CDS and the other sysplex CDSs.

2.3.1 LOGR CDS usage

The LOGR CDS:

Must be formatted using the IXCL1DSU utility
Contains policy information (more on that in the next topic)
Must be accessible by all the systems in the sysplex

Regardless of whether you intend to use CF-Structure based or DASD-only log streams, it is important that you understand how the definition of the LOGR CDS can impact your applications. The parameters you specify can limit the number of log streams, LOGR structures, and offload data sets, as well as the ability of your systems to exploit new System Logger function. It is possible to bring in a new CDS with larger values (at the same LOGR CDS format level or greater), but it is very disruptive to move to a CDS with smaller values - therefore, it is important to give proper consideration to the values you will use.

Restriction:

If you wish to switch to a CDS that is formatted with smaller values, not only do you require a sysplex IPL, you will also lose all the information about all the log streams defined in the old CDS, along with all the data in those log streams.

Formatting the CDS

Format a primary, alternate, and spare LOGR CDS using the IXCL1DSU utility, making sure they are on different volumes, and different physical control units if possible, to ensure a copy exists if the primary is lost or otherwise not usable. We recommend you not over-specify these values as it can lead to a much larger than necessary CDS which can result in your IPL time increasing. While there is no sample job in SYS1.SAMPLIB for formatting the LOGR CDS, there is a sample job provided in Appendix B of z/OS MVS Setting Up a Sysplex, SA22-7625.

You may consider defining the alternate to have slightly higher values than the primary. If the values defined for your primary CDS are too low, you will have an alternate ready to switch in. However if you switch to this alternate for any reason, you will then need to define a new primary, formatted with the same values as the old alternate, that you can switch back to. This methodology should be used judiciously as it can result in the LOGR CDSs gradually getting larger and larger over time, until you end up with CDSs that are much larger than necessary.

The parameters that can be specified when creating a new LOGR CDS are:

LSR

The maximum number of log streams that can be defined in the System Logger policy that will be stored in this CDS. The default is 1, the minimum is 1, and the maximum is 32767. Do not take the default on this parameter or you will be limiting your sysplex to one log stream. You should evaluate the System Logger applications you plan to use and determine the number of log streams needed by each (keeping in mind some applications that run on separate systems may require a single sysplex-wide log stream; others might use separate log streams for each system).

LSTRR

The maximum number of structure names that can be defined in the System Logger policy. The default is 1, the minimum is 1, and the maximum is 32767. If you plan on using only DASD-only log streams, it is not necessary to specify this parameter. If you are planning on using CF-Structure based log streams, you should determine how many structures are necessary. We will discuss the guidelines for this in 2.5.1, "CF-Structure based log streams" on page 23.

Note that the maximum number of structures that can be defined in a CFRM policy is currently 512, so there is no value in making this number larger than 512 at a maximum. In practice, you should not make this number any larger than necessary. Also, system logger supports 255 connected structures at a time per system.

DSEXTENT

The number of additional offload data set directory extents available. The default is 0, the minimum is 0, and the maximum is 99998. Each DSEXTENT (directory extent) goes into a common pool available to any log stream in the sysplex, and is allocated as needed. If you have log streams that will exceed 168 offload data sets (for example, if you retain log data for long periods of time) you should specify this parameter. Log streams start with a base of up to 168 directory entries (that is, 168 offload data sets that can be used, 1 per directory entry); each additional DSEXTENT specified will allow the log stream owning the extent to use an additional 168 directory entries.

It is important to keep in mind that a DSEXTENT can only be owned by one log stream. If you have 20 log streams with 169 offload data sets each, you would requires at least 20 DSEXTENTs. When all the offload data sets in a DSEXTENT have been physically deleted, it will be returned to the available pool.

Note

Staging data sets do not count towards the directory entry limit.

If you decide to specify DSEXTENTs, there are some considerations you should keep in mind when determining how many should be requested. You should specify a value that is at least 15% more than you expect to be in use at any given time. You can monitor usage by:

Periodically running a LOGR CDS report using the IXCMIAPU utility. This will show the number of DSEXTENTS in use. Try to keep the number of directory records in use below 85% of the total formatted.
Watch for system messages IXG261E and IXG262A, which indicate usage of the offload data set directory is over 85% and 95% respectively.

If you have reached the maximum number of offload data sets and there are no DSEXTENTs in the available pool, System Logger will not be able to create any new offload data sets for that log stream and any offload attempt will fail. Watch for system message IXG301I with a return code of X'08' and reason code of X'085C' indicating this state. When additional DSEXTENTs have been made available for the sysplex, System Logger will retry the offload and issue an ENF 48 indicating that the log stream is available. You may be able to make additional directory space available by deleting log data from the log stream. For more information on deleting log data, see 2.7, "Deleting log data" on page 62.

You may be able to set up a retention period and automatic deletion policy to help ensure your log streams will not run out of space; however, be sure to verify that the use of these keywords will not have a negative impact on your System Logger applications. For more information on retention period and autodelete, see "Defining CF-Structure based log streams" on page 32.

SMDUPLEX

SMDUPLEX specifies whether the LOGR CDS should be formatted at the HBB6603 or HBB7705 level. The default is 0 (NO), and the maximum is 1 (YES). Specifying 1 indicates that System-Managed CF Structure Duplexing is a supported, in addition to other enhancements introduced in z/OS 1.3 and 1.4. We discuss CDS format levels further in "LOGR CDS format levels" on page 14.

Ensure you meet all the prerequisite requirements before attempting to use System-Managed Duplexing. For more information on this, see the section entitled "Understanding System-Managed Duplexing Rebuild Requirements" in z/OS MVS Setting Up a Sysplex, SA22-7625.

LOGR CDS format levels

The addition of the SMDUPLEX parameter to IXCL1DSU for LOGR CDSs in z/OS V1R2 allows the installation to specify what level CDS should be created. If you are not using the newest level LOGR CDS, you will be precluded from exploiting most of the new functionality added to System Logger since z/OS V1R2. The newest LOGR CDS format level as of z/OS V1R4 is HBB7705. To use the HBB7705 LOGR CDS format level, all systems in your sysplex must be running z/OS V1R2 or later. Any system running a lower level of z/OS or OS/390 will not be able to access a HBB7705 format CDS, and System Logger will not start on those systems. As we discuss functions that require this format level later in this chapter, we will note the requirement.

Note

LOGR CDS format levels do not actually correspond to any particular release in a one-to-one relationship, despite the naming convention (using release FMIDs such as HBB6603 and HBB7705). Instead, the format level only corresponds to the release it was introduced in, as this is the earliest release of OS/390 or z/OS it can be used with.

Updating the LOGR CDS

If you decide to update the format level of your LOGR CDS, remember that the newly-formatted CDS cannot decrease any of the values defined in the current CDS. To view these values as well as the current format level, you can either run the IXCMIAPU LIST report, or use the D XCF,C,TYPE=LOGR command.

Attention:

Note that you should never move to a new format level until all systems in the sysplex are stable at the required level of z/OS to support the new format, as System Logger will not start on those systems not meeting the minimum requirement. Attempting to fall back to a lower format level CDS will corrupt or destroy log data.

There are some steps you should take before moving to a new CDS:

Make sure you have already defined your new primary, alternate, and spare CDSs.
Update the COUPLExx member in SYS1.PARMLIB to point to the new primary and alternate CDS.

After completing these steps, you have ensured that a new primary and alternate CDSs are ready, and that the COUPLExx member points to them. This is important; if it is necessary to IPL and the COUPLExx member still points to the old CDSs, you will be given the option to switch back to those CDSs, which could result in corruption or loss of System Logger policy data.

To switch to the new LOGR CDS while keeping your policy definitions intact:

Make the new primary CDS the current alternate by issuing the following command:
```
 SETXCF COUPLE,TYPE=LOGR,ACOUPLE=new_primary_cds 
```
Next, promote that data set to be the primary LOGR CDS:
```
 SETXCF COUPLE,PSWITCH,TYPE=LOGR 
```

Finally, move in the new alternate:

 SETXCF COUPLE,TYPE=LOGR,ACOUPLE=(new_alternate_cds,volume)

These steps can be carried out at any time; it is not necessary to quiesce System Logger activity. As a result of taking these steps, you will have new LOGR primary and alternate CDSs and all of your policy definitions (log streams, CF structures, and so on) will be intact.

It is also possible to bring in a new primary and alternate LOGR CDS without retaining your System Logger policy definitions ("clean" copy):

Format new primary and alternate LOGR CDSs.
Update the COUPLExx member in SYS1.PARMLIB to identify the new primary and alternate CDS to the sysplex.
Shut down every system in the sysplex and do a sysplex IPL. After the IPL, you will receive a message asking if the system should use the CDSs listed in the COUPLExx member or the ones used the last time the system was up. You should reply C to indicate that the CDSs listed in the COUPLExx member should be used.

If there are any "failed persistent" structure connections, it may be necessary to force them using the SETXCF FORCE,CON,CONNM=ALL,STRNM=strname command.

Important:

If you switch to new CDSs using this method, all the data in the old CDSs will be lost. Any data in the log streams (including the offload data sets) will be inaccessible. This means that you must define all the log streams again in the new CDSs. It also means that you must manually delete all the offload and staging data sets associated with the log streams that were defined in the old CDSs—if you do not do this, System Logger will not have any knowledge of those data sets and will get duplicate data set errors when it tries to allocate the equivalent data sets for the log streams in the new CDS.

For additional guidance on handling LOGR CDSs, see topic 9.4.8 in z/OS MVS Setting Up a Sysplex, SA22-7625, and informational APARs II12375 and II12551.

2.3.2 The System Logger policy

The System Logger policy is different than most other z/OS policy definitions in that you can only have one per sysplex. Additionally, whereas most other CDSs only contain static policy statements and some transient information, the LOGR CDS contains persistent information, such as the names of the offload data sets associated with each log stream.

Specifically, the System Logger policy contains:

CF structure definitions
Log stream definitions
Data reflecting the current state of all log streams (connection status, names of staging and offload data sets, High RBA and log block BLOCKIDs for each offload data set, location of the duplex copy of the interim storage, and so on)
A list of the connections for every system
A count of the number of active systems in the sysplex

Since there is only one System Logger policy per sysplex, you cannot use the DEFINE POLICY NAME parameter in the System Logger policy, nor can you issue the SETXCF START,POLICY command to activate a System Logger policy. The System Logger policy is modified (or updated) using the IXCMIAPU utility or the IXGINVNT macro. As such, it is only necessary to specify the log streams and CF structures that are being newly defined, updated or deleted, unlike other policies (such as CFRM) for which you must enter the whole policy. Another difference between the System Logger policy and other policies is that action is taken immediately on the request submitted. For example, if you request that a log stream be defined, it will be done immediately, and the first offload data set will be allocated.

Note

One of the more annoying quirks of System Logger's interpretation of input to the IXCMIAPU utility is that if it finds a statement in error, it will ignore all the statements coming after that statement; therefore you should always verify that all the steps in a particular request completed - you can do this by simply checking the job output.

For information on modifying the System Logger policy, see 2.5, "Log streams" on page 22.

Authorization for IXCMIAPU

Before setting up the System Logger policy with the IXCMIAPU Administrative Data Utility program, you must specify who can use IXCMIAPU:

Define a resource profile for the resource name MVSADMIN.LOGR to the SAF FACILITY class. Grant ALTER access to users who must alter or maintain the policy; grant READ access to users who require reports on the policy, but who will not change the policy.
If applicable (if you will have CF structures), define a resource profile for the resource name MVSADMIN.XCF.CFRM to the SAF FACILITY class. Grant UPDATE access to users who must define CF structures in the policy.

The users of the IXCMIAPU utility require access to the resources used by the utility. Define the appropriate accesses before users attempt to add, update, delete, or extract a report from the System Logger policy. The LOGR CDS must be activated and available before you add log streams and structure definitions to it. The following access authorities are required to set up the System Logger policy:

To use the DEFINE, UPDATE, or DELETE LOGSTREAM statements, ALTER access to the RESOURCE(log_stream_name) CLASS(LOGSTRM) profile is required.
To use the DEFINE or DELETE STRUCTURE statements, ALTER access to the RESOURCE(IXLSTR.structurename) CLASS(FACILITY) profile is required.
To specify a structure name on a LOGSTREAM definition (for example, DEFINE LOGSTREAM(log_stream_name) STRUCTNAME(structname)), UPDATE access to the RESOURCE(IXLSTR.structurename) CLASS(FACILITY) profile is required.

< Day Day Up >