Page tree
Skip to end of metadata
Go to start of metadata

This document will help users who wish to install, configure, and use any of the z/IRIS components.

  • Purpose of this document

    This document will assist users who wish to:

    • Understand the requirements for a z/IRIS installation
    • Install, customize and z/IRIS IronTap on Linux
    • Install, customize and z/IRIS z/OS Client
    • Troubleshooting z/IRIS z/OS Client

    Background

    z/IRIS is a Java based software solution which offloads z/OS application and system information, which is interpreted to be made meaningful and readable, allowing quick and easy

    integration into other systems, applications or products which can process this information. The goal of z/IRIS  is to remove the barrier of understanding and locked-in knowledge

    which prevents many service providers from being able to tackle and address their customers needs with regards to their mainframe environment.

    z/IRIS is a Client-Server solution over TCP/IP written in Java and HLASM . The z/OS Client ( IBM Java 8 ) connects to the z/IRIS IronTap Linux server, which processes, parses and

    normalizes the system and application information from z/OS and presents this information to outside applications or products. Currently, z/IRIS IronTap will present all z/OS information

    in JSON format, but further development is always underway which means that various data presentation formats will be included in the product over-time.


    In summary z/IRIS was built to satisfy the following needs:

    • Provide meaningful and readable z/OS Application and System Information for easy integration in to other distributed solutions and platforms.
    • Open-up the mainframe to cutting-edge technologies without service providers requiring in-depth understanding of the mainframe or z/OS to cater for 
      mainframe customers and environments.
    • Offload mainframe application and system information for processing outside mainframe using Java to reduce processing impact on the mainframe.
    • Give the mainframe the flexibility to be included in monitoring software otherwise unattainable due to the sparse expertise in mainframe



    z/IRIS IronTap

    z/IRIS IronTap is a software product written in Java, which parses detailed information from the z/OS client and transforms it in to an appropriate format for further

    processing by trace systems.

    Using a streamlined connection directly to the z/IRIS z/OS Client IronTap processes live z/OS trace data, near real-time. For a list of available trace features with z/IRIS,

    see z/IRIS Trace Features

    Prerequisites for z/IRIS IronTap  

    Please refer to the minimum hardware and software requirements page for further details.

    Any software or product selected to receive and process data from z/IRIS, must be active or running before to IronTap is started. See z/IRIS IronTap Integration Considerations

    for more information.

    Preparing your Linux environment for z/IRIS IronTap

    Downloading z/IRIS IronTap

    • All z/IRIS software, including z/IRIS IronTap can be downloaded from the mainstorconcept Download Portal
      New users should register here first, before attempting to download any software.

      All required z/OS licenses are obtained through a valid license agreement. For more information please email us at: info@mainstorconcept.com

    Installing z/IRIS IronTap

    • Create the IRONTAP_INSTALL_DIR folder '/opt/msc'
    • Extract the "ironTap-vX.Y.Z.zip" file you downloaded into the IRONTAP_INSTALL_DIR path
    • Enter following command to mark the file run.sh as executable:

      chmod +x /IRONTAP_INSTALL_DIR/run.sh

    File Descriptions and Functions

    IronTap-vX.Y.Z-bin.jar

    is the core file which offers the whole back-end for processing z/OS tracing information.

    config.yaml

    defines settings for the application. More info in "Configuring z/IRIS IronTap"

    run.sh

    is a bash script to actually run the application


    Configuring z/IRIS IronTap 

    The config.yaml configuration file contains the following properties: 

    • smfQueueLimit: Default=10000 
      maximum number of smf records queued for further processing
    • (deprecated since 1.2.0) senderThreads this value is not used anymore
    • senderSpanQueueLimit: Default=1000 
      is the maximum number of Spans queued to be send to Instana
    • transformerMapperThreads: Default=2 
      is the number of threads used to parse and order incoming smf records
    • transformerMatcherThreads: Default=3
      is the number of threads used to collect smf records that belong to a trace
    • smfListenerPort: Default=None
      is the listener port which the z/OS client uses to connect to IronTap
    • smfDumpFilePath: Default=None
      is the file path where raw smf dump files are written (for debug purposes)

      smfDumpFilePath=/opt/msc/smfrecords specifies the complete file name and path.

      smfDumpFilePath=/opt/msc/ specifies only the directory path. The file name is then derived from the local date time using ISO-8601 extended offset date-time format (':' replaced with '.')

      Leave this smfDumpFilePath empty to disable the smf dump

    • smfDumpFileCompressed: Default=true

      Enable smf dump compression

    • instanaSpanDumpDirectoryPath: Default=json
      File directory for json span dumps (for debug purposes)

      Leave the instanaSpanDumpDirectoryPath empty to disable this feature

    • ebcdicCodepage: Default=IBM1047 

      Canonical name (java.nio API) for the Mainframe smf encoding.

    • traceField: Default=ClientHostName
      the client information property field (JDBC) the instana agent uses to set trace information (can be either "ClientHostName" or "ApplicationName")

      See z/IRIS Integration Considerations for more information

    • traceDelimiter: Default=None
      A single ASCII character (except "0-9" and "a-f", "A-F") that will be used to separate the trace information

      Example

      traceDelimiter=|


      This pipe delimiter will be used when inserting correlating tag information on distributed calls for end-to-end trace capabilities.

      See z/IRIS Integration Considerations for more information

    • maxSmfToBeProcessed: Default=500000
      maximum amount of smf records kept in memory

      WARNING

      If this number is exceeded, all queued SMF records will be discarded.

    • maxSmfPerDB2Thread: Default=300000
      maximum amount of smf records kept in memory per Db2 jdbc thread

      WARNING

      If this number is exceeded, all queued SMF records associated with a Db2 jdbc thread, will be discarded.

    • logSmfDataOnError: Default=true
      An smf parsing error will be logged including the whole smf record

      Info

      If you don't want to dump the smf records, you can disable this feature by setting it to 'false'.

    Using z/IRIS IronTap

    • Navigate to the IRONTAP_INSTALL_DIR
    • Run the following command to start the application: ./run.sh

    • Use the following command to see the log information and statistics in real time:

      tail -f ./logs/irontapInfo.log


    • Below is an example of the expected output: 

    • The following message indicates that a z/IRIS z/OS Client is connected: 

      z/IRIS z/OS Client connected
      New smf server connected: <ipAdress>"
    • The following message indicates that the span dump path has been created, based on the instanaSpanDumpDirectoryPath value in the config.yaml file:

      Writing Instana spans to <path to directory>

    Logging overview

    The following example is used to explain the z/IRIS IronTap logging:

  • Active connections: 1
    The number of z/IRIS z/OS clients currently connected to the IronTap server (max. 128 connections)
  • smf record count: 136 (57 KByte)
    This shows the total number of records as well as the amount of data the system received since its startup
  • SMF queue: 0
    Number of records in the input queue
  • to be processed: 0 
    Number of records for which the current transaction is not finished yet
  • discarded: 76/136 
    Number of records which won't be used for tracing. (In the above example: There are 136 records in total of which 76 have been discarded)
  • Match count: 6
    Number of spans resulted from performance record correlation.

This number is only visible when performance records are enabled.
Accounting records are being sent directly to the agent, while the performance records depend on a particular order

  • Enqueued for dispatch: 30/30 spans
    Number of spans ready to send to Instana

  • dropped: 0
    Number of spans dropped
  • sent to agent: 30
    For Instana APM integration: Number of spans actually sent to the Instana agent (one span can contain multiple smf records)

Debug features

Activating debug features can have a performance impact on the system

Span dumps

this feature is enabled by setting a non empty string for the instanaSpanDumpDirectoryPath property. Irontap will write all spans into the provided directory. Multiple spans may be joined together into a json array in one file.

2019-05-07T14.40.29.955+02.00-204.json

Each file name consists of a timestamp (when this span was sent to the agent) followed by a dash and the agent http response code or the string "connection-error" if no connection could be established.

Smf dumps

this feature is enabled by setting a non empty string for the smfDumpFilePath property. Irontap will write all smf records to disk. You may provide either a filename or a directory. If you provide a directory irontap will create a new file during each system start e.g.: 2019-01-24T14.30.00.00.smf. If you provide a filename irontap will always append to the file.

During high smf throughput from the z/IRIS z/OS Client, smf dump files can become very large in a short amount of time.

z/IRIS IronTap Integration Considerations 

Instana APM

  • You must have a running Instana agent otherwise IronTap is not able to send Spans to the Instana APM  back-end.
  • In some cases end-to-end application tracing into the mainframe requires a trace tag to be inserted on the distributed calls, for example Distributed DB2 for z/OS tracing. To configure end-to-end tracing, the required instrumentation must be enabled by setting the appropriate JVM options.

z/IRIS Troubleshooting

z/IRIS Troubleshooting



z/IRIS z/OS Client

The z/IRIS z/OS Client is a IBM JZOS based application, built to connect to the z/IRIS Linux server (IronTap) and forward selected z/OS application and system information.

Setting up the z/IRIS z/OS Client is simple and but will require users with access to:

  • Updating SMFPRMxx Parmlib member
  • Add and Change RACF User and Resource definitions
  • Creating and Mounting zFS directories
  • Applying extended attributes to OMVS files
  • Modifying OMVS file attributes

Once all configuration has been completed, the z/IRIS z/OS Client is activated through MVS as a started task and runs in its own address space until a shutdown command is issued, using standard MVS commands

Prerequisites  for z/IRIS z/OS Client 

Please refer to the minimum hardware and software requirements page for further details


Downloading z/IRIS z/OS Client

  • All z/IRIS software, including z/IRIS z/OS Client can be downloaded from the mainstorconcept Download Portal
    New users should register here first, before attempting to download any software.

    All required z/OS licenses are obtained through a valid license agreement. For more information please email us at: info@mainstorconcept.com

Preparing your mainframe environment for the z/IRIS z/OS Client

The following is assumed from this point:

  • The user intending to install and configure z/IRIS has the necessary authority to do so
  • The required z/IRIS IronTap Server is configured and available for connection 
  • z/IRIS IronTap and z/OS Client are licensed property of mainstorconcept GmbH, the use of this product is therefore subject to a license agreement which provides access 
    to license key files required to make use this software.
  • z/OS version 2.1 or later is installed and configured appropriately

Java preparations for z/OS

Download IBM SDK for zOS component

 

At the time of writing this document, IBM Java SDK 1.8 was the most recent package available for z/OS.  z/IRIS z/OS Client was built using the Java SE 8 capability only. 
Obtain the IBM Java SDK from the following URL: https://developer.ibm.com/javasdk/support/zos/. All required documentation should be available at this site.

This section will provide the minimum necessary steps to install the IBM Java SDK component. 

Download the following file: 

  • SDK8_64bit_SR%_FP%%.PAX.Z 

    Always make use of the latest release and fix pack available for IBM Java 8 through the IBM Website


    Consult the IBM README.txt contained in the compressed pax file for more detailed information.


Create and Mount a JAVA_HOME directory path

  • In z/OS OMVS / USS, create a directory for Java v8 64bit, for example:

    mkdir /usr/lpp/java/Java800_64


    For the purposes of this document we will refer to this directory as $JAVA_HOME.


  • Issue a TSO MOUNT using the allocated dataset filesystem and the newly created directory as the mountpoint with MODE(RDWR) and TYPE(ZFS):

    MOUNT cmd example
    MOUNT FILESYSTEM('OMVS.JVB805.HFS') TYPE(HFS) MODE(RDWR) MOUNTPOINT('/usr/lpp/java/Java800_64') 

Upload the IBM JAVA SDK

  • The easiest way to transfer the SDK to z/OS USS is to FTP the file in BINARY mode:

    FTP example 1
    ftp
    open hostame
    user ibmuser xxxxxx
    binary
    cd /usr/lpp/Java800_64/
    put SDK8_64bit_SR5_FP11.PAX.Z
    
    quit


    OR



    FTP example 2
    ftp
    open hostame
    user ibmuser xxxxxx
    binary
    put SDK8_64bit_SR5_FP11.PAX.Z   'yourhlq.SDK8.64bit.SR5.FP11.PAX.Z
    quit

    yourhlq - this is a valid hlq for Data Sets at your site



Extract the file

  • Change directory to $JAVA_HOME and unpax the uploaded SDK8_64bit_SR5_FP11.PAX.Z file. If you uploaded it to the zFS or HFS, use:

    pax -ppx -rvzf SDK8_64bit_SR5_FP11.PAX.Z
    

    or if the file was uploaded to a dataset, use:

    pax -ppx -rvzf "//'yourhlq.SDK8.64bit.SR5.FP11.PAX.Z'"
    
  • If you are not able to restore the code archive with this command, it may be because you do not have the necessary authority o restore the program control bit: 

    Required authorisation: To restore the files with the proper permission bits, you must have the following authority:

    • UID(0) or access to BPX.SUPERUSER.FACILITY class
    • Access to BPX.FILEATTR.APF
    • Access to BPX.FILEATTR.PROGCTL

    Access to BPX.FILEATTR.SHARELIB Note: Access to BPX.FILEATTR.* could be used instead.This is the typical authority you require to install z/OS.

Copy the Java Batch modules to the LINKLST library (must be APF authorized)

  • Issue the following commands to copy the files from zFS to data sets:

    cd $JAVA_HOME/mvstools
    cp samples/jcl/JVMJCL86 "//'SYS1.SAMPLIB(JVMJCL86)'"
    cp samples/jcl/JVMPRC86 "//'SYS1.PROCLIB(JVMPRC86)'"
    cp -X JVMLDM86 "//'SYS1.SIEALNKE(JVMLDM86)'"

    The above SYS1.** data sets are the default data sets, please confirm with the System Programmer which LINKLST Libraries are appropriate for this site.



BPXPRMxx changes

  • Minimum requirements: 
    ParameterValue
    MAXPROCSYS900
    MAXPROCUSER512
    MAXUIDS500
    MAXTHREADS10 000
    MAXTHREADTASKS5 000
    MAXASSIZE2 147 483 647
    MAXCPUTIME2 147 483 647
    MAXMMAPAREA40 960
    IPCSEMNIDS500
    IPCSEMNSEMS1 000
    SHRLIBRGNSIZE67 108 864
    SHRLIBMAXPAGES4 096

    For more information regarding these and other BPXPRMxx options and limits, please refer to the  IBM z/OS Unix System Services Planning Guide publications.


Security preparations for z/OS with RACF


  1. SMF In-Memory Resources can only be accessed once they have been defined to RACF.
    Decide on an In-Memory Resource Name for DB2 SMF Record types 102, with a maximum of 26 characters.
    Example IFASMF.INMEM.SMF102
    The RACF Resource Name must be the same as the name defined above, prefixed with "IFA." as as prefix. Therefore, the RACF resource name for the above In-Memory Resource is: IFA.IFASMF.INMEM.SMF102.
    Define the Resource to RACF class Facility, using the following TSO Command:

    RDEFINE FACILITY IFA.IFASMF.INMEM.SMF102
    SETROPTS RACLIST(FACILITY) REFRESH


  2. The  zIRISzOSClient.v%.%.%.zip  contains a file called RACFJCL.txt. This is a z/OS Job which creates a surrogate userid for z/IRIS using IBM RACF commands. Upload this file via FTP as text, customize the job as required and submit. 

    The settings detailed in the RACFJCL are not final, and some settings can be omitted. To ensure a problem free installation, consult you mainstorconcept Technical Professional regarding any changes to RACF permission in RACFJCL before proceeding with the installation.

    For customers not using IBM RACF as a Security Server on z/OS, the appropriate access must be provided to the userid associated with the started task as well as for the In-Memory Resource. For assistance, please contact mainstorconcept GmbH


SMF preparations for the z/IRIS z/OS Client


  1. Naming considerations


    All in-memory resource must follow the naming standard: IFASMF.rname (Reference:https://www.ibm.com/support/knowledgecenter/SSLTBW_2.3.0/com.ibm.zos.v2r3.ieag200/smfinmemhow.htm)The z/IRIS z/OS client autmaticall connect to any resource with prefixed  IFASMF.INSTANA.*
    Any resource name may be used.
    If the second qualifier is not Instana, the resource will be defined in the ziris.comm.config $APP_HOME/lib file later on in the configuration

  2. This document only describes the required steps for the purposes of the z/IRIS applicaton, should further information be required please refer to the IBM Documentation:
    +}https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zos.v2r3.ieag200/custom.htm+
    Create a new SMFPRMxx member in the appropriate concatenated PARMLIB data set.
    Copy all settings from the active SMFPRMxx member and save the new member.
    Add the following SMFPRMxx parameters:

    INMEM($INMEM_NAME,RESSIZMAX(nM),TYPE(ttt)) 


    where:

    1. $INMEM_NAME is the In-Memory Resource Name for DB2 SMF Record types 102 from chapter 3.2

    2. RESSIZMAX(nM) defines the resource maximum size, in this case 128M. Up to 2GB can be defined if required. 

      When the resource reaches the maximum defined here,the in-memory resource wraps and overwrites the oldest SMF records with the newest SMF records.

      mainstorconcept GmbH may have provided you with recommended size which should be used here, otherwise System Programmers and Administrators have discretion on this parameter, based on the rate at which SMF Records will be generated.

    3. TYPE(ttt) defines the SMF Record Type that is written to the in-memory resource. The type is dependent on the Features which your organisation wants to take advantage of. Refer to the zirisfeatureszos

    The following is an example SMFPRMxx member. Here we see the In-Memory Resource Name described in chapter 3.2, SMF Record Types 102 will be written to this in-memory resource, and the maximum size is 128 MB.

    In this example the Logstream includes SMF Type 102 as well, which means these records will be written to both the Logstream and the in-memory resource. To avoid this duplication, exclude the SMF type 102 from the Logstream definition explicitly.



  3. Save the PARMLIB member
  4. At this point it, please ensure all DB2 traces have been stopped. To do so, issue the following DB2 command:

    STOP TRACE(*)
  5. Issue the following MVS command to activate the the new In-Memory resource dynamically: 

    /SET SMF=xx


    where xx is equal to the suffix of the new SMFPRMxx parmlib you created in this chapter.
    The log output should reflect the new In-Memory Resource, similar to the following output:

  6. Change the IEASYSxx PARMLIB member to point to this new SMFPRMxx member.




zFS  preparations

  1. Create a new ZFS directory, this directory  will be referred to as  $APP_HOME in this document.
    You may want to create a new Mount entry for this zFS directory depending on your sites requirements. The minimum amount of space required is for z/IRIS: 2000K

    mkdir /usr/lpp/ziris/ 


Install and Configure z/IRIS

Upload and Install z/IRIS

  1. In the  zIRISzOSClient.v%.%.%.zip  is a tar file called zirisv100.pax

    Upload this file to the $APP_HOME directory created in STEP 3.4 in binary mode .

  2. Once the file has been uploaded, unpack the file using the tar command:

    pax -w[v]f zirisv100.pax


    use the -v option only if you want to see verbose output.

    Take not of the extended attributes associated with some of the files, if the files do not match this criteria, you will have to apply the extended attributes manually.

    $APP_HOME/ list
    -rw-r--r--   1 zirisv100.jar
    drwxr-x---   2 lib
    drwxr-x---   2 bin
    drwxr-xr-x   2 tmp
    
    


    APP_HOME/bin listing
    -rwxrwxr-x   1  sraget00
    -rwxrwxr-x   1  sradsc00
    -rwxrwxr-x   1  sracon00
    -rwxrwxr-x   1  CONSL001
    $APP_HOME/lib list
    -rw-rw-r--   1 mscSecureSocketProvider.jar
    -rw-rw-r--   1 ibmjzos.jar
    -rw-rw-r--   1 mscZosLicenseV2R0.jar
    -rw-rw-r--   1 ziris.properties
    -rw-rw-r--   1 ziris.comm.config
    drwxr-x---   2 security

Upload License File

mzHost.lic file is supplied seperately (i.e. not part  included in the downloadable software package). If you have not received this file, contact mainstorconcept GmbH for further assistance.
Upload the mzHost.lic to the $APP_HOME and should be set at 640 or Read-only for all users and groups.


Configure z/IRIS

  1. Change directory to the $APP_HOME/lib directory
  2. Open ziris.comm.config in edit mode, the supplied file should look like this:

    $APP_HOME/lib/ziris.comm.config
    alias=zirisprod              
    mode=tcp                     
    host=server:port             
    timeout=7                    
    inmem=smf.inmem.db2
    inmem=smf.inmem.cics     
    cicshlq=DFH420.CICS42
  3. Edit the ziris.comm.config using the syntax and paramater information detailed below.

    ziris.comm.config Parameters

    Layout:

    alias=Alias_Name

    mode=tcp|udp|mq

    host=IPv4_address:port 

    timeout=timeout_value_seconds 

    inmem=SMF_Inmem_Resource 

    optional configuration: 

    ssl=N[o] | Y[es]



    Parameter Values:

    • alias=Alias_Name
      This is a locally defined alias name that refers to the remote z/IRIS IronTap Server Agent. This can be any name with alphanumeric characters, without spaces or special characters (i.e. @!§$%&/() etc.)
      It is highly recommended that the Alias name be kept short for readability.

    • mode=tcp|udp|mq
      Default:tcp
      This defines the desired network communication protocol, TCP or UDP. TCP is default and supported by Remote z/IRIS IronTap server. UDP and MQ are for future use only.

    • host=IPv4_address:Port_Number
      IPv4_Address: must be the IP address of the remote z/IRIS IronTap server
      Port_Number: must be the connectable port of the remote z/Iris Iron Tap Linux Server

    • timeout=timeout_value_seconds
      The amount of time in seconds used as a connection and communication timeout value. This can be any integer value, but must be within the norms of the sites network.

    • inmem=SMF_Inmem_Resource
      SMF_Inmem_Resource to the SMF in-memory resource defined in the SMFPRMxx parmlib member. 

    • If the in-memory resource name is prefixed with IFASMF.INSTANA, the z/IRIS z/OS Client will automatically connect to it, and should not be specified here.

      All in-memory resources that have been created for z/IRIS should be listed here.


      Mutliple in-memory resources will be defined as follows:

      inmem=IFASMF.INMEM.SMF30
      inmem=IFASMF.INMEM.SMF70
    • Optional Configuration:


      • ssl=N[o] | Y[es]
        Default:Yes
        Enable or disable SSL encrypted and trusted communication with the remote z/IRIS IronTap server

      • reconnect=999
        Default: 10
        Configure the amount of seconds z/Iris will wait before trying to reconnect to the remote z/IRIS IronTap server
        Any valid Integer representing seconds is accepted

      • maxTCPSend=99999
        Default: 65536
        Configure the maximum number of bytes allowed for TCP traffic from z/Iris to the remote z/IRIS IronTap server. This should be equal to or less the than z/OS TCP max send buffer size.
      • cicshlq=cicstshlq
        Default: None
        Enter the HLQ for CICS Transaction Server data sets. For example the HLQ for the CICS SDFHLOAD, data set



Extended attributes

  • The extended attribute for the $APP_HOME/bin/CONSL001 must be:
    +a : apf authorized
    +s : shared address space
    issue the following command: 

    cd $APP_HOME
    extattr +a ./CONSL001
  • All files within the $APP_Home/bin path must be executable, issue the following command:

    cd $APP_HOME/bin
    chmod +x ./*



Workload Manager Considerations


The zIRIS STC should be defined with low / discretionary priority in WLM. (i.e. not in the SYSSTC service class)

Please consult your mainstorconcept Technical Professional if you require any assistance in this regard


Using the z/IRIS z/OS Client

The z/IRIS z/OS Client Started Task

  1. Upload the ZIRIS.jcl file from the zIRISzOSClient.v%.%.%.zip to a concatened PROCLIB Dataset. 

    MNDUP Step in the zIRIS.jcl proclib member is currently optional. This has been included in preparation for further z/IRIS CICS TG/TS performance information streaming in future releases

    sample ZIRIS PROCLIB JCL
    //******************************************************************* 
    //* Z/IRIS FOR INSTANA MONITORING. PROPERTY OF MAINSTORCONCEPT GMBH    
    //* CUSTOMIZE THE FOLLOWING FIELDS:                                   
    //* $APPHOME = THE APP_HOME DIRECTORY FROM INSTALLATION GUIDE         
    //* $JVAHOME = THE JAVA_HOME DIRECTORY FROM INSTALLATION GUIDE        
    //* CICSHLQ  = THE CICS HLQ for SDFHLOAD data set                     
    //* NB:                                                               
    //* COMMENT OUT MNDUP STEP TO GENERATE CICS DICT FOR CICS 
    //* PERFORMANCE TRACE PARSING                                                     
    //******************************************************************* 
    //SETUP   SET  APPHOME='/usr/lpp/zIRIS',                              
    //             JVAHOME='/usr/lpp/Java800_64/J8.0_64',                 
    //             CICSHLQ='DFH420.CICS',                                 
    //             ZIRISHLQ='ZIRIS'                                       
    //****************************************************************
    //* Step 1 IS OPTIONAL. This is in preparation for CICS TG/TS 
    //* performance information streaming.   
    //* Step 1 - Create new dictionary record and output to SYSUT4 *      
    //* Customize: 
    //* ssid    = The subsystim Id where this CICS subsystem runs
    //* gapplid = APPLID found in system initialization parm or generic 
    //*           in an XRF environment 
    //* sapplid = Communications Server APPLID of the CICS region
    //*           if excluded, the gapplid will be used
    //****************************************************************    
    //*MNDUP EXEC PGM=DFHMNDUP                                             
    //*STEPLIB DD DISP=SHR,DSN=&CICSHLQ..SDFHLOAD                          
    //*SYSUT4  DD DSN=&ZIRISHLQ..CICS.MNDUPREC,DISP=(NEW,PASS,KEEP),       
    //* UNIT=SYSDA,SPACE=(TRK,(1,1))                                       
    //*SYSPRINT DD SYSOUT=A                                                
    //*SYSUDUMP DD SYSOUT=A                                                
    //*SYSIN DD *                                                          
    //*MCT=NO                                                                
    //*SYSID=ssid                                                           
    //*GAPPLID=gapplid                                                      
    //*SAPPLID=sapplid                                                                                                                                                                         
    /*                                                                    
    //****************************************************************    
    //* Step 2 - Start z/IRIS z/OS Client                            *    
    //* Uncomment SYSUT4 DD statement if a CICS dictionary record    *
    //* should was generated in the MNDUP Step                       *
    //****************************************************************    
    //JAVA EXEC PROC=ZIRISJVM,                                         
    // JAVACLS='com.msc.zos.ziris.zIrisClient',                        
    //   LOGLVL='+T'                                                   
    //*ARGS=&PARM1                                                     
    //STDOUT   DD SYSOUT=*                                             
    //STDERR   DD SYSOUT=*                                             
    //SYSABEND DD SYSOUT=*                                             
    //SYSMDUMP DD SYSOUT=*                                             
    //SYSUDUMP DD SYSOUT=*                                             
    //*SYSUT4   DD DSN=&ZIRISHLQ..CICS.MNDUPREC,DISP=(SHR,DELETE,DELETE)
    //STDENV   DD *                                                    
    ###################################################################    
    # Change $APPHOME to the z/Iris APP_HOME directory, refer to the       
    # installation Guide for more details                                  
    ###################################################################    
    export APP_HOME=$APPHOME                                     
    ###################################################################    
    # Change $JVAHOME to the IBM JAVA_HOME directory, refer to the         
    # installation Guide for more details                                  
    ###################################################################    
    export JAVA_HOME=$JVAHOME                          
    ###################################################################    
    # End of Customization, remaining lines should not be changed.         
    ###################################################################    
    . $APP_HOME/lib/ziris.properties                                                               
  2. Change $APPHOME in JCL to the $APP_HOME directory created for z/IRIS in zFS
  3. Change $JVAHOME to the $JAVA_HOME directory where IBM Java version 8 resides
  4. Save the job as ZIRIS. If ZIRIS is not available, you may use a different name, but, please note that this job name is related to the job name in the RACFJCL for CLASS STARTED permissions. If the job name is not ZIRIS, you will need to amend the permissions for the surrogate Userid created: 

    RDEFINE STARTED JOBNAME.** UACC(NONE) STDATA(USER(ZIRIS) +
    GROUP(SYS1) TRUSTED(YES))
  5. Upload the ZIRISJVM  jcl file to a concatenated PROCLIB data set from the zIRISzOSClient_v100.zip file. This proclib member contains the required JVM options to start the z/IRIS z/OS Client,


Starting the Started Task

  1. To start the z/IRIS z/OS client started task, issue the following MVS Command:

    /S ziris

    where ziris is the member name of the ZIRIS proclib member

    Failed Connection

    Should a failed connection message displayed during initial connection with the z/IRIS IronTap Linux Server, please check that the z/IRIS Linux Server instance is active and ports are open or a connection


 

Stopping the Started Task

  1. To stop the started task issue the following MVS command:

    /P ziris

    where ziris is the name of running z/IRIS STC address space


z/IRIS z/OS Logging and Error Messages

  • STDOUT and STDERR are merged by default into SYSOUT. 
  • The Started task will send messages to the SYSLOG when the messages require immediate attention, for example a TCP connection was lost and will try to reconnect as defined in the ziris.comm.config file.
  • Example SYSOUT from z/IRIS z/OS Client started task:

     Jul 17, 2018, 5:46:02 PM | ZIRIS z/Iris Startup V2R4
     Jul 17, 2018, 5:46:03 PM | ZIRIS Reading config File...
     Jul 17, 2018, 5:46:03 PM | ZIRIS z/Iris Settings: Host=<hostname>, serverPort=<port>,
                               Inmem=IFASMF.INMEM.SMFDB2, timeout=7, mode=tcp,
                               server Alias=zirisprod, reconnect=7, maxTCPBuffer=2000
     Jul 17, 2018, 5:46:03 PM | ZIRIS Preparing MVS Console for interaction ...
     Jul 17, 2018, 5:46:04 PM | ZIRIS z/Iris ready to receive modify and shutdown commands
     Jul 17, 2018, 5:46:04 PM | ZIRIS Preparing SMF Streaming
     Jul 17, 2018, 5:46:06 PM | ZIRIS 01 Listener started
     Jul 17, 2018, 5:46:07 PM | 01 SRA030I zIRIS v2r4 SMF Streaming initializing
     Jul 17, 2018, 5:46:07 PM | 01 SRA003I SMF stream started, Buffer=65536
     Jul 17, 2018, 5:46:21 PM | ZIRIS 01 sending disconnect command.
     Jul 17, 2018, 5:46:22 PM | 01 SRA002I SMF streaming ended, see related messages
     Jul 17, 2018, 5:46:22 PM | 01 SRA015I SMF Stream shut down successfully
     Jul 17, 2018, 5:46:22 PM | ZIRIS z/Iris is shutting down

Interacting with z/IRIS through MVS modify commands

  • z/OS users with SDSF and MVS command permissions, can interact with the z/IRIS Client started task through MVS modify commands.
    z/IRIS MVS comsand syntax :

    /F ziris,APPL=cmd

    where:

    ziris:  is the name of the Z/IRIS STC

    cmd:  is a valid z/IRIS modify command


z/IRIS MVS Commands

  • HELP

    lists and displays information about available commands

    /F ZIRIS,APPL=HELP
  • STATUS

    displays a summary of current connections with SMF and the z/IRIS IronTap Linux Server

    z/IRIS modify command example
    /F ZIRIS,APPL=STATUS

    Sample response

    z/IRIS modify command example output
    RESPONSE=CPAC      BPXM023I (SMFRAPI) ZIRIS will accept the STOP(P) and
    RESPONSE=Modify(F) commands                                            
    RESPONSE=CPAC      BPXM023I (SMFRAPI)                                  
    RESPONSE=CPAC      ZIRIS STATUS Jul 18, 2018, 12:01:34 PM              
    RESPONSE=CPAC      TCP Connection:  active to /172.25.999.999:9999     
    RESPONSE=CPAC      Number of Listeners: 1                              
    RESPONSE=CPAC      Listener 1 streaming from IFASMF.INMEM.SMFDB2  

z/IRIS Features and Trace requirements for z/OS

All z/IRIS Features are built to extract specific information from the mainframe, which is parsed and normalised before being given over to a third party application. Each feature will have its own traceing requriement, dependant on the component being traced and the complexity of tracing the component.

Feature: Distributed DB2 for z/OS Tracing 

With z/IRIS, mainframe customers and ISVs  can now  correlate distributed DB2 for z/OS calls made using JDBC 4.0 . From performance traces which delivers low-level performance information (but are very expensive) to accounting and deadlock events traces.

Deadlock event traces provide from mainframe  help users connect Deadlocks and timeouts experience as well as see which application was holding a resource up during the deadlock scenario.

The Transaction-Trace-Set provides trace information per UOW (grouped by commit or rollback) provides information about the jdbc transaction: response and processor timers per transaction, types of SQL work performed, the amount of statements processed etc. Transaction-trace-sets are much less expensive than the performance trace sets


DB2 SQLInfo-Trace-Set 

This trace-set provides detailed low-level performance information regarding JDBC SQL calls processed DB2 Address space, detailing amongst other information:

To enable this trace-set for to be processed by z/IRIS, the following DB2 Trace command must be issued to the relevant DB2 Subsystem:

-START TRACE(PERFM) CLASS(30) IFCID(58,59,60,61,62,63,64) DEST(SMF) TDATA(CORRELATION) [SCOPE(GROUP)]

Your System programmer must ensure that the correct SMF in-memory resources have been defined to capture the SMF Record Types 102. 

Refer to the SMF Preparations in this document for more information.

Use this trace set in pre-production or development environments, as part of QA

It is not recommended to run this type of trace in a productive environment.



DB2 Deadlock-Trace-Set 

This trace-set provides more in-depth DB2 information regarding a deadlock that occurred. We provides information regarding the Holder and Waiter information, which assist DB2 administrators and programmers track the affected applications as well as the initial holder during this deadlock scenario.

To enable this trace-set to be processed by zIRIS, the following DB2 Trace command must be issued to the relevant DB2 Subsystem:

-START TRACE(PERFM) CLASS(32) IFCID(172) DEST(SMF) TDATA(CORRELATION) [SCOPE(GROUP)]

Your System programmer must ensure that the correct SMF in-memory resources have been defined to capture the SMF Record Types 102. 

Refer to the SMF Preparations in this document for more information.


DB2 Transaction-Trace-Set 

This trace-set captures the accounting information, grouped by Unit-of-Work, for JDBC calls processed at the DB2 Address space. The Unit-Of-Work is ended at commit or rollback by the client DB2 application. 

To enable this trace-set to be processed by zIRIS, the following DB2 Trace command must be issued to the relevant DB2 Subsystem:

-START TRACE(ACCTG) CLASS(1) IFCID(3) DEST(SMF) TDATA(CORRELATION) [SCOPE(GROUP)]

Note for Instana APM customers

In future releases, it will be mandatory to activate a second performance  trace trace for Instana span correlation. This information will be updated here.

-START TRACE(PERFM) CLASS(30) IFCID(xx) DEST(SMF) TDATA(CORRELATION) [SCOPE(GROUP)]

In order to receive records for actual UOWs in the DB2 Address space, the DB2 ZPARM ACCUMACC must be set to NO. if ACCUMACC is left active, the accounting records are rolled-up by the chosen aggregation field also specified in the ZPARM. Please see the following IBM web pages for more information regarding the affected parameters:

DDF/RRSAF ACCUM field (ACCUMACC subsystem parameter)

AGGREGATION FIELDS field (ACCUMUID subsystem parameter)

  • No labels