« back to all changes in this revision
Viewing changes to calamaris.1
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Philipp Frauenfelder
- Date: 2004-06-08 14:26:25 UTC
- Revision ID: james.westby@ubuntu.com-20040608142625-bctk532l0ms6of1j
Tags: upstream-2.59
Import upstream version 2.59
added
removed
calamaris.1
1
.TH CALAMARIS 1 "$Date: 2003/05/14 21:22:37 $" Handmade "Calamaris Manual"
2
3
.SH NAME
4
calamaris \- generate statistic out of log files from Proxy-Cache-Servers
5
6
.SH SYNOPSIS
7
cat log |
8
.B calamaris
9
[ calamaris_options ]
10
11
.SH DESCRIPTION
12
.B Calamaris
13
is used to produce statistical output from
14
.BR Squid ,
15
.B NetCache,
16
.B Inktomi Traffic Server,
17
.B Oops! proxy server,
18
.B Compaq Tasksmart,
19
.B Cisco Content Engines
20
or related Proxy log files. The resulting output can be
21
.I ascii
22
or
23
.IR html .
24
It is possible to cache calculated data in a file to use them in later runs.
25
26
This manual page describes the options of
27
.B Calamaris
28
and gives a few examples.
29
30
.SH OPTIONS
31
32
.SS Reports
33
34
.TP
35
.I -a
36
all: extracts all reports available,
37
.I -a
38
equals
39
.IR "-D 10 -d 20 -P 60 -r 20 -s -t 20" .
40
41
.TP
42
.I -d n
43
domain report: switches the top level and the second level report on. The
44
data is derived from the URL. The output is limited by n. (-1 is unlimited)
45
46
.TP
47
.I -p type
48
peak report: Measures the peaks of the Proxy usage in requests per second,
49
per minute and per hour. It reports peaks for TCP, UDP and ALL requests. If
50
set to
51
.I 'old'
52
these values were calculated with the old slow method, if set to
53
.I 'new'
54
the new faster (but still slow) method is used.
55
56
.TP
57
.I -P n
58
performance report: Shows the throughput of TCP requests for every n minutes.
59
60
.TP
61
.I -r n
62
requester report: Switches the UDP and TCP requester reports on. The output
63
is limited by n. (-1 is unlimited)
64
65
.TP
66
.I -R n
67
Requested report: adds to each line of the requester report the requested
68
URLs. The output is limited by n. (-1 is unlimited, and can result in very
69
very long reports.)
70
71
.B Warning:
72
Using this option breaks the privacy of your users! (see PRIVACY-Section
73
below)
74
75
.TP
76
.I -s
77
status report: alters the default behaviour of
78
.B Calamaris
79
and makes the status reports more verbose.
80
81
.TP
82
.I -t n
83
type report: switches the content type and the file extension report on. The
84
output is limited by n. (-1 is unlimited)
85
86
.TP
87
.I -D n
88
Distribution Histogram: shows size-based distribution of requested objects,
89
smaller numbers result in more verbose reports. (choose 2, 10 or 100 for
90
useful output.)
91
92
Allocation report: shows how different sized objects perform on your Proxy.
93
94
.SS Input Format
95
.TP
96
.I -f type
97
format: sets the type of input logfiles. If set to
98
99
.I 'auto'
100
.B Calamaris
101
tries to guess the input file format. This is the Default.
102
103
.B Note:
104
If the first line of your input file is corrupted, Calamaris will stop with
105
an error.
106
107
.I 'squid'
108
.B Calamaris
109
expects native logfile derived from
110
.B Squid V1.1.beta26-V2.x
111
or
112
.B OOPS.
113
114
.I 'squid-extended'
115
.B Calamaris
116
expects native logfile derived from
117
.B Squid V1.1.alpha1-V2.x
118
with
119
.I log_mime_hdrs
120
enabled or
121
.B Squid
122
with
123
.B Smartfilter-Patch.
124
or squid-style logfiles out of
125
.B Cisco Content Engines.
126
(This only enables parsing of these kind of logfile, the additional
127
data will be ignored.)
128
129
(Logging of MIME-Headers breaks the privacy of your users! (see
130
PRIVACY-Section below)
131
132
.I 'squid-old'
133
.B Calamaris
134
expects native logfile derived from
135
.B Squid V1.1.alpha1-V1.1.beta25.
136
137
.I 'nc'
138
.B Calamaris
139
expects Logfiles from
140
.B NetCache up to V4.x.
141
(Please see the README on this.)
142
143
.I 'its'
144
.B Calamaris
145
expects Logfiles from
146
.B Inktomi Traffic Server.
147
148
.I 'elff'
149
.B Calamaris
150
expects Logfiles in Extended Logfile Format (i.e. from
151
.B Compaq Tasksmart,
152
.B Novell Internet Caching System
153
or
154
.B NetCache V5.x
155
)
156
157
.I 'nse'
158
.B Calamaris
159
expects Logfiles in Netscape Extended-1 or Netscape Extended-2
160
Logfile Format (from
161
.B Netscape/ipoint Proxy-Server
162
)
163
164
.SS Output Format
165
Standard output format is plain ascii with 80 chars width.
166
167
.TP
168
.I -F type[,type[,type[,...]]]
169
Format: sets the format of the output-report. If set to
170
171
.I 'mail'
172
adds a subject header to the beginning of the report.
173
174
.I 'html'
175
all output is given in html with tables. Can be combined with
176
.I 'mail'
177
to send html mails.
178
179
.I 'html-embed'
180
all output is given in html with tables without HTML-Headers. Useful for
181
Server-Side-Includes.
182
183
.I 'unformatted'
184
gives out the raw numbers seperated by spaces. Useful for re-using the output
185
in other scripts. If you use this along with
186
.I -U,
187
the byte values are calculated in the given Unit, and displayed without
188
indication along with the numbers. the indication moves up to the header of
189
the report.
190
191
.TP
192
.I -M string
193
Meta: adds a custom string into the <HEAD> of a HTML-Report. Useful if you
194
want to add Stylesheets or something to the Report.
195
196
.B Note:
197
.I -M
198
works only in combination with
199
.IR -F
200
html.
201
202
.TP
203
.I -l string
204
logo: add a custom string to a HTML-Report. It'll be added to a table on the
205
top of the output.
206
.I -l '<A HREF="http://cord.de/"><IMG BORDER=0 SRC="http://cord.de/Images/cord/cordlog2n.gif" ALT="Cord"></A>'
207
will add my logo with a link to the Report.
208
209
.B Note:
210
.I -l
211
works only in combination with
212
.IR -F
213
html.
214
215
.TP
216
.I -U string
217
Unit: You can define this to K(ilo), M(ega), G(iga) or T(era) for
218
the Byte-units.
219
220
.TP
221
.I -S n[,n[,n[,...]]]
222
Show: Shows only the defined reports in the specified order. Default is to
223
display the reports as they are defined through the report-switches above. The
224
following numbers are defined:
225
226
.RS
227
0 Summary
228
.RE
229
.RS
230
1 Incoming request peak per protocol
231
.RE
232
.RS
233
2 Incoming transfer volume per protocol
234
.RE
235
.RS
236
3 Incoming requests by method
237
.RE
238
.RS
239
4 Incoming UDP-requests by status
240
.RE
241
.RS
242
5 Incoming TCP-requests by status
243
.RE
244
.RS
245
6 Outgoing requests by status
246
.RE
247
.RS
248
7 Outgoing requests by destination
249
.RE
250
.RS
251
8 Request-destinations by 2ndlevel-domain
252
.RE
253
.RS
254
9 Request-destinations by toplevel-domain
255
.RE
256
.RS
257
10 TCP-Request-protocol
258
.RE
259
.RS
260
11 Requested content-type
261
.RE
262
.RS
263
12 Requested extensions
264
.RE
265
.RS
266
13 Incoming UDP-requests by host
267
.RE
268
.RS
269
14 Incoming TCP-requests by host
270
.RE
271
.RS
272
15 Distribution Histogram
273
.RE
274
.RS
275
16 Performance in minute steps
276
277
.B Note:
278
Using this doesn't make
279
.B Calamaris
280
any faster, the internal calculations will
281
be done as the report-switches were set (see above).
282
283
.SS Caching
284
285
.TP
286
.I -i file
287
input file: You can reuse a cache file generated with
288
.I -o file
289
to add old data to a new report. Several files can be seperated with a ':'.
290
291
.B Note:
292
if you use more than one cache file, make sure they are chronologicaly
293
ordered (oldest first).
294
295
.B Note:
296
if you reuse cache-files, which were not created with
297
.I -d -1 -r -1 -t -1 -R -1
298
the number of 'others' is likely wrong everywhere.
299
300
.TP
301
.I -o file
302
output file:
303
.B Calamaris
304
stores a summary of the computed information in
305
.I file
306
and you can reuse it at a later time with
307
.IR -i .
308
309
.B Note:
310
The output file can be the same as the input file: it is simply overwritten
311
after reading the data. It is not recommended to change the options between
312
different runs if you include older data as this can result in strange
313
measurements.
314
315
.SS Misc
316
317
.TP
318
.I -H name
319
Host name: The name for the title or subject of the output. If set to
320
.I 'lookup'
321
.B Calamaris
322
looks up the host name of the system its been run on.
323
324
.TP
325
.I -n
326
no lookup: Switches the IP lookup for the requesters off.
327
328
.TP
329
.I -O
330
Order: Changes the sort order in the reports to request size, default is
331
sorting by number of requests.
332
333
.TP
334
.I -I t-t
335
Interval: defines which time-interval should be parsed. t has to be the
336
format yyyymmddhhmmss
337
338
.B Note:
339
omitting the beginning or ending date is allowed.
340
341
.TP
342
.I -N
343
N-level: All URL-Host reports will be switched from 2nd-level to
344
N-level-reports. (-1 shows a full urlhost-report)
345
346
.B Note:
347
This option is only useful with activated domain-report.
348
349
.TP
350
.I -T n
351
Time: Adjust the Performancereport in minutes for non GMT-Timezoners.
352
353
.TP
354
.I -c
355
case: Switch to case-insensitive. This is useful for
356
the 'Requested extensions' report.
357
358
.TP
359
.I -u
360
user: Switches the usage of eventually available ident information for
361
requester reports on.
362
363
.B Warning:
364
This breaks the privacy of your users! (see PRIVACY-Section below)
365
366
.TP
367
.I -z
368
zero: Switches reading from standard input off. You can use this to merge
369
many cache files to one (see
370
.I -i
371
and
372
.IR -o )
373
or to generate a report out of cache files.
374
375
.TP
376
.I -b n
377
benchmark: A switch for the impatient as it prints a '#' for every n parsed
378
lines.
379
380
.TP
381
.I -v
382
verbose: print more information about what is Calamaris is doing
383
and believing.
384
385
.TP
386
.I -L
387
Loop: prints the internal loop to STDERR. (for Debugging)
388
389
.TP
390
.I -C
391
Copyright: Prints the copyright information of
392
.BR Calamaris .
393
394
.TP
395
.I -h
396
help: Prints a brief description of the command line options.
397
398
.TP
399
.I -V
400
Version: Prints out the Version-Number.
401
402
.SH EXAMPLES
403
404
.TP
405
This example mails the daily statistics to root:
406
cat /var/log/squid/access.log | nice -39
407
.B calamaris
408
-aH 'daily worf' -F mail | mail root
409
410
.TP
411
This one only caches a summary for later use:
412
cat /var/log/squid/access.log |
413
.B calamaris
414
-a -o daily.`date +"%w"` > /dev/null
415
416
.TP
417
You can then use the caches to have weekly statistics:
418
419
if [ $DAYOFWEEK = "0" ]; then
420
.B calamaris
421
-a -i daily.1:daily.2:daily.3:daily.4:daily.5:daily.6:daily.0 -z -F mail -H "weekly worf" | mail root ;
422
fi
423
424
.SH BUGS
425
If you have a problem with
426
.BR Calamaris ,
427
please make sure that you use the recent version of
428
.B Calamaris
429
(see VERSION below). Also check that your proxy works correctly and doesn't
430
produce invalid Logfiles. (see the README for buglist and pointers.)
431
432
If you're sure that you've encountered a bug in Calamaris, please report it to
433
Calamaris-bug@cord.de. This also applies if Calamaris itself says 'please
434
report this'.
435
436
.SH PRIVACY
437
438
.B Calamaris
439
can be (mis-)used to track what users are requesting.
440
441
So please read the following and think about it, before using
442
.B Calamaris
443
to be the
444
.I Big Brother.
445
446
.TP
447
-
448
If you don't trust your users than there is something more wrong
449
than the loss of productivity.
450
451
.TP
452
-
453
Squid has some nice acl-mechanisms. If you think that your users
454
don't use the net properly, don't let them use it. (You can also
455
open the net at specific times or to specific sites, if you want.)
456
457
.TP
458
-
459
If you still want to use Calamaris that way, let your vict^Wusers
460
know, that they'll be monitored. (in Germany you have to let them
461
know!)
462
463
.SH "SEE ALSO"
464
.B squid(8)
465
466
.SH AUTHOR
467
Cord Beermann <Cord@Wunder-Nett.org>. There are also a lot of people who
468
contributed code, gave ideas or requested features. Look them up in the
469
executable.
470
471
This man page was written by Philipp Frauenfelder <pfrauenf@debian.org>,
472
maintainer of the Debian package. Maintenance is now taken over by
473
Cord Beermann.
474
475
.SH VERSION
476
477
Version of this manpage: $Id: calamaris.1,v 1.28 2003/05/14 21:22:37 cord Exp $
478
479
It describes the usage of Calamaris V2.58 and later.
480
481
Information about new releases, mailing lists, and other related issues
482
can be found from the
483
.B Calamaris
484
home page at http://Calamaris.Cord.de/
485
486
.SH WARRANTY
487
.B Calamaris
488
comes with "absolutely no warranty".
489
490
.SH COPYRIGHT
491
Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003 Cord Beermann
492
493
This program is free software; you can redistribute it and/or modify it under
494
the terms of the GNU General Public License as published by the Free Software
495
Foundation; either version 2 of the License, or (at your option) any later
496
version.
497
498
(If you modify and want to publish it under the name
499
.BR Calamaris ,
500
please ask me. I don't want to confuse the 'audience' with many different
501
versions of the same name and/or Version number. (This is not part of the
502
license, it is only a favour i asked of you.))
503
504
This program is distributed in the hope that it will be useful, but WITHOUT
505
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
506
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
507
details.
508
509
You should have received a copy of the GNU General Public License along with
510
this program; if not, write to the Free Software Foundation, Inc., 59 Temple
511
Place - Suite 330, Boston, MA 02111-1307, USA.
Loggerhead is a web-based interface for Breezy
Version: 2.0.1