1.. Licensed to the Apache Software Foundation (ASF) under one
2   or more contributor license agreements.  See the NOTICE file
3   distributed with this work for additional information
4   regarding copyright ownership.  The ASF licenses this file
5   to you under the Apache License, Version 2.0 (the
6   "License"); you may not use this file except in compliance
7   with the License.  You may obtain a copy of the License at
8
9   http://www.apache.org/licenses/LICENSE-2.0
10
11   Unless required by applicable law or agreed to in writing,
12   software distributed under the License is distributed on an
13   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14   KIND, either express or implied.  See the License for the
15   specific language governing permissions and limitations
16   under the License.
17
18.. include:: ../../common.defs
19
20.. _traffic_logstats:
21
22traffic_logstats
23****************
24
25Synopsis
26========
27
28:program:`traffic_logstats` [options]
29
30Description
31===========
32
33:program:`traffic_logstats` is a log parsing utility, that is intended to
34produce metrics for total and per origin requests. Currently, this utility
35only supports parsing and processing the Squid binary log format, or a custom
36format that is compatible with the initial log fields of the Squid format.
37
38Output can either be a human readable text file, or a JSON format. Parsing can
39be done incrementally, and :program:`traffic_logstats` supports restarting
40where it left off previously (state is stored in an external file). This is
41useful when collecting metrics periodically into a stats processing system,
42and also supports the case where a log file is rotated.
43
44The per-URL metrics (*-u*) requires that you specify a size of the LRU used
45for keeping the counters. This is to assure that :program:`traffic_logstats`
46does not consume an exorbitant amount of memory.
47
48Options
49=======
50
51.. program:: traffic_logstats
52
53.. option:: -f FILE, --log_file FILE
54
55   Specific logfile to parse
56
57.. option:: -o LIST, --origin_list LIST
58
59   Only show stats for listed Origins
60
61.. option:: -O FILE, --origin_file FILE
62
63   File listing Origins to show
64
65.. option:: -M COUNT, --max_origins COUNT
66
67   Max number of Origins to show
68
69.. option:: -u COUNT, --urls COUNT
70
71   Produce JSON stats for URLs, argument is LRU size
72
73.. option:: -U COUNT, --show_urls COUNT
74
75   Only show max this number of URLs
76
77.. option:: -A, --as_object
78
79   Produce URL stats as a JSON object instead of array
80
81.. option:: -C, --concise
82
83   Eliminate metrics that can be inferred from other values
84
85.. option:: -i, --incremental
86
87   Incremental log parsing
88
89.. option:: -S FILE, --statetag FILE
90
91   Name of the state file to use
92
93.. option:: -t, --tail
94
95   Parse the last <sec> seconds of log
96
97.. option:: -s, --summary
98
99   Only produce the summary
100
101.. option:: -j, --json
102
103   Produce JSON formatted output
104
105.. option:: -c, --cgi
106
107   Produce HTTP headers suitable as a CGI
108
109.. option:: -m, --min_hits
110
111   Minimum total hits for an Origin
112
113.. option:: -a, --max_age
114
115   Max age for log entries to be considered
116
117.. option:: -l COUNT, --line_len COUNT
118
119   Output line length
120
121.. option:: -T TAGS, --debug_tags TAGS
122
123   Colon-Separated Debug Tags
124
125.. option:: -r, --report_per_user
126
127   Report stats per username of the authenticated client ``caun`` instead of host, see `squid log format <../../admin-guide/logging/examples.en.html#squid>`_
128
129.. option:: -n, --no_format_check
130
131   Don't validate the log format field names according to the `squid log format <../../admin-guide/logging/examples.en.html#squid>`_.
132   This would allow squid format fields to be replaced, i.e. the username of the authenticated client ``caun`` with a random header value by using ``cqh``,
133   or to remove the client's host IP address from the log for privacy reasons.
134
135.. option:: -h, --help
136
137   Print usage information and exit.
138
139.. option:: -V, --version
140
141   Print version information and exit.
142
143