z/OS logstreams

The z/OS® System Logger provides for collections of data called logstreams, which are written to local storage buffers and then to a sysplex coupling facility or DASD for long-term storage. Logstreams can provide high-performance logging for certain applications.

For general information about logstreams, read z/OS Setting Up a Sysplex (SA22-7625).

WebSphere® Application Server for z/OS can use logstreams for the following types of data:

Data in the WebSphere Application Server error log, which can be routed to a logstream instead of to a print dataset
Data in WebSphere Application Server transaction logs, which can be routed to a logstream instead of to a hierarchical file system (HFS) dataset
Data in WebSphere Application Server Session Initiation Protocol (SIP) recovery logs, which are routed to a logstream

WebSphere Application Server error log

The WebSphere Application Server error log is used to record detailed runtime error and status messages. If the ras_log_logstreamName variable is set, error log messages are written to the named z/OS logstream. If the ras_log_logstreamName variable is not set or if the named logstream does not exist, error log records are written to STDERR.

The primary advantage of sending the WebSphere Application Server error log to a z/OS logstream is that you can consolidate error logs from multiple servers and servant regions. If you place the error logstream in a coupling facility, you can also consolidate error logs from different systems in the same sysplex.

WebSphere Application Server for z/OS provides the following sample jobs to create error logstreams:

BBOERRLC: Create a coupling facility logstream for the WebSphere Application Server error log
BBOERRLD: Create a DASD-only logstream for the WebSphere Application Server error log

Use the copyZOS.sh script to write these jobs to a partitioned dataset.

After you create the logstream, use scripting or the administrative console to set the ras_log_logstreamName variable to the logstream name for all servers whose output is to go to the newly created logstream.

Use the BBORBLOG script in the SBBOEXEC profile dataset to view the error log. Read the Viewing error log contents through the Log Browse Utility article in the documentation for more information.

Transaction XA partner log

The WebSphere Application Server transaction XA partner log is used to record transaction (JTA) information. This information is written to an HFS file or a z/OS logstream, depending on the setting of the transaction directory file for a specific server:

If the transaction directory value is dir://directory_name, the named file system directory is used for storing transaction information.
If the transaction directory value is logstream://logstream_name, transaction information is written to the named logstream.

The default is dir://app_server_root/tranlog/server_name.

By using a z/OS logstream for the WebSphere Application Server transaction log and placing that logstream in a coupling facility, you can improve performance for cross-system restart operations.

WebSphere Application Server for z/OS provides the following sample jobs in the SBBOJCL product dataset to create transaction logstreams:

BBOTXALC: Create a coupling facility logstream for a WebSphere Application Server transaction log
BBOTXALD: Create a DASD-only logstream for a WebSphere Application Server transaction log

Use the copyZOS.sh script to write these jobs to a partitioned dataset.

After you create the logstream, use the administrative console to set an individual server's transaction log to logstream://logstream_name on the configuration tab of the server's transaction service settings (Servers > Server Types > WebSphere application servers > server_name > Container Services > Transaction Service) and restart the server. Read the Transaction service settings article in the documentation for more information.

Note: When an application server is federated into a Network Deployment cell, you must clear any existing transaction errors. If transaction logging is being done to a z/OS logstream, delete the server's transaction logstream after the application server is shut down and recreate it before starting the newly federated application server.

Creating SIP recovery logstreams

If your Network Deployment cell configuration includes replication partners across several LPARs, SIP recovery logstreams must reside in a coupling facility. DASD recovery logstreams can be used only if all replication partners are on the same LPAR.

SIP logstreams must follow a very specific pattern for their names: CELL_NAME.SERVER_NAME.D and CELL_NAME.SERVER_NAME.M.

You might experience errors that indicate that a logstream is full or corrupted. In this situation, you might need to delete and redefine the logstream. The following examples show jobs that can be used to perform these actions:

Delete the logstream:

//DEFLOGA  JOB MSGLEVEL=(1,1),MSGCLASS=H,NOTIFY=&SYSUID,REGION=0M 
//*                            
//LOGDEFN  EXEC PGM=IXCMIAPU,REGION=4M      
//SYSPRINT DD   SYSOUT=*       
//*                            
//SYSIN    DD   *              
     DATA TYPE(LOGR)           
     DELETE LOGSTREAM          
     NAME(WT0CELL.WT0S000.M)   
     DELETE LOGSTREAM          
     NAME(WT0CELL.WT0S000.D)   
     DELETE LOGSTREAM          
     NAME(WT0CELL.WT0S001.M)   
     DELETE LOGSTREAM          
     NAME(WT0CELL.WT0S001.D)
/*

Recreate the logstream:

//DEFLOGA  JOB MSGLEVEL=(1,1),MSGCLASS=H,NOTIFY=&SYSUID,REGION=0M  
//*                                
//LOGDEFN  EXEC PGM=IXCMIAPU,REGION=4M             
//SYSPRINT DD   SYSOUT=*           
//*                                
//SYSIN    DD   *
     DATA TYPE(LOGR)
     DEFINE LOGSTREAM 
     NAME(WT0CELL.WT0S000.M)
     DASDONLY(YES)
     HLQ(LOCAL) MODEL(NO)
     LS_SIZE(2048)
     STG_SIZE(2048)
     LOWOFFLOAD(60)
     HIGHOFFLOAD(80)
     DEFINE LOGSTREAM
     NAME(WT0CELL.WT0S000.D)     
     DASDONLY(YES)
     HLQ(LOCAL) MODEL(NO)
     LS_SIZE(2048)
     STG_SIZE(2048)
     LOWOFFLOAD(60) 
     HIGHOFFLOAD(80)
     DEFINE LOGSTREAM
     NAME(WT0CELL.WT0S001.M)
     DASDONLY(YES)
     HLQ(LOCAL) MODEL(NO)
     LS_SIZE(2048)
     STG_SIZE(2048)
     LOWOFFLOAD(60) 
     HIGHOFFLOAD(80)
     DEFINE LOGSTREAM
     NAME(WT0CELL.WT0S001.D)
     DASDONLY(YES)
     HLQ(LOCAL) MODEL(NO)
     LS_SIZE(2048)
     STG_SIZE(2048)
     LOWOFFLOAD(60)    
     HIGHOFFLOAD(80)       
/*     
//