Calculating the size of list structures for system logger applications

Use the following procedure to to calculate how large you should make each coupling facility list structure allocated for coupling facility log streams. This procedure applies only to coupling facility log streams. You can use this procedure for any system logger application, including applications provided by IBM®, independent software vendors, or your own installation.

For logrec log stream and operations log log streams, specific sizing recommendations are provided in the System/390® MVS™ Parallel Sysplex® Configuration Volume 2: Cookbook , SG24-2076.

For other IBM-provided system logger applications, such as CICS® log manager, you should get recommendations for the size of your coupling facility structure or structures from documentation on that particular application.

The procedure will help you determine the minimum amount of coupling facility space you should allocate for a coupling facility structure, based on the amount of space needed for all the log streams mapping to the structure.

This procedure requires the use of the PR/SM™ Planning Guide , order number GA22-7123-13 or higher. Versions at a lower dash level than -13 are not valid with this sizing procedure. The example provided at the end of this procedure applies only for a coupling facility at the following levels:

CFLEVEL 1 with a service level 4.03 or higher.
CFLEVEL 2 or higher.

Go through the procedure once for every coupling facility structure.

Gather information about the coupling facility structure.
For each structure, gather the following information common for all the log streams that map to the structure. You will use these values in sizing the coupling facility space you need. Most of this information corresponds to parameters in the structure definition of the LOGR policy. You can specify the values you gather here when you add information to the LOGR policy (see Add information about log streams and coupling facility structures to the LOGR policy).
AVGBUFSIZE

Average size of log blocks written by applications to log streams associated with this coupling facility structure. This value corresponds to the AVGBUFSIZE parameter specified for each structure in the LOGR policy. For this procedure, pick the value that represents the average size of log blocks generated by all the log streams writing to this coupling facility structure. For information on specifying the AVGBUFSIZE parameter in the LOGR policy, see Specifying the average log block size.
For a logrec log stream, IBM recommends an AVGBUFSIZE of 4068.

For an OPERLOG log stream, IBM recommends an AVGBUFSIZE of 512.

For an RRS log stream, see z/OS MVS Programming: Resource Recovery.

Installation or vendor supplied applications should base AVGBUFSIZE on the average size of the log blocks they want to write to the log stream.

MAXBUFSIZE

Maximum size of a log block corresponding to the MAXBUFSIZE parameter in the LOGR policy.
For a logrec or OPERLOG log stream, IBM recommends a MAXBUFSIZE of 4096.

For an RRS log stream, see z/OS MVS Programming: Resource Recovery.

Installation or vendor supplied applications should base MAXBUFSIZE on the maximum size of the log blocks they want to write to the log stream.

Note that once you have defined the MAXBUFSIZE for a coupling facility structure, you cannot update the value. To change the MAXBUFSIZE, you must delete the log streams associated with the structure, delete the structure, and then re-define the structure with the new MAXGBUFSIZE value.

LOGSNUM

Maximum number of log streams in the structure corresponding to the LOGSNUM parameter in the LOGR policy. See The LOGSNUM parameter for more information.

MXSS-to-TSS

The ratio of the maximum structure size to the target structure size. For example, if you want your maximum structure size to be twice as big as your target structure size, then MXSS-to-TSS would be 2. See Appendix B in the PR/SM Planning Guide.
Gather information about each log stream.
For each log stream that maps to a coupling facility structure, gather the following information.

Most of these values are projected or desired values for your log stream, and a few correspond to parameters you will specify in the LOGR policy. You will use these values in sizing the coupling facility space you need.
LOWOFFLOAD

LOWOFFLOAD specifies the point, in percent value of space consumed, where system logger will stop offloading coupling facility log data to the DASD log data sets for this log stream. It corresponds to the LOWOFFLOAD parameter in the LOGR policy. For OPERLOG, logrec log stream, or the CICS log manager, IBM recommends that you use the LOWOFFLOAD default value of zero. See Administrative data utility for more information on the LOWOFFLOAD parameter.

HIGHOFFLOAD

HIGHOFFLOAD specifies the point, in percent value of space consumed, where system logger will begin offloading coupling facility log data to the DASD log data sets for this log stream. It corresponds to the HIGHOFFLOAD parameter in the LOGR policy.
For OPERLOG, logrec log stream, or the CICS log manager, IBM recommends that you use the HIGHOFFLOAD default value of 80.

See Administrative data utility for more information on the HIGHOFFLOAD parameter.

ResidencyTime

Desired residency time for log data in the coupling facility structure, in seconds. Residency time is the amount of time you want a log block to stay in the coupling facility between the time it is written to the coupling facility and being offloaded to DASD.
For a logrec or OPERLOG log stream, IBM recommends a residency of 10 seconds. For other system logger applications, get the desired residency time from the documentation for the application.

WritePerSec
Projected write requests per second against the log stream. This value is the total IXGWRITE requests per second issued by all system logger applications or systems connected to a log stream.
For an OPERLOG log stream, you can calculate projected writes per second using the current SYSLOGs. For each system in the sysplex, do the following calculation:
1. Choose a spot in SYSLOG and note the timestamp at that spot. You might want to choose a peak or high usage time of day.
2. Page down 2000 lines by issuing, for example, DOWN 2000 to SDSF or TSO/E browse.
3. Note the time stamp in this spot.
4. Calculate the number of seconds between the two time stamps. This is the number of seconds it took to write 2000 lines of SYSLOG. (This calculation is based on most messages being one line).
5. Divide 2000 by the number of seconds it took to write 2000 lines to get the lines per second.
6. Add the results for each system's SYSLOG to get the total writes per second for the OPERLOG log stream.
For a logrec log stream, calculate the projected writes per second using the current logrec data sets. For each system that will write to the logrec log stream, do the following calculation:
1. Request or obtain an EREP report for a particular time span. It must be a report that includes all records. For example, take an EREP daily report that processed all records.
2. Near the top of the report, message IFC120I will tell how many records were written in the time span chosen for the report. Divide this number by the number of seconds in the time span for the average writes per second for this logrec data set.
3. You can also look at timestamps in the output to analyze how many records were written in a particular second. You can do this to check for peak usage.
4. Add the results for each logrec data set that will write to the log stream to get the total writes per second for a logrec log stream.
Calculate coupling facility structure list entries required per log stream.
For each log stream that maps to the coupling facility structure, use the following formula to calculate the number of list structure entries required to represent a log stream's data. The number of entries a log stream needs in the coupling facility list structure depends on the coupling facility residency time desired for a given log stream. Use the values for WritePerSec and ResidencyTime gathered in the prior step:
```
Entries = ((100/(HighOffload-LowOffload))*WritePerSec*ResidencyTime)+4
```
Calculate the total coupling facility structure size.
This step calculates the size needed for each coupling facility structure to contain all the log data for the log streams that map to it. Perform this step for each coupling facility structure planned for system logger applications.
This step requires that you use the values from the previous steps and refer to Appendix B in PR/SM Planning Guide for formulas for the total structure size (TSS) and maximum structure size (MSS) for a coupling facility level 1 list structure at service level 4.01. This formula applies to the following coupling facility levels:
- CFLEVEL 1 with service level 4.03 or higher.
- CFLEVEL 2 or higher.
In order to pick the correct formula, you will need to know that the system logger uses keys and adjunct data, but no names for its list structures.
For each structure, use the following data as input to the TSS and MXSS formulas:
MLSEC
MLSEC is the number of coupling facility list entries needed for all the log streams that map to a coupling facility structure. Calculate this value by taking the value for entries calculated in step 3 for the log stream with the largest entries value and do the following:
```
MLSEC = entries * maximum number concurrently
        active log streams for the structure
```
You take the entries value for the largest log stream because when there are multiple log streams assigned to one coupling facility structure, system logger divides the structure space equally between each log stream connected to the structure.

If you are not sure how many of the log streams mapped to the structure will be concurrently active at any given time, multiply the entries times the LOGSNUM value for the structure to calculate the value for MLSEC. That way, you can be certain your coupling facility structure will be large enough for all logging activity.
MLSELC

Not used.

LELX

If MAXBUFSIZE is greater than 65,280, LELX = 1. Otherwise, LELX = 0.

MDLES
To calculate MDLES
```
(Greater of MAXBUFSIZE or 8192) / (256 * (2 ** LELX)).
```
LC
Do the following to calculate LC:
```
LOGSNUM * 4 + 1
```
LTEC

LTEC = 0

LTEX

LTEX = 0

R_le

R_le=1

R_data
Do the following to calculate R_data:
```
R_data=
(AVGBUFSIZE + 4 Bytes
rounded up to the next (256 * (2**LELX)) boundary)
/ (256*(2**LELX))
```
Calculate SIZE and INITSIZE parameter values for the structure definition in the CFRM policy.
Take the TSS and MXSS values for a level 1 coupling facility at service level 4.01 or higher and do the following to calculate SIZE and INITSIZE:
```
INITSIZE=TSS * 4
SIZE=MXSS * 4
```
Example of determining the size of a coupling facility structure.

The following example shows how to calculate the size of a coupling facility structure that has two log streams mapping to it. Note that this example was calculated for a level 1 coupling facility at service level 4.01 or higher.
1. Gather information about the coupling facility structure.
  AVGBUFSIZE
  
  AVGBUFSIZE = 4068
  
  MAXBUFSIZE
  
  AVGBUFSIZE = 65,532
  
  LOGSNUM
  
  LOGSNUM = 2
  
  MXSS-to-TSS
  
  MXSS-to-TSS = 2
  This means that the maximum structure size should be twice the initial structure size.
2. Gather information about each log stream:
  - Log stream information for log stream 1:
    LOWOFFLOAD
    
    LOWOFFLOAD = 0
    
    HIGHOFFLOAD
    
    HIGHOFFLOAD = 80
    
    ResidencyTime
    
    ResidencyTime = 10
    
    WritePerSec
    
    WritePerSec = 5
  - Log stream information for log stream 2:
    LOWOFFLOAD
    
    LOWOFFLOAD = 0
    
    HIGHOFFLOAD
    
    HIGHOFFLOAD = 80
    
    ResidencyTime
    
    ResidencyTime = 10
    
    WritePerSec
    
    WritePerSec = 20
3. Calculate coupling facility structure list entries required per log stream.
  For log stream 1:
```
   Entries = ((100/(HighOffload-LowOffload))*WritePerSec*ResidencyTime)+4
   Entries = ((100/(80-0))*5*10)+4
   Entries = 67
```
  For log stream 2:
```
   Entries = ((100/(HighOffload-LowOffload))*WritePerSec*ResidencyTime)+4
   Entries = ((100/(80-0))*20*10)+4
   Entries = 254
```
4. Calculate the total coupling facility structure size. Use the following data as input to the TSS and MXSS formulas in the PR/SM Planning Guide.
  MLSEC
  
  MLSEC = (254 * 2)
  MLSEC = 508
  
  Note that 254, the entries value for log stream 2 is used to calculate MLSEC because it is the larger of the entries values for the two log streams.
  
  MLSELC
  
  Not used.
  
  LELX
  
  LELX = 1
  
  MDLES
  
  MDLES = 128
  
  LC
  
  LC = 9
  
  LTEC
  
  LTEC = 0
  
  LTEX
  
  LTEX = 0
  
  R_le
  
  R_le = 1
  
  R_data
  
  R_data = 8
  Calculate SIZE and INITSIZE parameter values for the structure definition in the CFRM policy from the TSS and MXSS values:
  MXSS
  
  MXSS = 1472
  
  TSS
  
  TSS = 704
```
SIZE = MXSS * 4
SIZE = 1472 * 4
SIZE = 5888

INITSIZE = TSS *4
INITSIZE = 704 * 4
INITSIZE = 2816
```
If you need to change the coupling facility structure size later, there are two ways you can do that:
- Dynamically alter the coupling facility structure size by entering the SETXCF START,ALTER command or issuing the IXLALTER service.
- Update the CFRM policy with the new coupling facility size, activate the policy, and then have the operator initiate a rebuild of the structure. See Administrative data utility for updating the CFRM policy using the IXCMIAPU utility.
Note, however, that these options should not be substituted for advance planning, which can optimize both capacity and performance. See the following references for more information:
- z/OS MVS System Commands for the SETXCF command.
- z/OS MVS Programming: Sysplex Services Reference for reference information about the IXLALTER service.
- z/OS MVS Programming: Sysplex Services Guide for guidance on using the IXLALTER service.