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