Error and diagnostic logging

Vocalizer logs error messages and optionally can be configured to report diagnostic information as well.

Vocalizer also writes call-log information to report TTS engine statistics, which can be used for application tuning and capacity planning. See Application call logs for details.

Also see Minimizing latency for suggestions on how to optimize performance and minimize latency.

At runtime Vocalizer logs error messages for problems encountered by the TTS engine. Although Vocalizer returns error codes that give a high-level indication of the type of failure, it is important to monitor the error logs. The error logs provide detailed information about the errors returned so they can be quickly resolved (such as the specific URI, line, and column containing a SSML parse error). Also, check the error logs for warnings about application problems that don’t trigger a fatal error, but that may lead to unexpected behavior that needs correction (perhaps with as an SSML say-as type that is not supported).

Vocalizer can optionally be configured to report diagnostic information as well. If you file a support incident with Nuance Technical Support, they may ask you to enable diagnostic logging so Nuance can analyze and resolve your issue.

These error and diagnostic logs are written to the following destinations:

Speech Server (only) and Nuance Management Station. If not using Management Station, set in the NSS configuration file.
(Optional, disabled by default) Operating system’s System logging: Windows Application Log or Unix syslog.
(Optional, disabled by default) Vocalizer written log files and diagnostic log files.

The verbosity of the diagnostic logs is controlled by the log_level parameter in the Vocalizer configuration file.

Vocalizer written log files

Vocalizer-written log files are disabled by default, but can be enabled via the log_file_enabled parameter in the Vocalizer configuration file. When enabled, the logs are written to ${TMPDIR}/nvn-${USER}-log.xml , where ${TMPDIR} is your temporary files directory (typically /tmp on Linux and the directory indicated by the user environment variable %TEMP% on Windows).

Note: You must explicitly set TMPDIR on Linux, either in the Vocalizer configuration file or as an environment variable.

Vocalizer starts logging to one of those files, then when it gets to a configurable size, it “rolls over” to the second file, erasing any content already there. The filename is ${TMPDIR}/nvn-${USER}-bck001-log.xml This two-file rollover system prevents filling up the disk. The storage location, filename, and maximum log file size are configurable by log_file_[…] parameters in the Vocalizer configuration file.

The log file is written in an XML format. It starts with the usual XML declaration, includes a comment to indicate this is a Vocalizer written log file, then provides an internal DTD that describes the file format. The actual log messages appear within an <xml_log> root element, with <error>, <entry>, and <event> elements (one per line) that report the log messages.

<error> reports an error message, warning message, or informational message.
<entry> reports a diagnostic message. These are only present when diagnostic logging is enabled (log_level is set to 2 or more in the Vocalizer configuration file). Because diagnostic logging can significantly affect performance, it is disabled by default and only enabled when requested by Nuance Technical Support.
<event> reports an application event message (described in Application call logs). These are only present when diagnostic logging is enabled (log_level is set to 5 or more in the Vocalizer configuration file); they are disabled by default. Use the separate application call log file to obtain call logs. (This redundant information is only included for Nuance support purposes.)

Note: The root <xml_log> element only gets closed (</xml_log>) when the log file is closed after a rollover, or when Vocalizer is shut down normally. If you wish to parse the log files using an XML parser, make sure the parser can tolerate an unclosed <xml_log>, or make sure you look for the </xml_log> and append it in-memory when necessary, before calling the XML parser.

The log entries are composed of XML elements within the <error>, <entry>, and <event> elements. The names are kept short to minimize log file disk space use.

Element	Description
t	Timestamp
mi	Vocalizer module ID number
mn	Vocalizer module name
mv	Vocalizer module version number
thr	Operating system thread ID
id	Vocalizer instance ID number (hexadecimal)
sid	Session identifier
s	<error> elements only: the error severity CRITICAL (critical error that affects all engine instances) SEVERE (severe error that affects one engine instance) WARNING (non-fatal application error) INFO (informational notice like the list of installed voices at startup)
eid	<error> elements only: the error ID number, corresponding to the "num" field in VOCALIZER_SDK\doc\VocalizerLogStrings.enu.xml
l	<entry> elements only: log_level value where that message starts appearing
evt	<event> elements only: the event ID number
tm	Text message: the error description (corresponding to the <error> content in VOCALIZER_SDK\doc\VocalizerLogStrings.enu.xml), diagnostic message, or event name
mp	<error> and <events> elements only: message pair that further describes the event or error, where the "key" attribute gives the name of a variable and the content of the element gives the value of the variable. For example, a key of "URI" with a value of "http://myserver/input.ssml" could be used to indicate a specific URI that triggered the error.
bl	<entry> elements only: label for a logged block of binary data, rarely used
bs	<entry> elements only: size of a logged block of binary data, rarely used
bm	<entry> elements only: base 64 encoded logged block of binary data, rarely used

Suppressing confidential data

Vocalizer has features to protect sensitive data from being written to logs. The system protects any data defined as confidential. Typically, this means confidential personal data: names, addresses, telephone numbers, account numbers, passwords, and so on.

With regards to logging, you can protect confidential data as follows:

Control the logging data flow. The system stops writing log data.
Suppress data. The system avoids writing specific strings.
Mask data. The system replaces confidential text strings in logs with masked text. When masking text in a call log, the system writes the SECURE token (SECURE=true), and replaces the encrypted data with the string "_SUPPRESSED."

To suppress logging confidential data to the error and diagnostic logs, you can use switts.secure_context property to set a secure context which only affects the current speak request.

You can also set "secure_context" via an SSML <meta> element . For example:

<meta name="secure_context" content="mask-sensitive"/>

For Vocalizer-written log files (disabled by default), whenever secure_context is set to any mode except "open" for system-prompts, Vocalizer suppresses writing potentially confidential data. For the Nuance Watcher integration, Vocalizer uses the same encryption mechanism as Speech Server. For a complete overview of features and details for managing confidential data, see Protecting confidential data.

Error and diagnostic logging

Suppressing confidential data

Related topics