Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Logstalgia(1)		    General Commands Manual		 Logstalgia(1)

       Logstalgia -  a web server access log visualization tool

       logstalgia [options] logfile

       logstalgia  is  a visualization tool that replays or streams web	server
       access logs as a	retro arcade game simulation.

       logstalgia's display is rendered	using OpenGL and requires a 3D	accel-
       erated video card to run.

       Logstalgia supports several standardized	access.log formats used	by web
       servers such as Apache and Nginx	(see 'SUPPORTED	LOG FORMATS' below).

       As logstalgia is	designed to playback logs in real time you will	need a
       log  from  a  fairly  busy webserver to achieve interesting results (eg
       100s of requests	each minute).

       -f     Fullscreen.

	      Set the window size. If -f is also supplied, will	attempt	to set
	      the video	mode to	this also. Add ! to make the window non-resiz-

       --screen	SCREEN
	      Set the number of	the screen to display on.

       --window-position XxY
	      Initial window position on your desktop which may	be made	up  of
	      multiple monitors.

	      This will	override the screen setting so don't specify both.

	      Frameless	window.

       --title TITLE
	      Set a title.

       -b, --background
	      Background colour	in hex.

       -x  --full-hostnames
	      Show full	request	ip/hostname.

       -s, --simulation-speed
	      Simulation speed.	Defaults to 1 (1 second-per-second).

       -p, --pitch-speed
	      Speed balls travel across	the screen (defaults to	0.15).

       -u, --update-rate
	      Page Summary update speed. Defaults to 5 (5 seconds).

       -g	  name,(HOST|URI|CODE)=regex[,SEP=chars][,MAX=n][,ABBR=n],per-
	      Creates a	new named summarizer group for requests	 for  which  a
	      specified	attribute (HOST, URI or	response CODE) matches a regu-
	      lar expression.  Percent	specifies  a  vertical	percentage  of
	      screen to	use.

	      SEP=chars	can specify a list of separator	characters (e.g. /) to
	      split on.	The default separator is /.

	      MAX=n specifies the max depth into the  path  to	be  displayed.
	      (e.g.  MAX=1  would show only root directory names of paths). By
	      default there is 0 (no limit).

	      ABBR=n specifies the minimum depth at which to  allow  partially
	      abbreviated strings. The default is 0 (allow). -1	to disallow.

	      A	 colour	 may  optionally be supplied in	hexadecimal format (eg
	      FF0000 for red) which will be applied to all labels and  request
	      balls matched to the group.


	       -g "HTML,URI=html?$,30"
	       -g "Lan,HOST=^192,30"
	       -g "Success,CODE=^[23],30"

	      If no groups are specified, the default groups are Images	(image
	      files), CSS (.css	files) and Scripts (.js	files).

	      If there is enough space remaining a catch-all group 'Misc' will
	      appear as	the last group.

       --address-separators CHARS
	      List of address separator	characters. Defaults to	'.:'.

       --address-max-depth DEPTH
	      Maximum  depth  to display in address summarizer.	0 for no maxi-

       --address-abbr-depth DEPTH
	      Minimum abbreviation depth of address summarizer.	 0  to	always
	      allow abbreviations, -1 to never abbreviate.

       --path-separators CHARS
	      Default list of path separator characters. Defaults to /.

       --path-max-depth	DEPTH
	      Default  maximum	path  depth  shown in the summarizer. 0	for no

       --path-abbr-depth DEPTH
	      Default minimum path abbreviation	depth. 0 to always  allow  ab-
	      breviations, -1 to never abbreviate.

       --paddle-mode MODE
	      Paddle mode (pid,	vhost, single).

	      vhost  - separate	paddle for each	virtual	host in	the log	file.

	      pid    - separate	paddle for each	process	id in the log file.

	      single - single paddle (the default).

       --paddle-position POSITION
	      Paddle position as a fraction of the view	width (0.25 - 0.75).

       --display-fields	REQUEST_FIELDS
	      List  of one or more request fields that are shown when the user
	      hovers the mouse over an individual request:

		  path		- the path of the resource requested
		  hostname	- hostname or IP address
		  response_size	- size of the response in bytes
		  response_code	- response code
		  method	- method
		  protocol	- protocol
		  timestamp	- timestamp of request
		  referrer	- referrer URL of the request
		  user_agent	- user agent
		  vhost		- virtual host name
		  log_entry	- full log entry
		  pid		- the pid of the instance that handled the re-

	      Separate multiple	fields with commas (eg "path,hostname")

       --sync Read from	STDIN, ignoring	entries	before the current time.

       --from, --to "YYYY-MM-DD	hh:mm:ss +tz"
	      Show entries from	a specific time	period.

	      If  a  time  zone	 offset	isn't specified	the local time zone is

	      Example accepted formats:

		  "2012-06-30 12:00"
		  "2012-06-30 12:00:00 +12"

       --start-position	POSITION
	      Begin at some position in	the log	file (between 0.0 and 1.0).

       --stop-position POSITION
	      Stop at some position.

	      No bouncing.

	      Hide response code.

	      Hide paddle.

	      Hide paddle tokens shown in multi-paddle modes.

	      Hide URL protocol	and hostname prefix of requests.

	      Disable automatic	skipping of empty time periods.

	      Disable the progress bar.

	      Disable the glow effect.

       --font-size SIZE
	      Font size.

	      Duration of the glow (between 0.0	and 1.0).

	      Adjust the amount	of glow.

	      Intensity	of the glow.

       -o, --output-ppm-stream FILE
	      Write frames as PPM to a file ('-' for STDOUT).

       -r, --output-framerate FPS
	      Framerate	of output (used	with --output-ppm-stream).

       --load-config CONFIG_FILE
	      Load a config file.

       --save-config CONFIG_FILE
	      Save a config file with the current options.

	      Automatically reload config file when it is modified.

	      The path to the access log file to read or '-' if	 you  wish  to
	      supply log entries via STDIN.

       Watch an	example	access.log using the default settings:

	  logstalgia /usr/local/share/logstalgia/example.log

       Watch  the  live	access.log, starting from the most recent batch	of en-
       tries in	the log	(requires tail). Note than '-' at the end is  required
       for logstalgia to know it needs to read from STDIN:

	  tail -f /var/log/apache2/access.log |	logstalgia -

       To  follow the log in real time,	use the	--sync option. This will start
       reading from the	next entry received on STDIN:

	  tail -f /var/log/apache2/access.log |	logstalgia --sync

       Watch a remote access.log via ssh:

	  ssh tail -f /var/log/apache2/access.log |  logstal-
       gia --sync

       Logstalgia  supports the	following standardized log formats used	by web
       servers like Apache and Nginx:

	  NCSA Common Log Format (CLF)
	      "%h %l %u	%t \"%r\" %>s %b"

	  NCSA Common Log Format with Virtual Host
	      "%v %h %l	%u %t \"%r\" %>s %b"

	  NCSA extended/combined log format
	      "%h %l %u	%t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""

	  NCSA extended/combined log format with Virtual Host
	      "%v  %h  %l  %u  %t  \"%r\"  %>s	%b  \"%{Referer}i\"  \"%{User-

       The  process  id	 (%P), or some other identifier, may be	included as an
       additional field	at the end of the entry. This can be used with '--pad-
       dle-mode	 pid'  where a separate	paddle will be created for each	unique
       value in	this field.

       Logstalgia now supports a pipe ('|') delimited custom log file format:

	  timestamp	  - unix timestamp of the request date.
	  hostname	  - hostname of	the request
	  path		  - path requested
	  response_code	  - the	response code from the webserver (eg 200)
	  response_size	  - the	size of	the response in	bytes

       The following are optional:

	  success	  - 1 or 0 to indicate if successful
	  response_colour - response colour in hexidecial (#FFFFFF) format
	  referrer url	  - the	referrer url
	  user agent	  - the	user agent
	  virtual host	  - the	virtual	host (to use with --paddle-mode	vhost)
	  pid		  - process id or some other identifier	(--paddle-mode

       If  success  or	response_colour	are not	provided, they will be derived
       from the	response_code using the	normal HTTP conventions	(code <	400  =

       See  the	 guide	on  the	homepage for examples of recording videos with

       The time	shown in the top left of the screen is set initially from  the
       first  log  entry  read	and is incremented according to	the simulation
       speed (-s).

       The counter in the bottom right hand corner shows  the  number  of  re-
       quests displayed	since the start	of the current session.

       Pressing	 space	at  any	 time will pause/unpause the simulation. While
       paused you may use the mouse to inspect the detail  of  individual  re-

       You can click on	summarizer group entries on the	left and right side of
       the screen to filter to requests	matching that entry. Click on the fil-
       ter description to remove the filter.

       Interactive keyboard commands:

	  (q) Debug Information
	  (c) Displays Logstalgia logo
	  (n) Jump forward in time to next log entry.
	  (+-) Adjust simulation speed.
	  (<>) Adjust pitch speed.
	  (F5) Reload config
	  (F11)	Window frame toggle
	  (F12)	Screenshot
	  (Alt+Enter) Fullscreen toggle
	  (Ctrl+S) Save	config
	  (Home/End)	      Adjust address summarizer	maximum	depth
	  (Page	Up/Down)      Adjust group summarizer maximum depth
	  (Ctrl+Home/End)     Adjust address summarizer	abbreviation depth
	  (Ctrl+Page Up/Down) Adjust group summarizer abbreviation depth
	  (ESC)	Quit

	Written	by Andrew Caudwell

	Project	Homepage:

	Copyright (C) 2008 Andrew Caudwell (

	This program is	free software; you can redistribute it and/or
	modify it under	the terms of the GNU General Public License
	as published by	the Free Software Foundation; either version
	3 of the License, or (at your option) any later	version.

	This program is	distributed in the hope	that it	will be	useful,
	but WITHOUT ANY	WARRANTY; without even the implied warranty of
	GNU General Public License for more details.

	You should have	received a copy	of the GNU General Public License
	along with this	program.  If not, see <>.

	Catalyst IT (

	For supporting the development and promotion of	Logstalgia!



Want to link to this manual page? Use this URL:

home | help