Analyse SIP Communications with 3CX Log Viewer

Introduction

The 3CX Bin 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 Bin Log Viewer can be downloaded and installed directly from the 3CX Admin Console.

You can download the Bin Log Viewer directly from here: 3CX Bin Log Viewer V15

3CX Bin Log Viewer Overview

The first time you load the 3CX Log Viewer, click on File > Open and navigate to the location where 3CX logs are stored. The Bin Log Viewer shall not be used directly on the 3CX host to avoid performance implications with the live system. Generate a support bundle from the 3CX Management Console and download it to your PC where the Bin Log Viewer is running. Extract the ZIP file and within the /Logs folder you will find a file named “3CXPhoneSystem.bldef”.

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

Filtering Options

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

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:

The Formula text gets updated as you add and remove tags. Copy 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

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 holding down the Shift or Control key. The above screenshot shows log entries for Extension 100 being highlighted.

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 1 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.

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 settings are retained when you close the 3CX Log Viewer.

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 “View → 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 (Dashboard) → Activity Log → Settings”) 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 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 SIP Server service. Other processes, such as the 3CX Phone System Media Server service, 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 to 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

Last Updated

This document was last updated on 15 November 2019

https://www.3cx.com/docs/3cx-log-viewer/