Advanced Information
- Nathaniel Halbrooks
- Kelli Higdon
- 1 Making Sense of the Configuration Files
- 2 Making Sense of the Log Files
Making Sense of the Configuration Files
By default, all configuration files are found at the file paths below:
(Windows) C:\Program Files (x86)\Sangoma NetBorder Platform 2.0.3\config
(Linux) /opt/Sangoma_NetBorderCallAnalyzer/config
At first glance it is not intuitive exactly what settings are found in each configuration file, but once you understand the logic behind the setup it is easy to remember what settings are contained in each file.
license.txt & license.txt.sig
These files are fairly self-explanatory. The “license.txt” file contains a human readable version of the currently installed license, which includes information such as the MAC Address and number of channels purchased. The “license.txt.sig” file is an encoded version of the human readable file which is what NCA checks against when limiting services to exactly what the customer has purchased.
call-analyzer-service.properties
This file can be thought of as the “main” configuration file. This file defines general settings about NCA as a whole, such as what sockets we are listening on, and what to do in case of a crash.
The most important settings are on lines 5 and 16, which will define the port we are listening for SIP messages on, and what “mode” NCA is operating as. There are completely separate configuration files for both of the possible modes.
Line 5: netborder.sip.userAgent.IPAddress=INADDR_ANY:5062/udp
Line 16:
CallAnalyzerAsOutboundProxy.call-properties & CallAnalyzerGenesysOCS.call-properties
Depending on which mode you configure in “call-analyzer-service.properties” one of these two files will be parsed, and their configurations applied. NCA will never apply the configuration from both of these files. These can be considered the configuration files for how we handle SIP messages.
These files contain settings specific to each operation mode, as well as partly configuring how we communicate with the RTP manager by defining the socket the two parts of NCA expect to be communicating on, as well as the thresholds used by the RTP manager.
call-analyzer-engine.properties
This file can be thought of as the main configuration file for the RTP manager and contains all of the same types of configuration options as “call-analyzer-service.properties”.
The most important setting in this file is found on line line 22, and will toggle “call recording”. When enabled, NCA will record the audio being analyzed to .wav files, so that a human can listen to the exact audio-stream that NCA analyzed. Enabling call recording is extremely useful for debugging most NCA issues.
call-analyzer-logging.properties & call-analyzer-engine-logging.properties
These two files define what level of SIP and RTP logging NCA will use, and where to store this information. Unlike enabling call-recording, increasing the logging in these two files is essential to debugging NCA issues.
The screenshot below is from “call-analyzer-loging.properties”, but the lines in question appear in both files. The lines to pay attention to are lines 14 and line 19 (12 and 17 in engine-logging). One line of these two lines should always be commented out, and the other should always be un-commented, and they define what level of logging will be enabled when NCA starts. If both are un-commented, only the second will be applied.
Configuring Logging Overrides
log4cplus.logger.netborder.sip.messages=INFO
log4cplus.logger.netborder.cpa=INFO
(log4cplus.logger.netborder.sip-hub=INFO)
These lines can be seen in the above file on lines 7 and 8. These override the root logger settings and can increase the logging for a specific area of NCA. Adding all the overrides would be equivalent to changing the first entry in the root logger line in both logging.properties files.
Configuring Logging Levels
There are six logging levels, as follows (taken from the NBE user guide “Loggers Configuration” :
FATAL: Logs very severe error events that may lead the application to abort.
ERROR: Logs only error conditions. The ERROR level provides the smallest amount of logging information.
WARN: Logs information when an operation completes successfully but there are issues with the operation.
INFO: Logs information about workflow. It generally explains how an operation occurs.
DEBUG: Logs all of the details related to a specific operation. This is the highest level of logging.
TRACE: Logs designated finer-grained informational events than DEBUG.
Making Sense of the Log Files
By default, all log files are found at the filepaths below:
(Windows) C:\Program Files (x86)\Sangoma NetBorder Platform 2.0.3\logs
(Linux) /opt/Sangoma_NetBorderCallAnalyzer/logs
Per Call Files
One of the great benefits of NCA is that when call-logging is turned on, not only is all information stored chronologically in a master log file, there are logs created for each and every call. This is extremely beneficial as NCA is designed specifically for high-call-volume installs, and trying to follow the SIP messages for a single call when there are +1000 calls made in an hour is very difficult.
When call-logging is enabled, there are three files that will be generated per call, located in the directory “call-logs” and organized per year/month/day/hour. In addition, if you turn on call-recording, a fourth .wav file will be made for each call:
[NBE-Call-ID].log
[NBE-Call-ID].analyzer-engine.log
[NBE-Call-ID].analyzer-engine.cdr.xml
[NBE-Call-ID].analyzer-engine.0.0.wav
[NBE-Call-ID].log
This file will contain all of the SIP messages sent and received by NCA. This file is extremely useful when encountering the following scenarios:
The call attempt fails, and the dialer is returned a 3XX, 4XX, 5XX or 6XX message in response to the invite request from the Dialer
You have already identified that there is an issue with the audio with a specific call, and you are trying to discover if it is a configuration issue
When working on an issue reported by the customer as “XXXX call had an issue with it” this file is the place to start once you know the NBE Call-ID of the call.
If you are looking for specific examples of calls, please consult the NCA users guide found in the /doc folder of an NCA install starting on page 104.
[NBE-Call-ID].analyzer-engine.log
This file contains the SIP and RTP logs seen by the RTP handler. All of the SIP messages should come on the local-loopback from NCA itself, and other than the initial INVITE and the final BYE, the only other SIP message that should be received is an INFO message sent to indicate that NCA has received a 200 OK from the remote party, and we need to switch from pre-connect analysis to post-connect analysis.
In addition to the SIP messages, this file contains log messages related to the analysis of the RTP packets we receive. This file is extremely useful for:
Isolating the exact audio issue that NCA is experiencing (jitterbuffer issues, receiving no-audio, receiving RTP packets from multiple sources, etc.)
Analyses on calls that customers believe return an incorrect disposition. A “live” CPD Result Certainty will be printed throughout the log, so you can easily see when/why the final analysis was detected.
You will need to have DEBUG or TRACE level logging in order to see this information
Is much more useful when combined with the audio recording.
[NBE-Call-ID].analyzer-engine.cdr.xml
It matches the cdr.xml file in the /log directory. This file is very useful in combination with the .wav file generated, as it gives you the exact timestamps related to the important SIP messages with respect to the beginning of the audio-recording, so you can match up when messages came in to NCA to the exact audio we are seeing at that time.
This is extremely useful when customers are complaining about inconsistent/low accuracy.
[NBE-Call-ID].analyzer-engine.0.0.wav
This is a human-listenable file of the exact audio that NCA analyzes. Almost every issue can be found through careful analysis of this file, and is one of the only ways to really make sense of issues. More often than not, the issue is not with signalling or configuration, and has to deal with specifics dealing with the RTP and the way NCA analyzes the RTP.
In general, the audio files will have clues as to what issues are on the line, then this can be confirmed by looking through the other logs. Suspicious logs that look like there are issues can be confirmed by listening to the audio for that call. Without both logs and recordings, it is almost impossible to be confident of an analysis of an issue.
cpa-stats.csv
This file contains a detailed record of all call attempts made through NCA. The important thing to note here is that it logs the exact time that NCA starts the outbound dialing attempt, and should be used when looking for statistics such as "How long does it take for NCA to analyze a call?" and "How much time does it take for NCA to analyze the audio and connect the call to an agent?". The start times will vary between NCA and the Dialer due to the delay in transmitting/receiving sip messages between the two.
call-analyzer-engine.out
This file logs information equivalent to what can be found in [NBE-Call-ID].analyzer-engine.log, but in a purely chronological format. It also includes generic error and warning messages related to the process managing the RTP which would not show up in the per-call logs. Logs will be written to this fie in "production" mode. This file
call-analyzer-service.out
Like call-analyzer-engine.out, his file logs information equivalent to what can be found in [NBE-Call-ID].log in a chronological format, and contains error messages related to the process managing SIP messages, and will only be written to in "production" mode by default.