Installation
You need to have Python 3.8 to Python 3.10 (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.
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/IBM/zdg/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.
Clone the IBM-SMF-Explorer repository into a location on your workstation and enter the directory.
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
Note that you might encounter the Path Too Long error during the setup process on Windows workstation. To overcome this, please follow guides here.
./setup
After the setup script completes successfully the JupyterLab environment is ready to be used (see Usage).
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.
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 thegit pull
command may complain that there are uncommitted changes. You can delete all local changes withgit reset --hard
followed by a secondgit 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]