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

Content




Created  

Updated 


Summary

z/IRIS integrates with partner APM ISV solutions and tools to enable mainframe-inclusive APM functionality. z/IRIS creates APM related traces from mainframe performance data and posts these mainframe traces to APM servers. All mainframe traces created by z/IRIS are viewable in the APM ISV UI.

This article describes how z/IRIS is configured to integrate with Instana APM.

application.conf

The following module configurations can be customized to override defaults:

Property prefix: irontap.apm.instana.
PropertyDescriptionDefault ValueNotes
tracing.db2.trace-delimiterA single ASCII character (except "0-9" and "a-f", "A-F") used to separate the trace information. |ASCII code 124 (vertical-bar, pipe)
tracing.db2.trace-field

The client information property field (JDBC) used to provide trace information. The following fields are available:

ClientHostName

ApplicationName

ClientHostName

For Instana Apm integration only one field is necessary.

sdsf.returnCodeEventsEnabledIronTap will create events for jobs (SMF 30) with a completion code > 0false
 Example Instana Event

Example config to enable Instana Events for mainframe jobs:

application.conf dot notation
irontap.apm.instana.sdsf.returnCodeEventsEnabled: true
application.conf Json notation
irontap{
	apm {
		instana{
			sdsf{
				returnCodeEventsEnabled: true
			}
		}
	}
}

Metrics overview

click on the image to enlarge


z/IRIS IronTap metrics are visible in the Instana UI. Open the z/IRIS IronTap JVM Dashboard and scroll down towards the Micrometer Custom Metrics.

MetricDescription
irontap.apm.instana.events.sentEvents that were successfully sent to the Instana Agent.

irontap.apm.instana.spans.sentSpans that were successfully sent to the Instana Agent.
irontap.apm.instana.spans.enquedSpans ready to be sent to the Instana Agent.
irontap.apm.instana.spans.droppedDropped Instana Spans. Spans might be dropped if the Instana Agent is not available and the internal queue is full.
irontap.apm.instana.record.invalid-typeRecords that aren't supported by your current setup.

irontap.smf.xxxNumber of records processed for each enabled SMF record type.

Debugging

Activating debug features may impact the performance of z/IRIS and the delivery of spans into the Instana backend.

Span Dumps

This feature is enabled by setting a non-empty string for the instanaSpanDumpDirectoryPath property. z/IRIS IronTap will write all spans into the provided directory. Multiple spans may be joined into a JSON array in one file.

JSON file name example

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 was established.

Instana designated z/OS in-memory resources

z/IRIS z/OS clients will automatically discover and connect to IBM z/OS in-memory resources, where names match the following pattern:

  • **.INSTANA.**

Instana designated resources do not need to be specified in the ziris.comm.config file and will be automatically connected.

Example of an Insana designated In-memory resource
IFASMF.IFA.INSTANA.INMEM.DB2


Considerations 

  • z/IRIS IronTap must have access to an Instana agent to send spans to the Instana APM backend.
  • Mainframe-inclusive tracing requires the client application on distributed infrastructure to be fully instrumented by Instana agents. This ensures that Instana trace-ids are populated within the meta-data of client application calls, ensuring mainframe related spans, processed by z/IRIS, are appended to the correct application traces within the Instana backend.