Skip to end of metadata
Go to start of metadata
 Click to expand table of contents...





This document will help users who wish to install, configure, and use z/IRIS v1.6.0. The following will be covered in this document:

  • Install and customize z/IRIS IronTap (Linux server).
  • Install and customize z/IRIS z/OS clients.


z/IRIS is a Java-based software product that offloads z/OS SMF to the Linux server, where the SMF records are translated, formatted and normalized into mainframe performance data. Thereafter, the mainframe performance data is transformed into traces valid for processing in application performance monitoring (APM) software platforms.

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.
  • Integrate mainframe applications and systems monitoring with any APM platform to provide flexible end-to-end options for mainframe customers.
  • Offload mainframe application and system information (SMF records) to ensure low impact on z/OS.
  • Java-based application for zIIP eligibility on mainframe for improved performance and avoid MSU impact.

Downloading z/IRIS IronTap and z/OS Client installation packages

z/IRIS IronTap installation packages can be downloaded from the mainstorconcept Download Portal. New users should register here first, before accessing the portal.

z/IRIS is owned, licensed and distributed by mainstorconcept GmbH. For more information about obtaining the required licenses to run z/IRIS, please email mainstorconcept at:

z/IRIS IronTap

z/IRIS IronTap is a Java application server that runs on Linux and processes SMF records sent from z/IRIS clients. SMF records are transformed into trace records that can be processed in partner APM solutions.


All prerequisites and requirements are documented on the minimum hardware and software requirements page.

Any 3rd party solution that will receive and process data from z/IRIS must be active or running before z/IRIS IronTap is started.

Installing z/IRIS IronTap

  • Create the IRONTAP_BASE_DIR folder '/opt/mainstorconcept/'.
  • Extract the z/IRIS IronTap release zip file into the IRONTAP_BASE_DIR path.
  • The z/IRIS IronTap files are located in the IRONTAP_INSTALL_DIR '/opt/mainstorconcept/irontap/'.

File Descriptions and Functions


contains z/IRIS IronTap modules and dependencies.


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

describes a launcher script for z/IRIS IronTap.

Configuring z/IRIS IronTap 

The application.conf configuration file can be used to overwrite the default z/IRIS IronTap module configurations.

Default valueNotes

global.time-zoneThe default time zone for all z/OS systems.CET

smf.ebcdic-codepageThe default EBCDIC encoding.IBM1047

systemsAn array of system ids and time zones.
 Multi system time zone config example
systems: [
{id: S0W1, time-zone: EST}
{id: S0W2, time-zone: CET}

worker-threadsThe number of threads for parallel SMF processing.-1Choose the number of threads. A negative value will always result in using #cores -1 threads (at least 1).

logSmfDataOnErrorAn SMF parsing error will be logged including the whole SMF record.true

portThe listener port which the z/IRIS client uses to connect to z/IRIS IronTap.


topicPatternA pattern describing the topics z/IRIS IronTap should consume.smf

consumerContains the Apache Kafka Consumer configuration provided by your Apache Kafka administrator.default consumer config

bucketThe InfluxDB bucket to be used for z/IRIS metrics

orgThe InfluxDB organization

urlThe url to your InfluxDB

authenticateTokenA token with write permissions within the organization
Please note that all configs can be provided via the command line as well.

 Example config
    bucket = "16b45434a5f58182"
    org = "e9043121e23a02da"
    url = ""
    authenticateToken = "MySecureOrgToken=="

Example config, overriding the default EBCDIC code page with IBM01140 and enabling Instana Events for mainframe jobs.

application.conf dot notation
irontap.zos.smf.ebcdic-codepage: "IBM01140"
irontap.apm.instana.sdsf.returnCodeEventsEnabled: true
application.conf Json notation
   ebcdic-codepage: "IBM01140"
 apm {
    returnCodeEventsEnabled: true

z/IRIS z/OS Client

z/IRIS clients are IBM JZOS based applications that stream SMF records to the Linux Server for processing and integration into 3rd party APM tools (z/IRIS IronTap).

 z/OS clients requirements...


Please refer to the minimum hardware and software requirements page.

IBM Java for z/OS

z/IRIS clients require IBM Java SDK 1.8. For more information on how to install and configure IBM Java for z/OS, please visit the IBM Knowledge Center.

In-Memory Resources

z/IRIS clients stream SMF records from IBM SMF in-memory resources. For information on how to configure new SMF in-memory resources, please visit the IBM Knowledge Center.

Apache Kafka integration

z/IRIS clients activate Kafka Producers to stream SMF to a predefined and network accessible Kafka cluster. Users must download and install the Apache Kafka binaries in z/OS USS before configuring z/IRIS clients for Kafka streaming mode.  

Visit the official Apache Kafka website to download binaries and access all relevant documentation about Apache Kafka Producers and Apache Kafka Clusters and more.

For more information about z/IRIS integration with Apache Kafka, visit Apache Kafka - Configuration Guide.

 Security preparation...

RACF configuration 

All z/IRIS clients must be granted access to SMF in-memory resources using SAF permissions. The RACFJCL text file is a RACF batch job to create a surrogate userid for the z/IRIS client started task  with the required permissions for OMVS, SMF in-memory resources and MVS display commands.

Upload, customize and submit RACFJCL from the installation package.

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

 ZFS filesystem preparation..

ZFS directory ($APP_HOME)

Customize and run the following JCL example to create and mount a new ZFS directory for z/IRIS in USS. This directory is hereinafter referred to as $APP_HOME.

Sample JCL to create z/IRIS zFS directory
// JOB
//* Create a z/IRIS ZFS directory
// PARM='SH mkdir -p /usr/lpp/ziris'
//* Create ZFS mount point for z/IRIS
LINEAR CYL(200 50))
VOLUMES(xxxxxx) -
//* Mount the z/IRIS directory
MOUNTPOINT('/usr/lpp/ziris') +

Install and configure a z/IRIS client

 Extract installation package...
  1. Extract and upload (in binary mode) the zirisv%%.pax to the $APP_HOME directory on z/OS USS. 

  2. Unpack the file using the tar command:

    pax command
    pax -w[v]f zirisv1%%.pax

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

  3. Apply the authorized extended attribute to $APP_HOME/bin/CONSL001:

    extatttr command
    cd $APP_HOME/bin
    extattr +a ./CONSL001
  4. Make all commands in $APP_HOME/bin executable:

    chmod command
    cd $APP_HOME/bin
    chmod +x ./*

z/IRIS License

The z/IRIS license file is provided separately and must be uploaded to the $APP_HOME directory.

 ziris.comm.config customization...


Configure the $APP_HOME/lib/ziris.comm.config to as required.

Parameters and options

Required parameters and options
# ziris.comm.config required parameters
# mode defines the technology used to stream SMF records.
#  syntax : mode={tcp!kafka}                              

# host refers to the host address destination for SMF record streaming. 
#  If mode=tcp host is required and refers to the IronTap host address. 
#  If mode=kafka, host is a list of kafka bootstrap servers which overrides
#  all bootstrap servers listed in kafka            
# syntax : host=[IronTap_host_address|kafka_bootstrap_servers]

# inmem is required and defines which active SMF in-memory resources z/IRIS will 
# read SMF records from. The inmem statement can be specified multiple times to
# configure multiple in-memory resources.
# syntax :                            
# kafkaTopic defines the kafka cluster topic used to stream SMF records.
#  Required if mode=kakfa                                               
# syntax : kafkaTopic=kafka_topic_name                                  
Optional parameters
# ssl activates SSL for mode=tcp
# default : n (not active)      
syntax : ssl=y!n        
# kafkaConfig defines an alternate absolute path to a           
#  kafka file. The default path is              
#  default : $APP_HOME/kafka/  
#  syntax : kafkaConfig=/producer/properties/file               
# timeout defines the timeout for SMF record streaming in seconds.
# timeout=ä0-2147483647ü                                          

# reconnect defines the number of seconds to wait before reconnecting the
#  stream after a timeout or error.                                     
# default : 7                                                           
# syntax : reconnect=ä0-2147483647ü         

# monitor.thruput.interval defines an interval in seconds to display throughput
#  statistics. Only takes effect if com.msc.zos.ziris=FINE in
# default : 60 seconds                                                  
# syntax : monitor.thruput.interval=ä5-3600ü                            

# alias is used to identify this client to the SMF receiver. 
# if mode=kafka, alias will overwrite the Kafka Producer property                       
# alias=ziris_client_alias_name                   

 mode=kafka considerations...

Apache Kafka Producer properties when mode=kafka

The installation package contains default Apache Kafka Producer properties for z/IRIS streaming:


Avoid making changes to the as this may be overwritten by updates.

Instead create a new file by :

  1. Copy the sample producer properties file in the $KAFKA_HOME/config directory.
  2. Edit the properties as required.
  3. Specify the new producer properties path and file name in the ziris.comm.config file using the kafkaConfig parameter.

For more information about required properties for z/IRIS SMF streaming, see Apache Kafka - Configuration Guide .

 Workload manager considerations...

Workload manager considerations

The z/IRIS started tasks should be allocated to low/discretionary priority in WLM.

Please consult your mainstorconcept technical professional if you require any assistance with amending your WLM policies.

Using z/IRIS clients

 Create a new z/IRIS proclib member ...

Create a z/IRIS client PROCLIB member

  1. Upload the ZIRISPRC started task procedure and the ZIRISJVM JZOS procedure files from to a concatenated PROCLIB data set.

  2. Change $APP_HOME in JCL to the $APP_HOME directory created for z/IRIS in ZFS.
  3. If mode=kafka for SMF records streaming via a predefined and network accessible Kafka cluster, uncomment the following line and define the Kafka home directory to z/IRIS z/OS: 

    # export KAFKA_HOME=/usr/lpp/kafka/kafka_2.11-2.3.0
  4. Change $JVAHOME to the $JAVA_HOME directory where IBM Java version 8 resides.
  5. Save the PROCLIB member.

  6. Allocate the surrogate user id defined by the RACFJCL job: 

    RACF RDEFINE syntax example

 Starting z/IRIS clients

Activating z/IRIS clients

To start the z/IRIS client Started Task, issue the following MVS Command:

Start z/IRIS started task syntax
/S ziris

where ziris is the member name of the z/IRIS PROCLIB member.

Please note:

When z/IRIS reports a failed connection during start-up, check that either the z/IRIS Linux server is active or that the Apache Kafka cluster is running with the accessible topics and brokers.

 Stopping z/IRIS clients...

Stopping  z/IRIS clients

To stop the started task issue the following MVS Command:

Stop z/IRIS started task syntax
/P ziris

Where ziris is the name of running z/IRIS STC Address Space.

 z/IRIS client modify commands...

z/IRIS client 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 Command Syntax :

Modify command syntax for z/IRIS started task
/F ziris,APPL=cmd


ziris:  is the name of the z/IRIS STC
cmd:  is a valid z/IRIS Modify Command


lists and displays information about available commands:

z/IRIS HELP modify command
/F ziris,APPL=HELP


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

z/IRIS STATUS modify command syntax

Sample response:

Sample output from STATUS modify command
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 client logging...

z/IRIS client 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 client Started Task:

    2020-03-26 09:34:24   INFO     z/IRIS Startup V1.3.0                       
    2020-03-26 09:34:28   INFO     ZIRISTST initializing System Properties       
    2020-03-26 09:34:28   INFO     ZIRISTST Checking License Information        
    2020-03-26 09:34:33   INFO     ZIRISTST Getting In-Memory Information...    
    2020-03-26 09:34:35   INFO     ZIRISTST Reading config File: /lib/ziris.comm.config
    2020-03-26 09:34:36   INFO     ZIRISTST Loaded Configuration...              

z/IRIS Features

OpenTelemetry support

 Click here for more information..

The Cloud Native Computing project OpenTelemetry provides an open standard for telemetry data, including traces and metrics. The importance and the capabilities of this open standard are recognized by countless APM vendors and ensure z/IRIS users have mainframe-inclusive tracing with proprietary and open-source APM tools.  Because Observability and Monitoring requirements can vary greatly depending on the business case, implementing a uniform standard allows different APM products to interact with each other, resulting in custom solutions that meet our customer needs.

Read more about out OpenTelemetry support in our public knowledge base.

z/OS Connect trace streaming

 Click here for more information..

z/IRIS creates OTLP compliant traces from z/OS Connect SMF type 123 version 2 records. DevOps teams have access to multiple performance indicators regarding REST API requests processed by z/OS Connect servers on mainframe, such as:

  • the total elapsed time it took to send a response from z/OS.
  • differentiation between z/OS connect transaction times and System-Of-Record(SOR) transaction times.
  • mainframe related request and system identifiers for each REST API call that can be provided to SMEs for escalated root cause analysis.
  • security authentication data.
  • DevOps friendly trace tags that reduce the learning curve drastically when monitoring mainframe related application performance, e.g.:
    • zos.connect.sor.request.received_time.

See z/IRIS z/OS Connect support and configuration  for examples of monitoring mainframe hosted Rest API calls in Jaeger with OpenTelemetry.

Load Balancing & High Availability with Apache Kafka Integration

 Click here for more information...

Streaming SMF records through an intermediate predefined Kafka Cluster is now possible. Integration with Apache Kafka guarantees high availability and load balancing. 

Using an intermediate Kafka cluster provides the ability  to retain SMF records in the cluster for a configurable period and integrate the cluster into SMF record collection and eliminate traditional collection of SMF records using daily batch jobs on the mainframe. 

The configuration options and recommendations for z/IRIS processing can be found here:

Apache Kafka - Configuration Guide

z/OS work activity tracing 

 Click here for more information...

Common address space work activity SMF records (Type 30) provide the following information:

  • a batch job, APPC/MVS transaction program, OMVS forked or spawned address space starts
  • a batch job or step, APPC/MVS transaction program, OMVS forked or spawned address space ends
  • interval accounting for active jobs, started tasks, and system address spaces
  • TSO session starts or ends (user logon and logoff)

The following performance information is provided by SMF 30 records:

  • Work and batch job names and identifiers
  • CPU and specialty engine utilization(Service units and CPU time)
  • work start and end timestamps as well as duration/elapsed time
  • Completion codes which signal whether an error occurred during processing
  • Job Owners and assigned user ids

Benefits of streaming SMF 30 records in real-time:

  • z/OS work monitoring on modern APM platforms
  • Near real-time source for mainframe performance data which will increase the business value of existing mainframe capable infrastructure monitoring tools
  • Near real-time mainframe resource consumption charge back calculations possibilities
  • Incorporate mainframe administrators, developers and teams with modern DevOps and SysOps tools and processes

z/IRIS metric streaming 

 Click here for more information...

z/IRIS is capable of streaming metrics for storing and real-time processing in DBMS systems that are data sources for metric visualization and monitoring software. 

Supported IBM SMF records types for z/IRIS metrics

Additional SMF records coming soon but can be explicitly requested.

Officially supported metric data sinks

  • InfluxDB 2.0

Support for alternate data sinks can be requested.

z/IRIS metrics comply to open standards so that customers are not limited by proprietary solutions. 

Distributed Db2 for z/OS tracing streaming 

 Click here for more information...

Db2 deadlock traces

Deadlock traces provide details regarding deadlock events that have occurred within a Db2 address space. z/IRIS processes and provides the application Holder and Waiter information from a deadlock event as trace-ids that are searchable within partner APM solution. This helps DevOps teams quickly locate applications holding Db2 resources as well as identify the applications who timed out due to the unavailability of these Db2 resources.

Db2 accounting traces 

Accounting information gives an overview of a unit-of-work completed for JDBC client application. Details include elapsed CPU seconds and response time, SQL requests summaries, amount of fetched data and commits or rollbacks.

Accounting trace details vary according to the classes applied when activating accounting tracing. Speak to your Db2 administrator to ensure your APM integration contains all the information your DevOps teams require for effective monitoring.

Please note:

To receive records for each Unit-Of-Work 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 IBM web pages for more information regarding the affected parameters:

  •  DDF/RRSAF ACCUM field (ACCUMACC subsystem parameter)

  •  AGGREGATION FIELDS field (ACCUMUID subsystem parameter)

Db2 performance traces

This Db2 performance traces provide low-level performance information. Activating these traces can affect Db2 for z/OS response time and CPU consumption, and should only be activated when required.

Please note:

IBM does not recommend that users run this performance class traces in a production environment over extended periods of time.