Installation

You need to have Python 3.8 to Python 3.11 (64-bit) installed to use IBM SMF Explorer. Instructions on how to install Python can be found here. In the last installation step, make sure to enable the option to add Python to your PATH environment variable.

Next, verify the correct version of python and pip by running the commands python --version and pip --version in your terminal. This is necessary because some operating systems have Python 2 preinstalled or require you to install pip separately.

IBM SMF Explorer is provided in two parts. The first part is the IBM SMF Explorer Python package, which is shipped as part of the z/OS Data Gatherer: SMF Data REST Services. Note that this package is not available in the public Python package index (pypi) and cannot simply be installed with the pip command (Python package manager). The second part is the Github repository, which contains the tutorials and setup scripts.

Note: this step is not needed if you are installing on USS system

This tutorial assumes that you already have the z/OS Data Gatherer: SMF Data REST Services installed on your z/OS Host. The IBM SMF Explorer Python package is provided in a ZIP archive on the z/OS host on which the z/OS Data Gatherer: SMF Data REST Services was installed.

You will find the ZIP archive smf_explorer.zip in USS directory /usr/lpp/grb/smf_explorer. Use FTP or any other methods available to download the archive from the z/OS Host. Make sure to download the archive as a binary file to prevent accidental EBCDIC to ASCII conversion.

When you unpack the ZIP archive you will find a smf_explorer directory containing a smfexplorer-*.whl wheel file that will be used later in this guide.

The next step is to download the IBM-SMF-Explorer repository. This can be done by cloning the repository with git or directly downloading it from Github.

git clone https://github.com/IBM/IBM-SMF-Explorer.git

After downloading and extracting the IBM-SMF-Explorer repository from Github, you will have an IBM-SMF-Explorer folder with the following structure:

IBM-SMF-Explorer-main
   +- .github
   +- .util
   +- Notebooks
   +- smf_explorer
        // smfexplorer-*.whl from z/OS host will come here
    ...

Then, you must copy the smfexplorer-*.whl extracted in the previous step into the smf_explorer folder of the downloaded Github repository.

The environment needs to be installed by calling the setup script

If you are in an enterprise network environment you might need to set up a HTTP proxy for the python package manager to be able to install SMF Explorer.

You can use the pip config files or HTTP[S]_PROXY environment variables (see https://pip.pypa.io/en/stable/user_guide/?highlight=Proxy#using-a-proxy-server).

.\setup.bat

./setup

After the setup script completes successfully the JupyterLab environment is ready to be used (see Usage).

To update IBM SMF Explorer and the JupyterLab environment you should pull the latest changes from the IBM-SMF-Explorer repository using git pull or download the repository as a ZIP file again.

If you used the provided Notebooks without making your own copies the git pull command may complain that there are uncommitted changes. You can delete all local changes with git reset --hard followed by a second git pull. Note that this will delete all the local changes you made.

You should download a new version of IBM SMF Explorer from the Host if available and copy the smf_explorer directory into the cloned repository again.

By running the setup script again the environment will be updated. If you want to setup the environment from scratch, you can add the reset option.

.\setup.bat [-Reset]

./setup [--reset]

When working wih Python projects, it’s highly recommend to use a virtual environment to manage your project’s dependencies. This ensures that your project is isolated from other projects and avoids potential conflicts between package. Please refer to Python official documentation for details how to create such.

After the virtual environment has been created and activated, you can install the smfexplorer-*.whl wheel file using pip

pip install smfexplorer-*.whl

Please note that on USS, we leverage the Python® AI Toolkit for IBM® z/OS® that provides a secure foundation for AI development on z/OS.

IBM SMF Explorer has a feature to show the structure of a request as a graph in JupyterLab. For the feature to work you need to install a third party tool Graphviz on your Workstation.

You can follow the instruction here to install Graphviz for your platform.