Analyse SIP Communications with 3CX Log Viewer

Introduction

The 3CX Log Viewer is used to read and filter the logs generated by the 3CX Phone System, which allows users to build advanced filters and easily sieve through logs.

Installation

The 3CX Log Viewer can be downloaded and installed directly from the 3CX Management Console.

Version 14 users: Go to Help > Download 3CX Log Viewer. This will download a zip package on your computer. Extract and double click on “3cxBinLogViewer.exe”
Version 12 users: Go to 3CX Phone System Updates > Other Updates and download it from there. 3CX Log Viewer will be downloaded to <Program Files\3CX PhoneSystem\Bin\Support\3CXBinLogViewer>. You can start the application by running the 3cxBinLogViewer.exe file.

You can also click on this link to download the log viewer separately.
3CX Log viewer for 32 bit Operating systems
3CX Log viewer for 64 bit Operating systems

3CX Log Viewer Overview

The first time you load the 3CX Log Viewer, click on File > Open and navigate to the location where 3CX writes logging information. In there you will find a file named “3CXPhoneSystem.bldef”. If you are running the 3CX Log Viewer on a machine which does not have 3CX Phone System installed, or you need to load the logs from a different location, open the files from File > Open, and select a blrec or bldef file.

The 3CX Log Viewer consists of four main sections which are illustrated below.

3CX Log Viewer - Main Window

Filtering Options

The Filtering Options section allows you to select which logs are displayed in the Log Window.

3CX Log Viewer - Filtering

Filter by Date: Select to filter the logging by date / time range. 3CX Phone System timestamps the logs using the time of the local machine.

Filter by Tags: Most log lines have been assigned a tag. For example, all the logs for a particular call are tagged with their Call ID (e.g. CallID 10). There are many tags which you can use. We’ll look at some important tags at the end of this guide.

When you want to filter by a particular tag, you double click on the tag and the Tag formula window and the formula text will be updated with your selection. Click the “Apply” button to filter using the selected tags.

You’ll come across situations where you want to use operators in your filter. For example, if you select SiPMsg.method(INVITE), and need only the Invites for extension 100, you can click the “AND” button and then select “DN(100)” from the tag list.

You can also build nested Queries. For example, you might want to filter for the INVITE requests for calls with ID 12 and 13. This is shown in the screenshot below:

3CX Log Viewer - Nested Filtering

The Formula text gets updated as you add and remove tags. Copy and and save formulas that you use often. This will save you time trying to find the tag needed.

Important Note – The tags shown are the ones which are found in the binary log. So if, for example, you are trying to filter the log for extension 116, and you are not finding DN 116, it means that the log does not contain any entries from extension 116.

Highlight Matching Logs: When this checkbox is checked, all the log entries are displayed, and the logging that matches the filtering criteria will be highlighted in red. Press “Apply” to refresh the logging using your selected filtering criteria.

Log Window

3CX Log Viewer - Logs Window

The log window is where the log entries are shown. You can right click on an entry and “Select All” the log entries or “Copy” the selected logs to the clipboard. You can select multiple entries by holing down the Shift or Control key. The above screenshot shows log entries for Extension 100 being highlighted.

Tags Window

3CX Log Viewer - Tags Window

The tags window will show all the tags that have been assigned to the selected log entry. You can double-click on any of the tags in order to filter using that tag. If using Operators, you first need to select the operator before double clicking on the tag in the tags window. The tags window is very useful when you want to learn about new tags. For example, in the selected log entry the CallId tag is 12 and the DestAddr.Host is an IP address.

Detail Window

When you select a log line, the detail window will show it.

Some log entries consist of multiple lines which are not shown in the main log window. These are shown in the detail window. An example is the SIP messages that are shown in the screenshot below.

3CX Log Viewer - Details Window

Other Features

Records / Page: The 3CX Log Viewer uses paging – it doesn’t show the binary log in one go, otherwise it might use too many resources and too much time for a large binary log file. It will log an X amount of records per page. By default, it loads 10,000 lines per page. This number is configurable from the Preferences section.

Use the arrow buttons at the top to move from one page to the next or to go to the beginning or the end of the log file.

Searching the Logs:  You can also search the log by inserting the search term in the Find: entry field and pressing “Enter“. This will search from the current position to the end. Alternatively, use the down button to search downwards and hit the up button to search upwards. The search will always be performed starting from the current position. Note that searches are done across all the pages until the search reaches the beginning or the end of the log file.

Opening Logs: When you open the 3CX Log Viewer, it will automatically load the logs from the last location. You can open another set of 3CX logs from File > Open. You can also view a set of logs that you recently opened from File > Recent Logs

Preferences:  From View > Preferences, you can configure how many records are shown per page. You can also select the Severity mask and Log Level that will be used when showing the logs. The screenshot below shows the default values, which should be valid in most troubleshooting situations. These setting are retained when you close the 3CX Log Viewer.

3CX Log Viewer - Preferences

Associate Log Files: From Settings > Associate log files, you can associate blrec and bldef files with the 3CX Log Viewer.

Export to Text:  From Tools > Export to text, you can export the filtered log entries to a text file. All log entries from all pages will be exported. Remove any filters if you want all the log entries to be exported. You might need to adjust your default filtering preferences from Settings > Preferences.

Command Line: The 3CX Log Viewer can also be executed from the command line, in which case it will accept the following parameters:

3cxBinLogViewer.exe < Input Path to log files> <Export Path to text file>

If you run 3cxBinLogViewer.exe <Input Path to log files>, 3CX Log Viewer will load the log files found in the path specified. For example – 3cxBinLogViewer.exe c:\3cxlogs.

If you run 3cxBinLogViewer.exe <Input Path to log files> <Path to export text file>, 3CX Log Viewer will export the binary logs in the Input Path to the text file specified in the Export Path. For example – 3cxBinLogViewer.exe c:\3cxlogs c:\3cxlogs\txtlog.txt.

Information on the 3CX Server Logs

The 3CX Server Logs are made up of one bldef file and one or more blrec files. The bldef file is the file that contains information about the tags, and other index data. The blrec files are the files that hold the logs. Both files are required in order to read 3CX Logs. Note that one bldef file can be used to read multiple blrec files.

The 3CX logs rotate when they reach 50MB. If the Keep Backup option (in 3CX Management Console > Settings > Advanced > Logging level) is disabled, two blrec log files are kept – the current one and the previous one. If the Keep Backup setting is enabled, the older files will be  moved to the backup folder. There is an option to keep backup of log files for X number of days. This affects the how many 3CX Logs are kept in the backup.

Note that the 3CX Server Logs are the logs which are written by the 3CX Phone System Service. Other processes, such as the 3CX PhoneSystem Media Server, write logs in .log format, and can be viewed with a text editor.

Useful Tags

This list will help you understand and start using log tags (not all tags are listed):

  • CallId: Each call is assigned a Call ID by the PBX. The CallId tag allows you to filter by the logging that matches the selected CallId.
  • Cause.Code: The Cause.Code shows all the SIP cause codes found in the log. Therefore, if for example you are troubleshooting a situation whereby a call is returning a busy tone, you can filter for Cause.Code = 486
  • Contact.Host: The Contact.Host allows you filter for a specific IP address as listed in the SIP header.
  • DestAddr.Host and SrcAddr.Host: Useful when filtering on the destination/source address. Note that this is the network address, not the one specified in the SIP header.
  • DN: This is the extension number of the phone or device (virtual extension number). Use this tag to filter the logging from a particular extension or port on a device.
  • InboundDID: This might come in useful when you want to filter the logging for a specific DID number.
  • SipMsg.Method: This is useful to filter the logging and show a specific SIP message. For example, you might want to show only the REGISTER SIP methods in the log file. This is useful to get you started – maybe you want to find when a registration took place so you can then filter the logging by date. Remember to check the other SipMsg.X tags

Liked this article?


Get notified of new articles
or share
You might also be interested in:
  1. Tom

    That’s extremely useful!
    Great work, thank you very much!

    September 13, 2012 at 7:06 pm
  2. Stuart

    Looks good, however when looking at available updates in the Other Updates section I do not see the 3CX Log Viewer as an option. Is it available in version 10.0.24018?

    September 14, 2012 at 2:41 pm
  3. Nicholas Sciberras

    Hi Stuart,

    The 3CX Log Viewer is only available for version 11.

    September 14, 2012 at 2:42 pm
  4. toddy

    well done, guys

    thank you for that powerful tool

    /toddy

    September 14, 2012 at 11:07 pm
  5. Bruce G. Kreeger

    This is a great tool and we started to use it once it became available. Most of our clients are already on Version 11 SP-1. As usual, great job 3CX Team!

    September 14, 2012 at 7:18 pm
  6. Billy Dodson

    Nice tool. This will be helpful for sure.

    September 23, 2012 at 7:25 am