Usage

Before you can use the IBM® SMF Explorer, you need the URL used for the z/OS® Data Gatherer: SMF Data REST Services endpoint and your User IDs credentials for the z/OS Host.

The URL for the z/OS Data Gatherer: SMF Data REST Services endpoint usually has the form https://[host-domain/IP]/zosmf/zosdg/smf.

If you access the URL you should see the SMF Data REST Services Swagger page. A system administrator should be able to provide you with the correct endpoint.

IBM SMF Explorer leverages the SMF Data REST Services to fetch data, therefore, you should make sure that the certificate for the REST Services is configured properly on your workstation. This ensures a secure connection with the REST Services. Without the proper setup of the certificate, the connection will be rejected. Please contact your system administrator for further information.

You can ask your system administrator for the certificate or download the certificate from your browser and save it locally. To run SMF Explorer with a custom certificate, you can provide the path to this certificate on starting:

.\start.bat  ---cacert=path_to_ca_cert

./start ---cacert=path_to_ca_cert

Alternatively, you can deactivate the certification validation temporarily for your test environment as below. However, this is not recommended, since it opens up the test environment to potential security vulnerabilities.

.\start.bat --no-verify-tls=True

./start --no-verify-tls=True

To start the environment you should run the start script in the IBM-SMF-Explorer repository.

.\start.bat

./start

The start script will ask for the connection URL and your credentials.

>>> ./start
Activating environment...
What is your connection string?: https://zos-host-domain.com/zosmf/zosdg/smf
Enter your username: IBMUSER
Enter your password: *******
Starting Jupyter Lab...

After you provide the required information a browser window should open and show the JupyterLab interface.

On the JupyterLab interface you can create new Notebooks and get started using IBM SMF Explorer. If you have never worked with JupyterLab you might find the User Guide helpful to get you oriented.

Start by working through the notebooks in the Tutorial directory. Those notebooks will show you the basics for getting started with IBM SMF Explorer.

To stop the setup press Ctrl-C in the terminal and answer the termination request(s) with Y or use File > Shut Down from the JupyterLab interface.

Alternatively, you can use SMF Explorer in a Python script. The example below demonstrates how to do so:

import os
import smfexplorer
from smfexplorer.fields import SMF74S4

connection_string = "https://zos-host-domain.com/zosmf/zosdg/smf" # replace with your own connection string
user_name = 'YOUR_USER_NAME'
user_password = 'YOUR_PASSWORD'
custom_ca_path = 'path_to_your_cert'
verify_ssl = 'true'

dataset = "DATASET_NAME"
connection_info = f"mode=dgapi;url={connection_string};verify_ssl={verify_ssl};username={user_name};password={user_password}"
os.environ["SMFPY_CONNECTION_STRING"] = connection_info
os.environ['REQUESTS_CA_BUNDLE'] = custom_ca_path

ctx = smfexplorer.new_context(dataset)  

fields = [SMF74S4.r744fidp]

data = ctx.request(fields).run()
print(data)