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 --high-dpi
38 Request a high DPI display when creating the window.
39 On some platforms such as MacOS, the window resolution is speci‐
41 fied in points instead of pixels. The --high-dpi flag may be
42 required to access some higher resolutions.
43 E.g. requesting a high DPI 800x600 window may produce a window
45 that is 1600x1200 pixels.
46 --window-position XxY
48 Initial window position on your desktop which may be made up of
49 multiple monitors.
50 This will override the screen setting so don't specify both.
52 --frameless
54 Frameless window.
55 --title TITLE
57 Set a title.
58 -b, --background
60 Background colour in hex.
61 -x --full-hostnames
63 Show full request ip/hostname.
64 -s, --simulation-speed
66 Simulation speed. Defaults to 1 (1 second-per-second).
67 -p, --pitch-speed
69 Speed balls travel across the screen (defaults to 0.15).
70 -u, --update-rate
72 Page Summary update speed. Defaults to 5 (5 seconds).
73 -g name,(HOST|URI|CODE)=regex[,SEP=chars][,MAX=n][,ABBR=n],per‐
75 cent[,colour]
76 Creates a new named summarizer group for requests for which a
77 specified attribute (HOST, URI or response CODE) matches a regu‐
78 lar expression. Percent specifies a vertical percentage of
79 screen to use.
80 SEP=chars can specify a list of separator characters (e.g. /) to
82 split on. The default separator is /.
83 MAX=n specifies the max depth into the path to be displayed.
85 (e.g. MAX=1 would show only root directory names of paths). By
86 default there is 0 (no limit).
87 ABBR=n specifies the minimum depth at which to allow partially
89 abbreviated strings. The default is 0 (allow). -1 to disallow.
90 A colour may optionally be supplied in hexadecimal format (eg
92 FF0000 for red) which will be applied to all labels and request
93 balls matched to the group.
94 Examples:
96 -g "HTML,URI=html?$,30"
98 -g "Lan,HOST=^192,30"
99 -g "Success,CODE=^[23],30"
100 If no groups are specified, the default groups are Images (image
102 files), CSS (.css files) and Scripts (.js files).
103 If there is enough space remaining a catch-all group 'Misc' will
105 appear as the last group.
106 --address-separators CHARS
108 List of address separator characters. Defaults to '.:'.
109 --address-max-depth DEPTH
111 Maximum depth to display in address summarizer. 0 for no maxi‐
112 mum.
113 --address-abbr-depth DEPTH
115 Minimum abbreviation depth of address summarizer. 0 to always
116 allow abbreviations, -1 to never abbreviate.
117 --path-separators CHARS
119 Default list of path separator characters. Defaults to /.
120 --path-max-depth DEPTH
122 Default maximum path depth shown in the summarizer. 0 for no
123 maximum.
124 --path-abbr-depth DEPTH
126 Default minimum path abbreviation depth. 0 to always allow ab‐
127 breviations, -1 to never abbreviate.
128 --paddle-mode MODE
130 Paddle mode (pid, vhost, single).
131 vhost - separate paddle for each virtual host in the log file.
133 pid - separate paddle for each process id in the log file.
135 single - single paddle (the default).
137 --paddle-position POSITION
139 Paddle position as a fraction of the view width (0.25 - 0.75).
140 --display-fields REQUEST_FIELDS
142 List of one or more request fields that are shown when the user
143 hovers the mouse over an individual request:
144 path - the path of the resource requested
146 hostname - hostname or IP address
147 response_size - size of the response in bytes
148 response_code - response code
149 method - method
150 protocol - protocol
151 timestamp - timestamp of request
152 referrer - referrer URL of the request
153 user_agent - user agent
154 vhost - virtual host name
155 log_entry - full log entry
156 pid - the pid of the instance that handled the re‐
157 quest
158 Separate multiple fields with commas (eg "path,hostname")
160 --sync Read from STDIN, ignoring entries before the current time.
162 --from, --to "YYYY-MM-DD hh:mm:ss +tz"
164 Show entries from a specific time period.
165 If a time zone offset isn't specified the local time zone is
167 used.
168 Example accepted formats:
170 "2012-06-30"
172 "2012-06-30 12:00"
173 "2012-06-30 12:00:00 +12"
174 --start-position POSITION
176 Begin at some position in the log file (between 0.0 and 1.0).
177 --stop-position POSITION
179 Stop at some position.
180 --no-bounce
182 No bouncing.
183 --hide-response-code
185 Hide response code.
186 --hide-paddle
188 Hide paddle.
189 --hide-paddle-tokens
191 Hide paddle tokens shown in multi-paddle modes.
192 --hide-url-prefix
194 Hide URL protocol and hostname prefix of requests.
195 --disable-auto-skip
197 Disable automatic skipping of empty time periods.
198 --disable-progress
200 Disable the progress bar.
201 --disable-glow
203 Disable the glow effect.
204 --font-size SIZE
206 Font size.
207 --glow-duration
209 Duration of the glow (between 0.0 and 1.0).
210 --glow-multiplier
212 Adjust the amount of glow.
213 --glow-intensity
215 Intensity of the glow.
216 -o, --output-ppm-stream FILE
218 Write frames as PPM to a file ('-' for STDOUT).
219 -r, --output-framerate FPS
221 Framerate of output (used with --output-ppm-stream).
222 --load-config CONFIG_FILE
224 Load a config file.
225 --save-config CONFIG_FILE
227 Save a config file with the current options.
228 --detect-changes
230 Automatically reload config file when it is modified.
231 logfile
233 The path to the access log file to read or '-' if you wish to
234 supply log entries via STDIN.
235
238 Watch an example access.log using the default settings:
239 logstalgia /usr/share/logstalgia/example.log
241 Watch the live access.log, starting from the most recent batch of en‐
243 tries in the log (requires tail). Note than '-' at the end is required
244 for logstalgia to know it needs to read from STDIN:
245 tail -f /var/log/apache2/access.log | logstalgia -
247 To follow the log in real time, use the --sync option. This will start
249 reading from the next entry received on STDIN:
250 tail -f /var/log/apache2/access.log | logstalgia --sync
252 Watch a remote access.log via ssh:
254 ssh user@example.com tail -f /var/log/apache2/access.log | logstal‐
256 gia --sync
257
260 Logstalgia supports the following standardized log formats used by web
261 servers like Apache and Nginx:
262 NCSA Common Log Format (CLF)
264 "%h %l %u %t \"%r\" %>s %b"
265 NCSA Common Log Format with Virtual Host
267 "%v %h %l %u %t \"%r\" %>s %b"
268 NCSA extended/combined log format
270 "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
271 NCSA extended/combined log format with Virtual Host
273 "%v %h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-
274 agent}i\""
275 The process id (%P), or some other identifier, may be included as an
277 additional field at the end of the entry. This can be used with '--pad‐
278 dle-mode pid' where a separate paddle will be created for each unique
279 value in this field.
280
283 Logstalgia now supports a pipe ('|') delimited custom log file format:
284 timestamp - unix timestamp of the request date.
286 hostname - hostname of the request
287 path - path requested
288 response_code - the response code from the webserver (eg 200)
289 response_size - the size of the response in bytes
290 The following are optional:
292 success - 1 or 0 to indicate if successful
294 response_colour - response colour in hexidecial (#FFFFFF) format
295 referrer url - the referrer url
296 user agent - the user agent
297 virtual host - the virtual host (to use with --paddle-mode vhost)
298 pid - process id or some other identifier (--paddle-mode
299 pid)
300 If success or response_colour are not provided, they will be derived
302 from the response_code using the normal HTTP conventions (code < 400 =
303 success).
304
307 See the guide on the homepage for examples of recording videos with
308 Logstalgia:
309 https://github.com/acaudwell/Logstalgia/wiki/Videos
311
314 The time shown in the top left of the screen is set initially from the
315 first log entry read and is incremented according to the simulation
316 speed (-s).
317 The counter in the bottom right hand corner shows the number of re‐
319 quests displayed since the start of the current session.
320 Pressing space at any time will pause/unpause the simulation. While
322 paused you may use the mouse to inspect the detail of individual re‐
323 quests.
324 You can click on summarizer group entries on the left and right side of
326 the screen to filter to requests matching that entry. Click on the fil‐
327 ter description to remove the filter.
328 Interactive keyboard commands:
330 (q) Debug Information
332 (c) Displays Logstalgia logo
333 (n) Jump forward in time to next log entry.
334 (+-) Adjust simulation speed.
335 (<>) Adjust pitch speed.
336 (F5) Reload config
337 (F11) Window frame toggle
338 (F12) Screenshot
339 (Alt+Enter) Fullscreen toggle
340 (Ctrl+S) Save config
341 (Home/End) Adjust address summarizer maximum depth
342 (Page Up/Down) Adjust group summarizer maximum depth
343 (Ctrl+Home/End) Adjust address summarizer abbreviation depth
344 (Ctrl+Page Up/Down) Adjust group summarizer abbreviation depth
345 (ESC) Quit
346
349 Written by Andrew Caudwell
350 Project Homepage: http://logstalgia.io
352
354 Copyright (C) 2008 Andrew Caudwell (acaudwell@gmail.com)
355 This program is free software; you can redistribute it and/or
357 modify it under the terms of the GNU General Public License
358 as published by the Free Software Foundation; either version
359 3 of the License, or (at your option) any later version.
360 This program is distributed in the hope that it will be useful,
362 but WITHOUT ANY WARRANTY; without even the implied warranty of
363 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
364 GNU General Public License for more details.
365 You should have received a copy of the GNU General Public License
367 along with this program. If not, see <http://www.gnu.org/licenses/>.
368
370 Catalyst IT (catalyst.net.nz)
371 For supporting the development and promotion of Logstalgia!
373 Logstalgia(1)