323 lines
12 KiB
ReStructuredText
323 lines
12 KiB
ReStructuredText
.. gulik documentation master file, created by
|
||
sphinx-quickstart on Fri Aug 17 19:42:15 2018.
|
||
You can adapt this file completely to your liking, but it should at least
|
||
contain the root `toctree` directive.
|
||
|
||
.. py:currentmodule:: gulik
|
||
|
||
The pamphlet of the gulik
|
||
=========================
|
||
|
||
.. toctree::
|
||
:maxdepth: 2
|
||
:caption: Contents:
|
||
|
||
.. note:: This documentation is still a work in progress and as such subject
|
||
to sudden changes, cataclysms and various other FNORDs. The software it
|
||
describes is still in alpha and may cause undue frustration if not taken
|
||
in moderation.
|
||
|
||
.. image:: _static/gulik.png
|
||
:align: right
|
||
|
||
| This is ST. GULIK. He is the Messenger of the Goddess.
|
||
| A different age from ours called him Hermes.
|
||
| Many people called him by many names.
|
||
| He is a Roach.
|
||
|
||
Quickstart
|
||
----------
|
||
|
||
Install!
|
||
^^^^^^^^
|
||
| ``[pkg|apt|dnf|fnord] install gtk3``
|
||
| ``pip[-3.6] install --user https://rnd.phryk.net/phryk-evil-mad-sciences-llc/gulik``
|
||
|
||
Run!
|
||
^^^^
|
||
``gulik``
|
||
|
||
Done!
|
||
^^^^^
|
||
That's literally everything needed to get ``gulik`` to run.
|
||
If you want to go deeper, you can…
|
||
|
||
Configure!
|
||
^^^^^^^^^^
|
||
``$EDITOR ~/.config/gulik/config.py``
|
||
|
||
See also: `Configuration file`_.
|
||
|
||
Definitional bullshit
|
||
---------------------
|
||
|
||
``gulik`` is a highly configurable graphical system monitor.
|
||
|
||
``gulik`` is a framework for custom graphical system monitors.
|
||
|
||
Both of these statements are true in some sense, false in some sense,
|
||
meaningless in some sense, true and false in some sense, true and meaningless
|
||
in some sense, false and meaningless in some sense and true and false and
|
||
meaningless in some sense.
|
||
|
||
This incarnation of our most holy saint ``gulik`` is software licensed
|
||
under the GPLv3 license, see :download:`COPYING <../../COPYING>` for more details.
|
||
|
||
| The official git repository for ``gulik`` can be found at:
|
||
| https://rnd.phryk.net/phryk-evil-mad-sciences-llc/gulik/
|
||
|
||
The PNG ``gulik`` logo is based on a nice public domain trace of the sacred
|
||
roach crafted by toa267 who is definitely not a cabbage.
|
||
|
||
Compatibility and dependencies
|
||
------------------------------
|
||
|
||
``gulik`` should skitter just fine on FreeBSD and the Linuxoids.
|
||
It will probably™ crawl into problems on OSX and other BSDs, but
|
||
`give us a holler <https://rnd.phryk.net/phryk-evil-mad-sciences-llc/gulik/issues/>`_
|
||
if it doesn't run on your \*nix flavor of choice and you're willing
|
||
to do some testing.
|
||
|
||
All bets are off on Windows®™ʷᵗᶠ unless someone else is willing to do a PR,
|
||
which we expect will be a long march through the valley of pain that we do not
|
||
wish upon anyone.
|
||
|
||
``gulik`` runs only on python 3.6 or newer.
|
||
All python dependencies are noted in ``setup.py``, ready for use in pip.
|
||
|
||
The only other dependency is gtk3. It does run with X11 and *should* run
|
||
with wayland, but the latter hasn't been tested.
|
||
|
||
To get partial transparency working (on X11) you need to have a compositing
|
||
manager like ``xcompmgr`` running.
|
||
|
||
Installation
|
||
------------
|
||
|
||
| You can use pip to install ``gulik`` and all python dependencies in one go:
|
||
| ``pip install --user git+https://rnd.phryk.net/phryk-evil-mad-sciences-llc/gulik/``
|
||
|
||
If you insist on manual installation, just clone the repository and copy the
|
||
``gulik`` subdirectory into your ``site-packages`` directory and ``bin/gulik``
|
||
to a directory in your ``$PATH``.
|
||
|
||
The master branch of the repository always holds the most current release.
|
||
|
||
Running
|
||
-------
|
||
|
||
You run ``gulik`` simply by running the ``gulik`` executable that comes with
|
||
the installation.
|
||
|
||
Configuration and Customization
|
||
-------------------------------
|
||
|
||
Default behavior
|
||
^^^^^^^^^^^^^^^^
|
||
|
||
By default, ``gulik`` will occupy a 200 pixel wide area over the full height
|
||
of the screen, placed at the left border of it and fill it with a few
|
||
:ref:`Visualizer`\s to grant you a good overview of what's happening on
|
||
your system.
|
||
|
||
It will use a black/white/green color scheme with a hue-rotation palette
|
||
ranging from lime green to magenta-ish pink and try to use the League of
|
||
Movable Type font `Orbitron <https://www.theleagueofmoveabletype.com/orbitron>`_
|
||
which we very much recommend you install to get the right dystopian vibe.
|
||
|
||
Configuration file
|
||
^^^^^^^^^^^^^^^^^^
|
||
|
||
You can modify the settings for ``gulik`` by creating a configuration file
|
||
at ``~/.config/gulik/config.py``. This file, as it's name suggests, is a
|
||
python code file. ``gulik`` will import and ``exec()`` it, loading all
|
||
``UPPERCASE`` variables into its configuration.
|
||
|
||
Lock and reload
|
||
"""""""""""""""
|
||
|
||
When ``gulik`` is running, you can send ``SIGUSR1`` to its main process
|
||
at any time to tell it to reload the configuration file and apply its
|
||
settings. If your configuration file is broken, ``gulik`` will keep
|
||
running with the previous settings.
|
||
|
||
Sending the signal is currently a bit clunky, as you'll have to do
|
||
something like: ``kill -s SIGUSR1 `pgrep -f 'python3.6.*gulik$'```
|
||
since python applications always have the process name of the python
|
||
interpreter.
|
||
|
||
Explaining ALL THE CONFIGURATION OPTIONS (not really, tho)
|
||
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||
|
||
* ``FPS`` (``int`` or ``float``): Frames Per Second; How often to redraw the window (and update system data). Default value: ``1``
|
||
* ``WIDTH`` (``int``): The width of the window in pixels. Default value: ``200``
|
||
* ``HEIGHT`` (``int``): The height of the window in pixels. Default value: ``Gdk.Screen().get_default().get_height()``
|
||
* ``X`` (``int``): X coordinate of the windows top left corner. Default value: ``0``
|
||
* ``Y`` (``int``): Y coordinate of the windows top left corner. Default value: ``0``
|
||
* ``NETDATA_HOSTS`` (``list``): `netdata <https://my-netdata.io/>`_ hosts to connect to. Hosts as hostnames or ``(host, port)`` tuples. Default value: ``[]``
|
||
* ``NETDATA_RETRY`` (``int`` or ``float``): How long a defective :class:`NetdataMonitor` will wait before retrying to contact the ``netdata`` server, in seconds. Default value: ``5``
|
||
* ``BSD_ACCURATE_MEMORY`` (``bool``): Use accurate but expensive memory data collection on BSD. Default value: ``False``
|
||
* ``MARGIN`` (``int`` or ``float``): Margin around all :class:`Visualizer`\s. Default value: ``5``
|
||
* ``PADDING`` (``int`` or ``float``): Padding around all :class:`Visualizer`\s. Default value: ``5``
|
||
* ``FONT`` (``str``): Font family to use in captions, legends and the like. Default value: ``"Orbitron"``
|
||
* ``FONT_WEIGHT`` (``str``): Font weight. Default value: ``"Light"``
|
||
* ``FONT_SIZE`` (``int`` or ``float``): Font size in pixels. Default value: ``10``
|
||
* ``COLOR_WINDOW_BACKGROUND`` (:class:`Color`): Background color of the window. Default value: ``Color(0.05, 0.05, 0.05, 0.8)``
|
||
* ``COLOR_BACKGROUND`` (:class:`Color`): Background color for :class:`Visualizer`\s. Default value: ``Color(1,1,1, 0.1)``
|
||
* ``COLOR_FOREGROUND`` (:class:`Color`): Foreground color. This is used as base color for most :ref:`palette`\s. Default value: ``Color(0.5, 1, 0, 0.6)``
|
||
* ``COLOR_CAPTION`` (:class:`Color`): Text color for captions. Default value: ``Color(1,1,1, 0.6)``
|
||
* ``PALETTE`` (``function``): The default :ref:`palette` generator. Default value: ``functools.partial(`` :func:`palette_hue` ``, distance=-120)``
|
||
* ``PATTERN`` (``function``): The default :ref:`pattern` generator. Default value: ``patterns.stripe45``
|
||
* ``CAPTION_PLACEMENT`` (``str``): ``"padding"`` to have captions placed in the paddings of :class:`Visualizer`\s, ``"inner"`` to place them within the drawing region of the :class:`Visualizer`. Default value: ``"inner"``
|
||
* ``LEGEND`` (``bool``): Whether :class:`Visualizer`\s should attempt automatically creating a legend for themselves in their bottom padding. Default value: ``True``
|
||
* ``LEGEND_ORDER`` (``str``): Whether to reverse the legend order. Can be ``"normal"`` or ``"reverse"``. Default value: ``"normal"``
|
||
* ``LEGEND_SIZE`` (``int`` or ``float``): Pixel height of one legend cell, including its own margin and padding. Legend font size is inferred from this. Default value: ``20``
|
||
* ``LEGEND_PLACEMENT`` (``str``): Where to place legends within the :class:`Visualizer`\s drawing region. Can be ``"inner"`` or ``"padding"``. Default value: ``"padding"``
|
||
* ``LEGEND_MARGIN`` (``int`` or ``float``): Margin around legends. Default value: ``2.5``
|
||
* ``LEGEND_PADDING``: Padding around legends. Default value: ``0``
|
||
* ``OPERATOR``: The blending operator used by :class:`Visualizer`\s. Default value: ``Operator.OVER``
|
||
|
||
Explaining ALL THE ᴀʟʟ ᴛʜᴇ ᴄᴏɴꜰɪɢᴜʀᴀᴛɪᴏɴ ᴏᴘᴛɪᴏɴꜱ (ya rly)
|
||
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||
|
||
The above list doesn't really cover all the possible configuration variables
|
||
you can set, as ``gulik`` features a perversion of cascading styles.
|
||
|
||
Every single option except for ``FPS``, ``X``, ``Y``, ``NETDATA_HOSTS``,
|
||
``NETDATA_RETRY`` and ``BSD_ACCURATE_MEMORY`` can be overriden on a per-class
|
||
basis by appending an underscore and the class name in uppercase to the
|
||
variable name. To disable legends on all :class:`Plot`\s for example, you
|
||
would use ``LEGEND_PLOT = False``.
|
||
|
||
Additionally, ``MARGIN`` and ``PADDING`` can be set for each side by
|
||
appending an underscore and one of ``LEFT``, ``RIGHT``, ``TOP`` or ``BOTTOM``.
|
||
|
||
If you want to mix both of these things, the resulting string follows the
|
||
pattern `<name>_<class>_<subname>`, for example ``PADDING_PLOT_RIGHT`` or
|
||
``LEGEND_MARGIN_ARC_BOTTOM``.
|
||
|
||
Custom setups
|
||
"""""""""""""
|
||
|
||
By default, gulik will run :func:`Gulik.autosetup` to set up a reasonable
|
||
collection of :class:`Visualizer`\s that gives you a good overview of your
|
||
system – but you can add your own ``setup`` function to the configuration
|
||
file that will be used in stead of the autosetup.
|
||
|
||
::
|
||
|
||
import gulik
|
||
|
||
def setup(app):
|
||
|
||
box = app.box()
|
||
|
||
box.place(
|
||
'cpu',
|
||
gulik.Plot,
|
||
elements=['core_0', 'core_1'],
|
||
width=box.width,
|
||
height=box.width + 40
|
||
)
|
||
|
||
Let's look at the code, line by line:
|
||
|
||
``def setup(app)``
|
||
The name of the setup function *must* be ``setup``, otherwise ``gulik`` won't recognize it.
|
||
The passed ``app`` parameter is a :class:`Gulik` object.
|
||
|
||
``box = app.box()``
|
||
:func:`Gulik.box` creates a :class:`Box`, a little helper to make layouting
|
||
easier. You can limit its size via ``width`` and ``height`` keyword parameters.
|
||
If these aren't supplied, the box will fill the whole window.
|
||
|
||
``box.place(``
|
||
:func:`Box.place` places a new :ref:`visualizer`. :class:`Box` orders
|
||
visualizers from left to right and top to bottom.
|
||
|
||
``'cpu'``
|
||
This is the monitored :ref:`component` we want to visualize :ref:`element`\s
|
||
of. It is needed to look up the right :class:`Monitor` object for
|
||
:class:`Visualizer` instantiation.
|
||
|
||
``gulik.Plot``
|
||
The :ref:`visualizer` class to be instantiated.
|
||
A subclass of :class:`Visualizer`.
|
||
|
||
All keyword arguments below this are just passed on to the visualizer class,
|
||
so in this case, :class:`Plot`. Here, these are:
|
||
|
||
``elements=['core_0', 'core_1'],``
|
||
Defines the :ref:`element`\s to be visualized. These two values refer
|
||
to the first and second CPU cores.
|
||
|
||
``width=box.width,``
|
||
Defines the width of the :ref:`visualizer`.
|
||
|
||
``height=box.width + 40``
|
||
Defines the height of the :ref:`visualizer`. Has 40 pixel added to it,
|
||
because by default, ``gulik`` adds 40 pixel bottom padding to every
|
||
visualizer to allow 2 lines of legend.
|
||
|
||
:func:`Box.place` uses the ``width`` and ``height`` keyword parameters
|
||
(if passed) to make its layouting decisions. If they aren't passed, all
|
||
remaining space is used.
|
||
|
||
And with that, you hopefully know enough to get started with your custom
|
||
setup. You can consult :class:`Monitor` and its subclasses to find out
|
||
*what* you can visualize and :class:`Visualizer` and its subclasses to
|
||
find out *how* you can visualize that data.
|
||
|
||
If you want to extend the original setup instead of doing a completely
|
||
custom one, you can call :func:`Gulik.autosetup` from your custom ``setup``
|
||
function and limit its area by using ``width`` and ``height`` as well as
|
||
``x`` and ``y`` keyword parameters.
|
||
|
||
Package reference
|
||
-----------------
|
||
|
||
.. automodule:: gulik
|
||
:members:
|
||
|
||
`gulik.collectors`
|
||
^^^^^^^^^^^^^^^^^^
|
||
|
||
.. automodule:: gulik.collectors
|
||
:members:
|
||
|
||
`gulik.monitors`
|
||
^^^^^^^^^^^^^^^^
|
||
|
||
.. automodule:: gulik.monitors
|
||
:members:
|
||
|
||
`gulik.visualizers`
|
||
^^^^^^^^^^^^^^^^^^^
|
||
|
||
.. automodule:: gulik.visualizers
|
||
:members:
|
||
|
||
`gulik.palettes`
|
||
^^^^^^^^^^^^^^^^
|
||
|
||
.. automodule:: gulik.palettes
|
||
:members:
|
||
|
||
`gulik.patterns`
|
||
^^^^^^^^^^^^^^^^
|
||
|
||
.. automodule:: gulik.patterns
|
||
:members:
|
||
|
||
`gulik.helpers`
|
||
^^^^^^^^^^^^^^^
|
||
|
||
.. automodule:: gulik.helpers
|
||
:members:
|
||
|
||
Indices and tables
|
||
==================
|
||
|
||
* :ref:`genindex`
|
||
* :ref:`search`
|