### Navigation

- index
- modules |
- next |
- previous |
- Gate One Documentation »
- Developer Documentation »

# `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>

    Options:
      --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
                    viewing.

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

Note

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.``playback_log`(log_path, file_like, show_esc=False)

  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.

`logviewer.``escape_escape_seq`(text, preserve_renditions=True, rstrip=True)

  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, preserve_renditions=True, show_esc=False)

  Given a log file at log_path, return a str of log lines contained within.

  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.

  NOTE: Converts our standard recording-based log format into something that can be used with grep and similar search/filter tools.

### Navigation

- index
- modules |
- next |
- previous |
- Gate One Documentation »
- Developer Documentation »