As z/OS Connect continues to evolve as the premier API gateway for mainframe integration, we're excited to share a powerful new sample interceptor that complements your existing monitoring strategy: the File System Logger Interceptor.

What Is the File System Logger Interceptor?

The File System Logger Interceptor is a sample z/OS Connect interceptor that captures comprehensive API provider and API requester data and writes it in structured JSON format to rolling log files to the ZFS. This interceptor works seamlessly alongside your existing monitoring tools, providing an additional layer of detailed, file-based logging for both API providers and API requesters.

Think of it as your transaction "black box" – capturing every detail of your inbound and outbound API calls in an easily accessible, human or machine readable format that's perfect for debugging, auditing, and detailed analysis.

Why You'll Want to Use It

Complements Your Existing Monitoring Strategy

The File System Logger Interceptor is designed to work alongside z/OS Connect's existing monitoring capabilities, not replace them:

• SMF Records: Continue using SMF for enterprise-wide monitoring, capacity planning, and chargeback. SMF provides the high-level metrics and performance data your operations team needs.

• OpenTelemetry (OTel): Keep leveraging OTel for distributed tracing, real-time observability, and integration with modern APM tools. OTel excels at showing you the big picture across your entire application landscape.

• File System Logger: Add detailed, transaction-level logging for deep-dive troubleshooting, compliance auditing, and development debugging. This interceptor captures the granular details that help you understand exactly what happened in each API call.

Key Benefits

The File System Logger Interceptor leverages z/OS Connect's powerful interceptor framework, capturing data at strategic points in the request flow to provide the following detailed information:

• Request and response headers you chose to log

• Optional request and response body logging for full payload visibility

• Request/response sizes (always captured, even when bodies aren't)

• Query strings and endpoint details

• User identity and mapped credentials

• System of Record (SoR) information for API providers

• CICS/IMS context for API requesters

It then writes a single entry in the log file for each successfully processed request, for example for API provider:

{
  "timestamp": "2026-01-14T10:15:30.123Z",
  "requestId": 123456789,
  "user": "user1",
  "mappedUser": "USERID",
  "request": {
    "uri": "/api/v1/customers",
    "method": "POST",
    "queryString": "filter=active&limit=10",
    "headers": {
      "Content-Type": "application/json",
      "Accept": "application/json"
    },
    "body": "{\"customerId\":\"12345\"}",
    "size": 23
  },
  "sor": {
    "identifier": "CICS01",
    "resource": "CUSTOMER",
    "reference": "REF123"
  },
  "response": {
    "statusCode": 200,
    "headers": {
      "Content-Type": "application/json"
    },
    "body": "{\"status\":\"success\"}",
    "size": 21
  }
}

And then here's an example for API requester:

{
  "timestamp": "2026-01-14T10:15:30.123Z",
  "requestId": 987654321,
  "user": "user1",
  "mappedUser": "USERID",
  "request": {
    "requestType": "CICS",
    "jobname": "CICSJOB",
    "jobid": "JOB00123",
    "sysname": "SYSA",
    "cics": {
      "applid": "CICS01",
      "taskNumber": 54321,
      "transid": "ABCD"
    },
    "headers": {
      "Content-Type": "application/json",
      "Accept": "application/json"
    },
    "body": "{\"query\":\"customerId\"}",
    "size": 24
  },
  "endpoint": {
    "host": "backend.example.com",
    "port": 8080,
    "method": "GET",
    "path": "/customers/12345",
    "queryString": "format=json&include=details"
  },
  "response": {
    "statusCode": 200,
    "headers": {
      "Content-Type": "application/json",
      "Cache-Control": "no-cache"
    },
    "body": "{\"customer\":{\"id\":\"12345\"}}",
    "size": 30
  }
}

Note that the JSON is formatted nicely here for readability and in the log files there will be one line of JSON per request logged.

Getting Started With the File System Logger Interceptor

The interceptor is available as a sample on GitHub here https://github.com/zosconnect/sample-fslogger-interceptor, and includes complete source code with comprehensive JavaDoc, a Gradle build and extensive unit tests. See the detailed README to learn more and to understand how to build, install and configure the interceptor. The sample includes both API provider and API requester interceptors, so you can choose to implement one or both based on your needs.

WARNING - Be cautious when enabling the File System Logger Interceptor as it may log sensitive personal information such as passwords, credit card numbers, or personal data. You should ensure the log directory being used has appropriate permissions to prevent unauthorized access.

A Powerful Addition to Your Monitoring Toolkit

The File System Logger Interceptor doesn't replace your existing monitoring strategy – it enhances it. Use SMF for operational metrics, OTel for distributed tracing, and the File System Logger for detailed transaction analysis. Together, they provide comprehensive visibility into your z/OS Connect environment.

Whether you're troubleshooting a production issue, conducting a security audit, or simply want deeper insights into your API traffic, this interceptor gives you the detailed, accessible logs you need. Ready to enhance your z/OS Connect monitoring? Check out the sample on GitHub here https://github.com/zosconnect/sample-fslogger-interceptor, and start capturing detailed API transaction logs today!