summaryrefslogtreecommitdiffstats
path: root/doc/kicker-applets/ktimemon.docbook
blob: 914df50b2de768dab6b4aa25afa8d6aa47068561 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
<chapter id="ktimemon">
<chapterinfo>

<title>&ktimemon;</title>

<authorgroup>
<author>
<firstname>Martin</firstname>
<surname>Maierhofer</surname>
<affiliation>
<address><email>m.maierhofer@tees.ac.uk</email></address>
</affiliation>
</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>
<date>2001-11-29</date>
<releaseinfo>0.03.01</releaseinfo>
<abstract>
<para>&ktimemon; is a system monitor for the Trinity Desktop Environment</para>
</abstract>
<keywordset>
<keyword>KDE</keyword>
<keyword>ktimemon</keyword>
<keyword>system monitor</keyword>
<keyword>timemon</keyword>
</keywordset>
</chapterinfo>

<title>Introduction</title>

<para>&ktimemon; is a small program to keep track of your computer's system
usage. It can display bar graphs containing information about
<acronym>CPU</acronym>, memory, and swap usage as well as disk usage and
context switch activity. In keeping with the spirit of <ulink
url="http://www.kde.org/">KDE</ulink>, it supports configuration via a
graphical user interface. It also supports <emphasis>docking</emphasis>,
&ie; it can display information in the system panel tray.</para>

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

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

<sect1 id="fund">
<title>Onscreen Fundamentals</title>

<para>
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 <emphasis>tool-tip</emphasis> (&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 <link linkend="config">Configuration</link>).
</para> 

<sect2 id="modes">
<title>Display Modes</title>

<para>
&ktimemon; can display two different sets of system information. As
explained in the <link linkend="config">Configuration</link> 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 <guilabel>Normal Mode</guilabel> (the default)
to <guilabel>Extended Mode</guilabel>, and vice versa.
</para>

<sect3 id="normalmode">
<title>Normal Mode</title>

<para>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 <link linkend="config">Configuration</link>). The three bar
graphs represent (from left to right):
<variablelist>
<varlistentry>
<term><acronym>CPU</acronym> usage.</term>
<listitem>
<para>&ktimemon; shows the bar in three different colors, representing
<acronym>CPU</acronym> time spent in various modes. From bottom to top
they are: kernel mode, user mode, and user mode with lowered priority
(<emphasis>nice</emphasis>) - since &Solaris; does not seem to support
statistics for nice mode, the topmost part of the bar represents time
spent in the <emphasis>wait</emphasis> state on such systems. The gap
from the top of the bar to the top of the window represents the
percentage the <acronym>CPU</acronym> idle time.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Memory usage.</term>
<listitem>
<para>Similar to the <acronym>CPU</acronym> 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 <quote>inactive</quote> 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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Swap usage.</term>
<listitem>
<para>This bar consists of a single field representing
the current swap usage relative to the system's total amount of swap
space. </para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>Clicking the mouse button bound to <quote>mode switch</quote> in
the &ktimemon; window switches to <quote>Extended Mode</quote>.</para>

</sect3>

<sect3 id="xtndmode">
<title>Extended Mode </title>

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

<variablelist>
<varlistentry>
<term>Paging activity.</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Swapping activity.</term>
<listitem>
<para>The second bar displays the analog
information for swap activity.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Context switches.</term>
<listitem>
<para>Again, this bar graph consists of a single
field which indicates the number of context switches in the last
sample interval.</para>
</listitem>
</varlistentry>
</variablelist>

<para>Since there is no <quote>natural</quote> way of scaling the
information shown in <quote>Extended Mode</quote>, by default
&ktimemon; uses <emphasis>autoscaling</emphasis> (explained in the
<link linkend="autoscaling">Common Questions Section</link>). There
is, however, the possibility of specifying the scaling information,
see the <link linkend="config">Configuration</link> section.</para>

<para>Note that the two sets of bar graphs share the same colors, &ie;
the colors setup for <quote>Normal Mode</quote> is also used for
displaying information in <quote>Extended Mode</quote> (see also <link
linkend="config">Configuration</link> on how to change the color
scheme).</para>
</sect3>
</sect2>
  </sect1>

<sect1 id="menu">
<title>Menu Structure</title>

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

<sect2 id="config-menu">
<title><guimenuitem>Settings...</guimenuitem></title>

<para>The <guimenuitem>Settings...</guimenuitem> menu item is used to
pop up the configuration dialog. Configuration options are discussed in
section <link linkend="config">Configuration</link>.
</para> 
</sect2>

<sect2 id="docked-in-panel">
<title><guimenuitem>Docked In Panel</guimenuitem></title>

<para>
By selecting the <guimenuitem>Docked In Panel</guimenuitem> 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 <quote>panelized</quote> &ktimemon; behaves
exactly like its big brother.
</para> 
</sect2>

<sect2 id="help">
<title><guimenu>Help</guimenu></title>

&help.menu.documentation;

</sect2>

<sect2 id="horizontal-bars">
<title><guimenuitem>Horizontal Bars</guimenuitem></title>

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

<sect2 id="quit">
<title><guimenuitem>Quit</guimenuitem></title>

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

<para>
The configuration information is saved in the file
<filename>$<envar>HOME</envar>/.trinity/share/config/ktimemonrc</filename>,
where <filename class="directory">$<envar>HOME</envar></filename> refers
to the user's home folder. If this file is deleted, &ktimemon; will
start in its default state in the next invocation.
</para> 
</sect2>
</sect1>

<sect1 id="config">
<title>Configuration</title>

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

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

<para>
In the <guilabel>Interaction</guilabel> page, mouse bindings can be
adapted. Clicking a mouse button on the &ktimemon; window can be
ignored, trigger a mode switch (see also <link
linkend="modes">Modes</link>), invoke the context menu (see also <link
linkend="menu">Menu</link>), 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.</para> 

<para>The <guilabel>Interaction</guilabel> 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 <link
linkend="fund">Onscreen Fundamentals</link>).</para> 
</sect1>

<sect1 id="faq">
<title>Common Questions and Answers </title>

<qandaset>
<qandaentry>
<question>
<para>Which operating systems does &ktimemon; support?</para>
</question>
<answer>
<para>
&ktimemon; supports &Linux; based systems with the <filename
class="devicefile">/proc</filename> file system, &Solaris; based
systems with the <filename>kstat</filename> library, and Digital
&UNIX; (formerly DEC/OSF1) systems with the
<command>table</command>(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.
</para>

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

</qandaentry>

<qandaentry id="autoscaling">
<question>
<para>
How does autoscaling work?
</para>
</question>
<answer>
<para>
Glad you asked. Since there is no sensible predetermined scaling factor
for paging/swapping operations and context switches (unlike &eg; memory
utilization, where you can take the total memory size as baseline),
&ktimemon; uses a semi-intelligent (well, ...) autoscaling
mechanism. Autoscaling works as follows:
</para>

<itemizedlist>
<listitem>
<para> 
Each of the three bar graphs as described in the <link
linkend="xtndmode">extended mode section</link> has an associated
scaling factor. The initial values of these factors are set to some
predetermined value.
</para> 
</listitem>
<listitem>
<para> 
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).
</para>
</listitem>
<listitem>
<para> 
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.
</para>
</listitem>
</itemizedlist>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>
Why does a message box with <errorname>diagnostic output from child
command</errorname> pop up?
</para>
</question>
<answer>
<para>
If you bind a mouse button to an external command as described in the
<link linkend="config">Configuration</link> 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 <systemitem>stderr</systemitem> output of the command
shell, and reports it in this message box.
</para>

<para>
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 <systemitem>stderr</systemitem>.  A simple and elegant
solution to this problem is to add <userinput>2&gt;/dev/null</userinput>
at the end of the command specification.  This redirects diagnostic
messages to message nirvana, and stops the message box popping up.
</para>
</answer>
</qandaentry>

</qandaset>
</sect1>

<sect1 id="ktimemon-thanks-and-acknowledgements">
<title>Thanks and Acknowledgments</title>

<para>&ktimemon; is based on an Xt version by my brother.</para>

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

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underGPL;

</sect1>
</chapter>

<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
End:
-->