Configuration

Default configuration is automatically created as ~/.pptop/pptop.yml at the first launch. Alternative configuration can be specified with “-f” command line key:

pptop -f <CONFIG_FILE>

Configuration file is YAML file, which looks like:

inject-method: native
console:
  json-mode: true
display:
  colors: true # 256 - force 256 colors
  glyphs: true
keys:
  filter:
    - f
    - "/"
  select: ENTER
  back:
    - ESC
    - q
  ready: CTRL_L
  reinject: J
  interval: I
  console: "`"
  show-console: CTRL_O
  delete:
    - KEY_BACKSPACE
    - KEY_DC
  pause: p
  cursor-toggle: Z
  sort-col-next:
    - kRIT3
    - "}"
  sort-col-prev:
    - kLFT3
    - "{"
  sort-normal: kDN3
  sort-reverse: kUP3
  sort-toggle: "|"
  left: KEY_LEFT
  right: KEY_RIGHT
  up: KEY_UP
  down: KEY_DOWN
  hshift-left:
    - kLFT5
    - "["
  hshift-right:
    - kRIT5
    - "]"
  page-up:
    - KEY_PPAGE
    - CTRL_B
  page-down:
    - KEY_NPAGE
    - CTRL_F
  home: KEY_HOME
  end: KEY_END
  quit: KEY_F(10)
  reload: " "
  reset: CTRL_X
plugins:
  plugin_selector:
    default: true
    shortcut: KEY_F(2)
  script_runner:
    shortcut: KEY_F(3)
    config:
      script_dir: ~/.pptop/scripts
  vars:
    shortcut: KEY_F(4)
    interval: 0.5
    config:
      list: ~/.pptop/vars.list
  yappi:
    shortcut: KEY_F(5)
    #filter: lib/python
    cursor: false
  help:
    shortcut: KEY_F(1)
  open_files:
    shortcut: KEY_F(6)
  threads:
    shortcut: KEY_F(7)
  asyncio:
    shortcut: KEY_F(8)
    config:
      list: ~/.pptop/asyncio_loops.list
  log:
    shortcut: KEY_F(9)
    autostart: true
    cursor: false
  malloc:
    shortcut: KEY_F(11)
    cursor: false
  atasker:
    shortcut: KEY_F(12)
  env:
    shortcut: KEY_F(33) # C-F9
  last_exception:
    shortcut: CTRL_E

Main configuration

Option inject-method specifies proces inject method and can have values “native”, “loadcffi”, “unsafe” and “auto”. Can be overriden with “–inject-method” in command line.

Section console configures default console options:

console:
  json-mode: true

As you see, JSON mode is on by default, to display list and dictionary objects in a standard Python way by default, set it to false.

Next section is display

display:
  colors: true
  glyphs: true

and used to enable/disable colors and unicode glyphs. Both can be also disable with command like options -R (disables colors and glyphs) and –disable-glyphs (disable glyphs only). It’s recommended to disable unicode glyphs if you have an old terminal or working via old SSH client.

ppTOP automatically detects 256-color terminals (if $TERM env variable ends with 256color). However, some 256-color terminals may not have it. In this case, you may set colors: 256 in config, to enforce 256-color palette.

Plugins configuration

The next section is plugins, which configures plugins to load:

plugins:
  plugin_selector:
    default: true
    shortcut: KEY_F(2)
  script_runner:
    shortcut: KEY_F(3)
    interval: 5
    config:
      script_dir: ~/.pptop/scripts
  #.....

Each plugin can have the following options:

  • default specifies that plugin is default. Console option equivalent: -d

  • shortcut keyboard shortcut, used to launch plugin. Keys must be specified in curses format, except Ctrl+key combinations should be specified as CTRL_K (all uppercase), e.g. CTRL_M for Ctrl+m.

  • interval plugin data reload interval in seconds, default is 1.

  • autostart if plugin supports collecting data in background, setting this option to true will ask ppTOP to automatically inject and launch the plugin at startup. Otherwise the plugin will be injected only.

  • filter default plugin filter.

  • config this section is passed to plugin as-is, so see the corresponding plugin help how to use it (launch the plugin, then press F1).

Any configuration option can be overriden from command line with -o <PARAM>, which can be specified multiple times.

E.g. to include plugin, not listed in configuration, specify:

pptop -o plugin_name

to set reload interval for any plugin, specify it as plugin_name.interval e.g., lets set threads plugin to reload data every 0.5 seconds:

pptop -o threads.interval=0.5

to set config option, specify it as plugin_name.config.option, e.g. let’s set alternative default list file for vars plugin:

pptop -o vars.config.list=/path/to/mylist

Let’s combine all together: start ppTOP as variable watcher for the program which is running and store its PID into /var/run/myprog.pid process. Consider, list of required variables is stored into /opt/devel/myvars.list:

pptop -d vars -o vars.config.list=/opt/devel/myvars.list /var/run/myprog.pid