logviewer.py - Session Log Viewer

Log Viewer

Allows the user to play back a given log file like a video (default) or display it in a syslog-like format. To view usage information, run it with the --help switch:

root@host:/opt/gateone $ ./logviewer.py --help
Usage:  logviewer.py [options] <log file>

  --version       show program's version number and exit
  -h, --help      show this help message and exit
  -f, --flat      Display the log line-by-line in a syslog-like format.
  -p, --playback  Play back the log in a video-like fashion. This is the
                default view.
  --pretty        Preserve font and character renditions when displaying the
                log in flat view (default).
  --raw           Display control characters and escape sequences when

Here's an example of how to display a Gate One log (.golog) in a flat, greppable format:

root@host:/opt/gateone $ ./logviewer.py --flat
Sep 09 21:07:14 Host/IP or SSH URL [localhost]: modern-host
Sep 09 21:07:16 Port [22]:
Sep 09 21:07:16 User: bsmith
Sep 09 21:07:17 Connecting to: ssh://bsmith@modern-host:22
Sep 09 21:07:17
Sep 09 21:07:17 bsmith@modern-host's password:
Sep 09 21:07:20 Welcome to Ubuntu 11.04 (GNU/Linux 2.6.38-11-generic x86_64)
Sep 09 21:07:20
Sep 09 21:07:20  * Documentation:  https://help.ubuntu.com/
Sep 09 21:07:20
Sep 09 21:07:20 Last login: Thu Sep 29 08:51:27 2011 from portarisk
Sep 09 21:07:20 bsmith@modern-host:~ $ ls
Sep 09 21:07:21 why_I_love_gate_one.txt  to_dont_list.txt
Sep 09 21:07:21 bsmith@modern-host:~ $

About Gate One's Log Format

Gate One's log format (.golog) is a gzip-compressed unicode (UTF-8) text file consisting of time-based frames separated by the unicode character, U+F0F0F0. Each frame consists of JavaScript-style timestamp (because it is compact) followed by a colon and then the text characters of the frame. A frame ends when a U+F0F0F0 character is encountered.

Here are two example .golog frames demonstrating the format:

1317344834868:\x1b[H\x1b[2JHost/IP or SSH URL [localhost]: <U+F0F0F>1317344836086:\r\nPort [22]: <U+F0F0F>

Gate One logs can be opened, decoded, and parsed in Python fairly easily:

import gzip
golog = gzip.open(path_to_golog).read()
for frame in golog.split(u"\U000f0f0f".encode('UTF-8')):
    frame_time = float(frame[:13]) # First 13 chars is the timestamp
    # Timestames can be converted into datetime objects very simply:
    datetime_obj = datetime.fromtimestamp(frame_time/1000)
    frame_text = frame[14:] # This gets you the actual text minus the colon
    # Do something with the datetime_obj and the frame_text


U+F0F0F0 is from Private Use Area (PUA) 15 in the Unicode Character Set (UCS). It was chosen at random (mostly =) from PUA-15 because it is highly unlikely to be used in an actual terminal program where it could corrupt a session log.

Class Docstrings

logviewer.get_frames(golog_path, chunk_size=131072)[source]

A generator that iterates over the frames in a .golog file, returning them as strings.


Retrieves the first frame from the given golog_path.


Returns the metadata from the log at the given golog_path in the form of a dict.

logviewer.playback_log(log_path, file_like, show_esc=False)[source]

Plays back the log file at log_path by way of timely output to file_like which is expected to be any file-like object with write() and flush() methods.

If show_esc is True, escape sequences and control characters will be escaped so they can be seen in the output. There will also be no delay between the output of frames (under the assumption that if you want to see the raw log you want it to output all at once so you can pipe it into some other app).

logviewer.escape_escape_seq(text, preserve_renditions=True, rstrip=True)[source]

Escapes escape sequences so they don't muck with the terminal viewing text Also replaces special characters with unicode symbol equivalents (e.g. so you can see what they are without having them do anything to your running shell)

If preserve_renditions is True, CSI escape sequences for renditions will be preserved as-is (e.g. font color, background, etc).

If rstrip is true, trailing escape sequences and whitespace will be removed.

logviewer.flatten_log(log_path, file_like, preserve_renditions=True, show_esc=False)[source]

Given a log file at log_path, write a string of log lines contained within to file_like. Where file_like is expected to be any file-like object with write() and flush() methods.

If preserve_renditions is True, CSI escape sequences for renditions will be preserved as-is (e.g. font color, background, etc). This is to make the output appear as close to how it was originally displayed as possible. Besides that, it looks really nice =)

If show_esc is True, escape sequences and control characters will be visible in the output. Trailing whitespace and escape sequences will not be removed.


Converts our standard recording-based log format into something that
can be used with grep and similar search/filter tools.
logviewer.render_log_frames(golog_path, rows, cols, limit=None)[source]

Returns the frames of golog_path as a list of HTML-encoded strings that can be used with the playback_log.html template. It accomplishes this task by running the frames through the terminal emulator and capturing the HTML output from the Terminal.dump_html method.

If limit is given, only return that number of frames (e.g. for preview)


Returns the rendered 256-color CSS. If container is provided it will be used as the {{container}} variable when rendering the template ( defaults to "gateone").

logviewer.render_html_playback(golog_path, render_settings=None)[source]

Generates a self-contained HTML playback file from the .golog at the given golog_path. The HTML will be output to stdout. The optional render_settings argument (dict) can include the following options to control how the output is rendered:

prefix:(Default: "go_default_") The GateOne.prefs.prefix to emulate when rendering the HTML template.
container:(Default: "gateone") The name of the #gateone container to emulate when rendering the HTML template.
theme:(Default: "black") The theme to use when rendering the HTML template.
colors:(Default: "default") The text color scheme to use when rendering the HTML template.


This function returns a byte string (not a unicode string).


Returns the size of the current terminal in the form of (rows, cols).

logviewer.main(args=['/usr/bin/sphinx-build', '-b', 'html', '-v', '-T', '-d', 'build/doctrees', 'source', 'build/html'])[source]

Parse command line arguments and view the log in the specified format.