CICS log streams
The CICS® log manager uses services that are provided by the z/OS® system logger, and in a Parallel Sysplex® can write log data to the z/OS coupling facility.
DFHLOG and DFHSHUNT are the CICS system logs. CICS regions might also use extra log streams, depending on the applications, product mix, and the functions and tools that are being used.
The CICS system log, forward recovery logs, autojournals, and user journals map into specific log streams. Log streams are defined in structures within the coupling facility or as DASD-only log streams.
DASD-only logging can be used for single-image and non-Parallel Sysplex environments. DASD-only log streams do not use coupling facility storage. A DASD-only log stream has a single system scope. Only one system at a time can connect to DASD-only log stream. The z/OS system logger programming interface can be used to merge data from multiple instances of an application, including from different systems across a Parallel Sysplex (however, the CICS system log data will not be merged). DASD-only logging can be used in a Parallel Sysplex, but merging is supported within one z/OS image only.
A coupling facility log stream spans two levels of storage: the coupling facility for interim storage and DASD log datasets for more permanent storage. When the coupling facility space for the log stream fills, the data is offloaded to DASD log datasets. A coupling facility log stream can contain data from multiple systems, allowing a system logger application to merge data from systems across the Parallel Sysplex (however, the CICS system log data will not be merged). The main difference between coupling facility log streams and DASD-only log streams is the storage medium that the system logger uses to hold interim log data: In a coupling facility log stream, interim storage for log data is in the coupling facility list structures. In a DASD-only log stream, interim storage for log data is in the local storage buffers on the system. Local storage buffers are data space areas that are associated with the system logger address space. You can use coupling facility log streams, DASD-only log streams, or a combination of both types of log streams.
For a general understanding of z/OS System Logger and how it works, see the IBM® Redbooks® publication Systems Programmer's Guide to: z/OS System Logger SG24-6898. For information about the interactions between CICS and z/OS System Logger, see the IBM Redbooks publication Performance Considerations and Measurements for CICS and System Logger REDP-3768. For more information about CICS log streams, see Logging and journaling.
- Because the CICS DFHLOG and DFHSHUNT log streams are only accessed by a single CICS region, you have the choice of defining the log streams as CF log streams or DASDONLY log streams.
- For CF log streams:
- You must carefully plan the number of log streams per CF structure for use in your environment, as each log stream uses a proportion of the resources of a single coupling facility structure. For further information about defining your logger environment for CICS, see Defining coupling facility structures.
- Try to ensure that each structure contains log streams that are connected to by CICS regions on more than one CPC to enable recovery if one of the CICS regions abends.
- Do not mix DFHLOG and DFHSHUNT log streams in the same structure.
- Try to place log streams with a similar level of activity in the same structure. For example, place busy log streams in one structure, and less busy ones in a different structure.
- For all log streams:
- Size your staging datasets or z/OS System Logger structures (or both) so that no log records are moved from primary storage to the offload datasets.
- Specify a reasonable LS_SIZE value. The default value of just two tracks is far too small.
- Use a data class for the offload datasets that result in a CI size of 24 KB. However, the staging datasets must have a CI size of 4 KB.
- Specify OFFLOADRECALL(NO) for the DFHLOG and DFHSHUNT log streams.
- Use model log stream definitions so that you do not have to explicitly specify new log stream definitions every time that you start a new CICS region.
- If you use DASD mirroring for disaster recovery purposes, and you do not want to do an INITIAL start of your CICS regions in a disaster, define all your CICS log streams to use staging datasets.
- A good empirical range for CICS system logstreams DFHLOG and DFHSHUNT, HIGHOFFLOAD should be set to 80 - 85%. The LOWOFFLOAD parameter value is most suitable between 40 - 60%. Too low a value might result in physical offloading of log data from primary to auxiliary storage after the z/OS System Logger offload process has completed physical deletion of any unwanted log data during offload processing. Conversely, too high a value might mean that subsequent offload processing occurs more frequently, as less space is freed up from primary storage during an offload operation.
- The guidelines for general log streams like forward recovery logs and user journals are different from those for the system log. There is no requirement here to retain logged data in the coupling facility structure. Rather, due to the typical use of such data, you might need only a small structure to offload the data rapidly to DASD. If so, set HIGHOFFLOAD to 80 - 85% and LOWOFFLOAD to 0.
- It is preferable to have smaller structures, and to do frequent, small offloads, rather than large structures and the resulting infrequent, but long-running, offloads.
- Do not enable auto alter for z/OS System Logger structures.
- Keep the log streams for test CICS systems (and other systems not in regular use) in structures separate from the structures that hold the log streams of production CICS systems.
- Keep the log streams for terminal-owning regions (TORs) in structures separate from those accommodating log streams for application-owning regions (AORs). In addition, keep log streams for file-owning regions (FORs) in structures separate from those accommodating log streams for TORs and AORs.
- Set MAXBUFSIZE to slightly less than 64 K (for example, 64000).
Log defer interval (LGDFINT) value
The LGDFINT CICS SIT parameter defines the log defer interval. The interval is the length of time, which is specified in milliseconds, that the CICS log manager is to wait before it invokes the z/OS System Logger for a forced write request. The value that is chosen can have an impact on transaction response time.
Specifying a large LGDFINT value might increase the number of log records that CICS is able to place in a log block, and also decreases the cost of using z/OS System Logger (because z/OS System Logger is called less frequently). However, given the speed of more recent processors, it is better to send the log blocks to z/OS System Logger more frequently. For this reason, the default LGDFINT value is decreased to 5 milliseconds. While some benefit might be achieved from using an even smaller value, using a value larger than 5 is inadvisable.
Activity keypoint frequency (AKPFREQ) value
The AKPFREQ keyword specifies the number of write requests to the CICS system log stream output buffer required before CICS writes an activity keypoint. One of the consequences of taking an activity checkpoint is that log records that are no longer required for backout and recovery are deleted from the log stream, thus freeing up space in interim storage. A larger AKPFREQ value means that log records are retained in interim storage for longer.
The result of this is that either log blocks must be moved to the offload datasets (which is not desirable) or the size of interim storage needs to be increased, resulting in extra storage requirements in the CF and in the z/OS System Logger data space. Another effect is that higher AKPFREQ can increase restart times.
Reducing the AKPFREQ value caused CICS to trim the tail of the log more frequently. Trimming the tail more often makes it possible for the offload process to reach the LOWOFFLOAD point without the overhead of issuing I/O to move data to the offload datasets.