Debian Codegraph @

interactive-notebook/README.md

raw
1 # ISystemtap
2 Welcome to ISystemtap, to get started check the [usage](#usage) below and tryout the ISystemtap.ipynb
3
4 ## Usage
5 ### Local usage
6 Once ISystemtap is installed just run `jupyter-lab [notebook_name.ipynb]` and then select a new or existing ISystemtap notebook. For installation see [below](#local-installation)
7
8 ### Container usage
9 No local installation of ISystemtap is needed. Once systemtap is installed the following can be run.
10 It is suggested to pull the pre-built image from `quay.io`, but it can optionally be locally built as well
11 ```bash
12 stap-jupyter-container [--repo REPOSITORY] [--image IMAGE] [--tag TAG] [--keyname KEYNAME] --{run, pull, build, publish, remove}
13 ```
14 * --keyname: The name of the key to use for ssh'ing from the container to the host to run the stap commands. There should exist both "keyname" and "keyname.pub" files
15 * --run: Runs the image (if not pulled / built locally pull it from `quay.io`)
16 * --pull: Pull the built image (Published to `quay.io/systemtap/isystemtap`)
17 * --build: Do a local container build
18 * --publish [For maintainers only]: Publish the image to the public repo
19 * --remove: Remove the local copy of the image
20
21 #### TL;DR
22 To get started just run `stap-jupyter-container --run`
23
24 #### Running as a superuser
25 Running the container as a superuser means that stap scripts will be run as root. Therefore there are 2 prerequisites
26 * Make sure to add `PermitRootLogin without-password` to `/etc/ssh/sshd_config`. Note this does not mean there is no authentication it means that logging in is only possible using a fallback method (in this case a public key authentication).
27 * Make sure that systemtap is installed by root
28
29 ## Local Installation
30 Run `stap-jupyter-install`. This will install the ISystemtap kernel, syntax highlighting and language-server dependencies in `~/.systemtap/jupyter` (and the jupyter config directories). To uninstall add the `--remove` flag.
31
32 ## Development Directory Structure
33 ```
34 interactive-notebook
35 ├── codemirror // Jupyterlab extension for syntax highlighting
36 │ ├── jupyterlab-stap-highlighting
37 │ │ └── ...
38 │ ├── lib
39 │ │ └── ...
40 │ └── package.json
41 │
42 ├── container // Container which wraps up the pythonic install elements
43 │ ├── Dockerfile
44 │ └── runtime_container_config.sh
45 │
46 ├── setup.py // setup for module. Included in stap-jupyter-install
47 ├── isystemtap // the jupyter kernel source and config file
48 │ ├── *.py
49 │ └── kernel.json
50 │
51 ├── tests // Some automated and manual tests (Note: to test the dir must be writable)
52 │ └── ...
53 │
54 ├── ISystemtap.ipynb // An introductory notebook example
55 │
56 ├── stap-jupyter-install.in // Used to generate the local install script
57 │
58 ├── stap-jupyter-container.in // Used to generated container management script
59 │
60 ├── jupyter_stap_lsp.json // The language server config file
61 │
62 └── requirements.txt // Python reqs
63 ```
64
65 ## FAQ
66 1. What if something goes wrong, and a systemtap kernel module is left running after ISystemtap shuts down
67 * All you need to do is kill the process and run `sudo staprun -d MODULE_NAME` (this can be checked in `/proc/systemtap`)
68 2. How do I build from source?
69 * The same as normal. `make; make install` followed by one of the above `stap-jupyter-*` commands
70 3. What does Error: OCI runtime error: crun: error creating systemd unit `libpod-*.scope: got failed` mean
71 * Some file systems have issues with `podman`, try running as a superuser
72 4. **I'm a maintainer who wants to publish the latest image**; how do I do this?
73 * After building and installing systemtap run `stap-jupyter-container --build && stap-jupyter-container --publish`
74 * After the build you will be prompted for a `quay.io` login. This will be followed by the image being published to `quay.io/systemtap/isystemtap`