README
1
2 Logstalgia
3
4 a website access log visualisation tool
5
6 Copyright (C) 2008 Andrew Caudwell
7
8 http://logstalgia.io
9
10Contents
11========
12
131. Description
142. Requirements
153. Using Logstalgia
164. Copyright
17
181. Description
19==============
20
21Logstalgia is a visualization tool that replays or streams web server access
22logs as a retro arcade game simulation.
23
242. Requirements
25===============
26
27Logstalgia's display is rendered using OpenGL and requires a 3D accelerated
28video card to run.
29
30Logstalgia supports several standardized access.log formats used by web servers
31such as Apache and Nginx (see 'Supported Log Formats' below).
32
33As Logstalgia is designed to playback logs in real time you will need a log from
34a fairly busy webserver to achieve interesting results (eg 100s of requests
35each minute).
36
373. Using Logstalgia
38===================
39
40logstalgia [options] logfile
41
42options:
43
44 -f Fullscreen.
45
46 -WxH Set the window size. If -f is also supplied, will attempt to set the
47 video mode to this also. Add ! to make the window non-resizable.
48
49 --screen SCREEN
50 Set the number of the screen to display on.
51
52 --window-position XxY
53 Initial window position on your desktop which may be made up of
54 multiple monitors.
55
56 This will override the screen setting so don't specify both.
57
58 --frameless
59 Frameless window.
60
61 --title TITLE
62 Set a title.
63
64 -b, --background FFFFFF
65 Background colour in hex.
66
67 -x, --full-hostnames
68 Show full request ip/hostname.
69
70 -s, --simulation-speed
71 Simulation speed. Defaults to 1 (1 second-per-second).
72
73 -p, --pitch-speed
74 Speed balls travel across the screen (defaults to 0.15).
75
76 -u, --update-rate
77 Page Summary update speed. Defaults to 5 (5 seconds).
78
79 -g name,(HOST|URI|CODE)=regex[,SEP=chars][,MAX=n][,ABBR=n],percent[,colour]
80
81 Creates a new named summarizer group for requests for which a
82 specified attribute (HOST, URI or response CODE) matches a
83 regular expression. Percent specifies a vertical percentage of
84 screen to use.
85
86 SEP=chars can specify a list of separator characters (e.g. /)
87 to split on. The default separator is /.
88
89 MAX=n specifies the max depth into the path to be displayed.
90 (e.g. MAX=1 would show only root directory names of paths). By
91 default there is 0 (no limit).
92
93 ABBR=n specifies the minimum depth at which to allow partially
94 abbreviated strings. The default is 0 (allow). -1 to disallow.
95
96 A colour may optionally be supplied in hexadecimal format
97 (eg FF0000 for red) which will be applied to all labels
98 and request balls matched to the group.
99
100 Examples:
101
102 -g "HTML,URI=html?$,30"
103 -g "Lan,HOST=^192,30"
104 -g "Success,CODE=^[23],30"
105
106 If no groups are specified, the default groups are Images
107 (image files), CSS (.css files) and Scripts (.js files).
108
109 If there is enough space remaining a catch-all group 'Misc'
110 will appear as the last group.
111
112 --address-separators CHARS
113 List of address separator characters. Defaults to '.:'.
114
115 --address-max-depth DEPTH
116 Maximum depth to display in address summarizer. 0 for no maximum.
117
118 --address-abbr-depth DEPTH
119 Minimum abbreviation depth of address summarizer.
120 0 to always allow abbreviations, -1 to never abbreviate.
121
122 --path-separators CHARS
123 Default list of path separator characters. Defaults to /.
124
125 --path-max-depth DEPTH
126 Default maximum path depth shown in the summarizer.
127 0 for no maximum.
128
129 --path-abbr-depth DEPTH
130 Default minimum path abbreviation depth.
131 0 to always allow abbreviations, -1 to never abbreviate.
132
133 --paddle-mode MODE
134 Paddle mode (pid, vhost, single).
135
136 vhost - separate paddle for each virtual host in the log file.
137
138 pid - separate paddle for each process id in the log file.
139
140 single - single paddle (the default).
141
142 --paddle-position POSITION
143 Paddle position as a fraction of the view width (0.25 - 0.75).
144
145 --display-fields REQUEST_FIELDS
146 List of one or more request fields that are shown when the user
147 hovers the mouse over an individual request:
148
149 path - the path of the resource requested
150 hostname - hostname or IP address
151 response_size - size of the response in bytes
152 response_code - response code
153 method - method
154 protocol - protocol
155 timestamp - timestamp of request
156 referrer - referrer of the request
157 user_agent - user agent
158 vhost - virtual host name
159 log_entry - full log entry
160 pid - the pid of the instance that handled the request
161
162 Separate multiple fields with commas (eg 'path,hostname')
163
164 --sync Read from STDIN, ignoring entries before the current time.
165
166 --from, --to "YYYY-MM-DD hh:mm:ss +tz"
167 Show entries from a specific time period.
168
169 If a time zone offset isn't specified the local time zone is used.
170
171 Example accepted formats:
172
173 "2012-06-30"
174 "2012-06-30 12:00"
175 "2012-06-30 12:00:00 +12"
176
177 --start-position POSITION
178 Begin at some position in the log file (between 0.0 and 1.0).
179
180 --stop-position POSITION
181 Stop at some position.
182
183 --no-bounce
184 No bouncing.
185
186 --hide-response-code
187 Hide response code.
188
189 --hide-paddle
190 Hide paddle.
191
192 --hide-paddle-tokens
193 Hide paddle tokens shown in multi-paddle modes.
194
195 --hide-url-prefix
196 Hide URL protocol and hostname prefix of requests.
197
198 --disable-auto-skip
199 Disable automatic skipping of empty time periods.
200
201 --disable-progress
202 Disable the progress bar.
203
204 --disable-glow
205 Disable the glow effect.
206
207 --font-size SIZE
208 Font size (10 - 40).
209
210 --glow-duration
211 Duration of the glow (between 0.0 and 1.0).
212
213 --glow-multiplier
214 Adjust the amount of glow.
215
216 --glow-intensity
217 Intensity of the glow.
218
219 -o, --output-ppm-stream FILE
220 Write frames as PPM to a file ('-' for STDOUT).
221
222 -r, --output-framerate FPS
223 Framerate of output (used with --output-ppm-stream).
224
225 --load-config CONFIG_FILE
226 Load a config file.
227
228 --save-config CONFIG_FILE
229 Save a config file with the current options.
230
231 --detect-changes
232 Automatically reload config file when it is modified.
233
234 logfile
235 The path to the access log file to read or '-' if you wish to
236 supply log entries via STDIN.
237
238Examples:
239
240Watch an example access.log file using the default settings:
241
242 logstalgia data/example.log
243
244Watch the live access.log, starting from the most recent batch of entries
245in the log (requires tail). Note than '-' at the end is required for logstalgia
246to know it needs to read from STDIN:
247
248 tail -f /var/log/apache2/access.log | logstalgia -
249
250To follow the log in real time, use the --sync option. This will start reading
251from the next entry received on STDIN:
252
253 tail -f /var/log/apache2/access.log | logstalgia --sync
254
255Watch a remote access.log via ssh:
256
257 ssh user@example.com tail -f /var/log/apache2/access.log | logstalgia --sync
258
259Supported Log Formats:
260
261Logstalgia supports the following standardized log formats used by web servers like Apache and Nginx:
262
263NCSA Common Log Format (CLF)
264 "%h %l %u %t \"%r\" %>s %b"
265
266NCSA Common Log Format with Virtual Host
267 "%v %h %l %u %t \"%r\" %>s %b"
268
269NCSA extended/combined log format
270 "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
271
272NCSA extended/combined log format with Virtual Host
273 "%v %h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
274
275The process id (%P), or some other identifier, may be included as an additional
276field at the end of the entry. This can be used with '--paddle-mode pid' where
277a separate paddle will be created for each unique value in this field.
278
279
280Custom Log Format:
281
282Logstalgia now supports a pipe ('|') delimited custom log file format:
283
284 timestamp - unix timestamp of the request date.
285 hostname - hostname of the request
286 path - path requested
287 response_code - the response code from the webserver (eg 200)
288 response_size - the size of the response in bytes
289
290The following are optional:
291 success - 1 or 0 to indicate if successful
292 response_colour - response colour in hexidecial (#FFFFFF) format
293 referrer url - the referrer url
294 user agent - the user agent
295 virtual host - the virtual host (to use with --paddle-mode vhost)
296 pid - process id or some other identifier (--paddle-mode pid)
297
298If success or response_colour are not provided, they will be derived from the
299response_code using the normal HTTP conventions (code < 400 = success).
300
301
302Recording Videos:
303
304See the guide on the homepage for examples of recording videos with Logstalgia:
305
306 https://github.com/acaudwell/Logstalgia/wiki/Videos
307
308Interface:
309
310The time shown in the top left of the screen is set initially from the first log
311entry read and is incremented according to the simulation speed (-s).
312
313The counter in the bottom right hand corner shows the number of requests
314displayed since the start of the current session.
315
316Pressing space at any time will pause/unpause the simulation. While paused you
317may use the mouse to inspect the detail of individual requests.
318
319You can click on summarizer group entries on the left and right side of the
320screen to filter to requests matching that entry. Click on the filter
321description to remove the filter.
322
323Interactive keyboard commands:
324
325 (C) Displays Logstalgia logo
326 (N) Jump forward in time to next log entry
327 (+-) Adjust simulation speed
328 (<>) Adjust pitch speed
329 (F5) Reload config
330 (F6) Load config (Windows only)
331 (F11) Window frame toggle
332 (F12) Screenshot
333 (Alt+Enter) Fullscreen toggle
334 (Ctrl+S) Save config
335 (Home/End) Adjust address summarizer maximum depth
336 (Page Up/Down) Adjust group summarizer maximum depth
337 (Ctrl+Home/End) Adjust address summarizer abbreviation depth
338 (Ctrl+Page Up/Down) Adjust group summarizer abbreviation depth
339 (ESC) Quit
340
341
3424. Copyright
343============
344
345Logstalgia - web server access log visualization
346Copyright (C) 2008 Andrew Caudwell <acaudwell@gmail.com>
347
348This program is free software: you can redistribute it and/or modify
349it under the terms of the GNU General Public License as published by
350the Free Software Foundation, either version 3 of the License, or
351(at your option) any later version.
352
353This program is distributed in the hope that it will be useful,
354but WITHOUT ANY WARRANTY; without even the implied warranty of
355MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
356GNU General Public License for more details.
357
358You should have received a copy of the GNU General Public License
359along with this program. If not, see <http://www.gnu.org/licenses/>.
360