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.
The following module configurations can be customized to override defaults:
|Property prefix: irontap.apm.instana.|
|tracing.db2.trace-delimiter||A single ASCII character (except "0-9" and "a-f", "A-F") used to separate the trace information.|||||ASCII code 124 (vertical-bar, pipe)|
The client information property field (JDBC) used to provide trace information. The following fields are available:
For Instana Apm integration only one field is necessary.
|sdsf.returnCodeEventsEnabled||IronTap will create events for jobs (SMF 30) with a completion code > 0||false|
Example Instana Event
Example config to enable Instana Events for mainframe jobs:
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.
|irontap.apm.instana.events.sent||Events that were successfully sent to the Instana Agent.|
|irontap.apm.instana.spans.sent||Spans that were successfully sent to the Instana Agent.|
|irontap.apm.instana.spans.enqued||Spans ready to be sent to the Instana Agent.|
|irontap.apm.instana.spans.dropped||Dropped Instana Spans. Spans might be dropped if the Instana Agent is not available and the internal queue is full.|
|irontap.apm.instana.record.invalid-type||Records that aren't supported by your current setup.|
|irontap.smf.xxx||Number of records processed for each enabled SMF record type.|
Activating debug features may impact the performance of z/IRIS and the delivery of spans into the Instana backend.
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.
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 designated resources do not need to be specified in the ziris.comm.config file and will be automatically connected.
- 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.