# &ktimemon;

## Introduction

&ktimemon; is a small program to keep track of your computer's system usage. It can display bar graphs containing information about CPU, memory, and swap usage as well as disk usage and context switch activity. In keeping with the spirit of KDE, it supports configuration via a graphical user interface. It also supports docking, &ie; it can display information in the system panel tray.

Currently, &ktimemon; only supports a limited number of systems: &Linux; based installations with the `/proc` file system, &Solaris; based installations with the `kstat` library, and Digital &UNIX; (formerly DEC/OSF1) based installations with the `table`(2) system call. Help with porting it to other platforms is most welcome.

&ktimemon; can be started from the command line or from the &kde; start menu (in the Utilities submenu). If you choose to start from the command line, &ktimemon; honors the usual &X-Window; program flags such as `-geometry`. &ktimemon; is session-aware, &ie; it keeps track of the current state (colors, &etc;) and restores it in the user's next session.

## Onscreen Fundamentals

After starting &ktimemon; a small window will appear displaying information gathered from the operating system. If you move the mouse pointer over the &ktimemon; window and let it rest for a small amount of time, a tool-tip (&ie; a small transient window) will appear. The tool-tip contains numeric information about the system parameters displayed by the bar graphs. Tool-tips can be disabled (refer to Configuration).

### Display Modes

&ktimemon; can display two different sets of system information. As explained in the Configuration chapter, mouse buttons can be bound to various actions. Per default, the left mouse button is bound to the mode switch action, &ie; by clicking the &LMB; mouse button anywhere in the &ktimemon; window, the displayed information switches from Normal Mode (the default) to Extended Mode, and vice versa.

#### Normal Mode

After starting &ktimemon; for the first time, it will show information about the current CPU activity, as well as memory and swap usage. Three bar graphs are used to show this information; they are updated regularly (the default sample interval is 0.5s, but it can be changed, see Configuration). The three bar graphs represent (from left to right):

CPU usage.

- &ktimemon; shows the bar in three different colors, representing CPU time spent in various modes. From bottom to top they are: kernel mode, user mode, and user mode with lowered priority (nice) - since &Solaris; does not seem to support statistics for nice mode, the topmost part of the bar represents time spent in the wait state on such systems. The gap from the top of the bar to the top of the window represents the percentage the CPU idle time.

Memory usage.

- Similar to the CPU usage bar, this bar is composed of three sub fields, representing (from bottom to top): memory allocated by processes, memory used for I/O buffering, and memory used for file caching. For Digital &UNIX; based systems, the middle section represents inactive memory (&ie; memory allocated and not used for a certain amount of time), and for &Solaris; based systems, the middle section of the bar is not used, and the topmost section represents the amount of memory used by the kernel. Again, the gap from the top of the bar to the top of the window represents free memory.

Swap usage.

- This bar consists of a single field representing the current swap usage relative to the system's total amount of swap space.

Clicking the mouse button bound to mode switch in the &ktimemon; window switches to Extended Mode.

#### Extended Mode

In this mode, the three bar graphs are used to display a different set of system information. Again from left to right, they show:

Paging activity.

- This bar consists of two parts, the lower half of which shows the number of memory pages written to secondary storage in the last sample interval. Similarly, the upper half indicates the number of pages read from secondary storage.

Swapping activity.

- The second bar displays the analog information for swap activity.

Context switches.

- Again, this bar graph consists of a single field which indicates the number of context switches in the last sample interval.

Since there is no natural way of scaling the information shown in Extended Mode, by default &ktimemon; uses autoscaling (explained in the Common Questions Section). There is, however, the possibility of specifying the scaling information, see the Configuration section.

Note that the two sets of bar graphs share the same colors, &ie; the colors setup for Normal Mode is also used for displaying information in Extended Mode (see also Configuration on how to change the color scheme).

## Menu Structure

By default, the &RMB; mouse button is bound to the menu pop-up action, &ie; clicking the right mouse button anywhere in the &ktimemon; window brings up a menu, which is discussed in the following sections.

### Settings...

The Settings... menu item is used to pop up the configuration dialog. Configuration options are discussed in section Configuration.

### Docked In Panel

By selecting the Docked In Panel menu item, &ktimemon; switches between its standard display (&ie; a normal window) and the panelized state, where the &ktimemon; window disappears and a smaller version is displayed in the system panel. Apart from the reduction in size, the panelized &ktimemon; behaves exactly like its big brother.

### Help

&help.menu.documentation;

### Horizontal Bars

By selecting the Horizontal Bars menu entry, &ktimemon; switches from vertical bars to horizontal bars and vice versa. Not very useful, but it was easy to implement ;-)

### Quit

The Quit menu item - surprise, surprise -- is used to terminate &ktimemon;. It will save the current state (⪚ the color scheme, window size, whether it is displayed in the panel) and restore the state in the next invocation.

The configuration information is saved in the file `$`HOME`/.kde/share/config/ktimemonrc`, where `$`HOME`` refers to the user's home folder. If this file is deleted, &ktimemon; will start in its default state in the next invocation.

## Configuration

&ktimemon; can be configured via a straight-forward dialog (see also the discussion of the Configuration Menu). On the General page, the sample interval can be specified as well as scaling information (see also the discussion of the extended mode). If the Autoscaling check box is ticked (autoscaling is explained in the FAQ section), the scaling factors cannot be edited, since &ktimemon; determines them automatically.

The Colors page can be used to tailor the colors of the bar graph to individual preferences. A small sample bar graph gives immediate feedback.

In the Interaction page, mouse bindings can be adapted. Clicking a mouse button on the &ktimemon; window can be ignored, trigger a mode switch (see also Modes), invoke the context menu (see also Menu), or invoke an external process. The command line specified for external processes is interpreted by the standard shell, &ie; shell commands, environment variables, redirection &etc; can be used.

The Interaction page also contains a check box which can be used to disable to automatic appearance of tool-tips with numeric information about the bar graphs (compare Onscreen Fundamentals).

## Common Questions and Answers

Which operating systems does &ktimemon; support?

&ktimemon; supports &Linux; based systems with the `/proc` file system, &Solaris; based systems with the `kstat` library, and Digital &UNIX; (formerly DEC/OSF1) systems with the `table`(2) system call interface. Only the &Linux; version has been thoroughly tested, if you experience any problems with the &Solaris;/Digital &UNIX; port, please do not hesitate to contact me.

Also, contributions to &ktimemon; to adapt it to other platforms are most welcome. Please contact me at m.maierhofer@tees.ac.uk if you intend to port &ktimemon; to other flavors of &UNIX;.

How does autoscaling work?

Glad you asked. Since there is no sensible predetermined scaling factor for paging/swapping operations and context switches (unlike ⪚ memory utilization, where you can take the total memory size as baseline), &ktimemon; uses a semi-intelligent (well, ...) autoscaling mechanism. Autoscaling works as follows:

- Each of the three bar graphs as described in the extended mode section has an associated scaling factor. The initial values of these factors are set to some predetermined value.

- Each time a new sample is displayed, the respective value is tentatively scaled with the corresponding factor. If the value can be displayed in the scale chosen by the factor, no change occurs (&ie; small changes in the activity are reflected by a changing height of the bar).

- If the scaled value would be either too large or too small to be displayed with the current scaling factor, the scaling is adjusted so that the new value displayed is roughly halfway up the bar graph. Thus, subsequent changes should have a good chance of getting displayed relative to the current value, without having to change the scale again.

Why does a message box with diagnostic output from child command pop up?

If you bind a mouse button to an external command as described in the Configuration chapter, &ktimemon; does not check for a valid command name. Instead a command shell is invoked to execute the statement, so shell commands, environment variables and more can be used. To allow some feedback to the user, &ktimemon; monitors the `stderr` output of the command shell, and reports it in this message box.

While this scheme can be helpful in case a command is not found, it can be quite annoying if the invoked command prints harmless diagnostic information on `stderr`. A simple and elegant solution to this problem is to add `2>/dev/null` at the end of the command specification. This redirects diagnostic messages to message nirvana, and stops the message box popping up.

## Thanks and Acknowledgments

&ktimemon; is based on an Xt version by my brother.

Thanks to Tobe Toben, ttoben@artis.uni-oldenburg.de, Cristian Tibirna ctibirna@gch.ulaval.ca, Dirk A. Mueller dmuell@rhrk.uni-kl.de, Mark Krischer krischem@amp.com, and Lubos Lunak l.lunak@sh.cvut.cz for bug reports, patches, comments, suggestions.

&underGPL;