Pexip log tools

Pexip provides a set of tools that make offline Pexip Infinity snapshots more readable. The tools package includes multiple free third-party tools (such as 7Zip, Python, OpenSSL, Notepad++, grepWin etc.), some PowerShell scripts (all signed), and some Python scripts.

These log tools are intended for advanced users and students of the Pexip Academy. Installation and use of these tools is at your own risk.

These tools are designed primarily to help analyze call flows. For training about troubleshooting within a Pexip Infinity deployment, and how Pexip support personnel use these logs to determine issues, then please sign up for the Troubleshooting and Logreading class at https://academy.pexip.com. Ensure that you read the description of the course and the prerequisites to make sure this is for you.

Downloading, installing and using the log tools

A 12-minute video on installing and using the tools is available at https://youtu.be/LwmTbwgBa3k.

The log tool is available from https://dl.pexip.com/resources/tools/PexipLogTools.exe. Download and run the PexipLogTools.exe file.

During installation on Windows, the scripts are placed into the c:\tools\scripts folder, with a shortcut added to the user's Send To folder. This allows you to simply right-click on a snapshot or downloaded log snippet and Send to -> Pexip Log Tools.

Installation instructions for Mac OSx are below.

How it works

The scripts extract snapshot files to C:\Snaps, create summarized call reports of the first 20 support log files that appear in the snapshot plus a system overview, then display these in a Notepad++ tab. If you send a downloaded support log snippet to the Pexip log tools, the script creates a call summary for that file and places it in a .\parsed folder in the current working folder. At the same time, the log files that are processed are translated into more human-readable versions, similar to how you see the support logs via the Administrator interface.

There are multiple other files In the expanded snapshot that may need unconcatenating (as each log line is joined with a ^M making the raw file difficult to read). These include:

  • Other support log files not included in the initial 20 that are analyzed. You can use grepWin, which is installed during setup, as a GUI grep tool to search through the files for specific Call-IDs, then process all of them at once.
  • The OSStatus log which contains 5 minute chunks of TOP, Netstat etc., from each of the nodes.

Each of these can be processed the same way, by simply right-clicking and sending to the Pexip Log Tools.

Keeping the scripts up-to-date

To update the underlying scripts (to keep in line with the latest versions of Pexip Infinity):

  1. Run the following script file:

    c:\tools\scripts\Get-Pexscripts.ps1

  2. This will break the script that shows the call reports (logreader). You need to then run the following to install some additional Python libraries:

    pip install -I lxml

  3. Optional. If you want to show some additional content in the system overview report (DBsummary) in relation to which certificates are installed and applied to the nodes, run the following to install some more Python libraries:

    pip install -I pyopenssl

Known issues

  • The applications require local administrative privileges in the Windows system for installation.
  • The PowerShell scripts require a minimum of PowerShell version 4 to run. Windows 7 shipped with PowerShell version 2 and is not upgraded with Windows updates. You should download and install the latest Windows Management Framework (which includes PowerShell) from https://www.microsoft.com/en-us/download/details.aspx?id=54616. You can see the PowerShell version you are using by opening a PowerShell window and using the $PSVersionTable command.
  • A support log snippet that is downloaded from Pexip Infinity is saved as txt, but if you already have multiple files in your Downloads folder the OS will rename this support (1).txt, support (2).txt, etc. The file must end in support.txt, so we recommend that you add the Call-ID to the beginning of the file name, just to distinguish one file from another. Also ensure there are no spaces in the file path or file name.

Mac OSx setup

The tools can be installed and used on Mac OSx. This script was updated in January 2020 for Catalina.

Requirements

Note that running this script will install the following:

Setup and use

  1. Run the following command in a Terminal window:

    zsh -c "$(curl -sSL https://dl.pexip.com/resources/tools/sync_pexscripts.sh)"

    This should install all of the relevant scripts.

  2. You can parse a snapshot using terminal with the following commands (assuming the downloaded snapshot is located in ~/Downloads):

    cd ~/Downloads

    pexsnap.py

    The script will either list the snapshots available or process the snapshot if only one snapshot was detected.

    Example output:

    $ pexsnap.py
    --------------------------------------------------
    Number Size Filename
    0      28MB diagnostic_snapshot_mgr_18_10_22_19_19_35.tgz
    1      7MB  diagnostic_snapshot_mgr_18_10_22_19_19_58.tgz
    --------------------------------------------------
    Select a number:
  3. There are a few configuration options in pexsnap.py — by default log files are opened in Sublime Text; you can change this to open the files in Atom by editing the options:

    open_in_atom = True # open parsed files in Atom when script completes

    open_in_subl = False # open parsed files in Sublime Text when script completes

    Sublime Text 3 is preferred and we have a language available here https://bit.ly/pexsublime; this is also automatically downloaded and installed by running the script.

  4. By default the snapshot is extracted to a folder with the snapshot name in the current directory, but you can also pass arguments to the script:

    usage: pexsnap.py [-h] [-i IN] [-o OUT]
    optional arguments:
    -h, --help show this help message and exit
    -i IN, --in IN path containing the snapshot(s)
    -o OUT, --out OUT path to extract the snapshot

    For example:

    $ pexsnap.py -i ~/Downloads/ -o ~/Desktop/snapshot_output

    Results in:

    Extracting diagnostic_snapshot_mgr_18_10_22_19_19_35.tgz to /Users/username/Desktop/snapshot_output

    Alternatively you can specify a pre-defined directory to extract the snapshot files into by editing the following statements in pexsnap.py:

    extract_snapshot_to_dir = False

    parsed_snaps = expanduser('~/Downloads/snapshots')