User Guide for Cisco Unified CVP VXML Server and Cisco Unified Call Studio Release 12.6(1)
Bias-Free Language
The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
Logging plays an
important part in voice application development, maintenance, and improvement.
During development, logs help identify and describe errors and problems with
the system. Voice applications relying heavily on speech recognition require
frequent tuning in order to maximize recognition effectiveness. Voice
application design may also be changed often, taking into account the behaviors
of callers over time. The more information an application designer has about
how callers interact with the voice application, the more that can be done to
modify the application to help callers perform their tasks faster and easier.
For example, a
developer could determine the most popular part of the voice application and
make that easier to reach for callers. If a large proportion of callers ask for
help in a certain part of the application, the prompt might need to be
rewritten to be clearer. After analyzing the declaration of various callers,
the effectiveness of grammars can be determined so that additional words or
phrases can be added or removed. None of this is possible without detailed logs
of caller behavior. While each component of a complete VRU system, such as the
voice browser and speech recognition system provide their own logs, VXML Server
provides logs that combine all this information with the application logic.
This chapter explains the details of logging on VXML Server.
Because of the
importance of logging, VXML Server has been designed to offer the maximum
flexibility with regards to what can be logged, how it is logged, and where it
is logged. The logs generated by VXML Server by default can be customized to
fit the needs of a deployment. In addition, a Java API exists that allows
developers to create their own ways of handling logging for better integration
with the deployed environment or tailored specifically for special needs.
Loggers
VXML Server handles all logging activity through the use of loggers. Loggers are plug-ins to VXML Server that listen for certain
logging events and handle them in a custom manner, from storing the information in log files, sending the information to a
database, or even to interface with a reporting system. Any number of loggers can be used, even multiple instances of the
same logger. A logger may or may not require a configuration that will allow the designer to customize how the logger performs.
VXML Server comes with several loggers that provide all necessary information in text log files. Some provide configurations
to allow for a level of customization in how the loggers perform. VXML Server exposes a Java API to allow developers the flexibility
of creating their own loggers to allow for even more customization. See the Programming Guide for Cisco
Unified CVP VXML Server and Cisco Unified Call Studio for detailed information on how to build custom loggers.
VXML Server communicates with loggers by triggering logging events that the loggers listen for and then deal with. VXML Server
activates loggers in a fully multithreaded environment to maximize performance.
Loggers are divided into two categories: global loggers and application loggers. Global loggers are activated by logging events
that apply to VXML Server as a whole and that is not directly related to any particular application (for example, a record
of all calls made to the VXML Server instance). Application loggers are activated by logging events that apply to a particular
application running on VXML Server (for example, a call visiting an element). Each logger type is constructed using separate
Java APIs and deals with a separate list of possible logging events . Each logger type is also given a separate area to store
logs, although a logger may choose to ignore this area if it does not log to files.
Global Loggers
The global_config.xml file found in the conf directory of %CVP_HOME%\VXMLServer is used to define the global loggers VXML Server is to use. The administrator can define any number of global loggers to
be simultaneously active, even multiple instances of the same logger class. This file also lists the names of the configuration
files for these loggers, if they are configurable. The configuration files must be placed in the same conf directory as the
global_config.xml file. The global_config.xml file and any configuration files must be edited by hand, there is no interface for editing them. Refer to VXML Server Configuration for more details about this file and how to define global loggers within it.
Global loggers are loaded by VXML Server when it starts up and remain in memory until it is shut down. Any change made to
the global_config.xml file is not loaded until VXML Server is restarted.
VXML Server provides the logs folder of %CVP_HOME%\VXMLServer for log file storage if the Global Loggers require it. To keep each logger instance’s logs separate, a subfolder with the
name of the logger instance is created, and all logs generated by the logger instance are stored there.
By default, VXML Server utilizes three loggers to create text log files containing VXML Server-specific information: a log
that keeps track of calls made to the system, a log for tracking VXML Server administration activity, and an log that shows
errors that occur on the VXML Server level (as opposed to the application level). The global error logger requires a configuration
that allows for detailed control over how the logger operates.
The following sections describe these three prebuilt global loggers, their configurations (if any), and the information stored
in their logs.
Global Call Logger
The global call logger records a single line for every application visit handled by VXML Server into a text call log. Most
calls will begin and end in a single application so in that case a line in the call log is equivalent to a physical phone
call. For situations where one application performs an application transfer to another application, a separate line will be
added to the call log for each application visit despite the fact that they all occur in the same physical call. Because each
application visit is logged separately in each application’s own log file, the call log provides a way to stitch together
a call session that spans multiple applications.
The call log file names are in the format call_logYYYY-MM-DD.txt where YYYY, MM, and DD are the year, month, and day when the call log was first created. By default, the log folder for is named GlobalCallLogger (though the name is set in the global_config.xml file and can be changed by the administrator). Call log files are rotated daily. The file is organized in a comma-delimited
format with 6 columns:
CallID—This is a nonrepeating value generated by VXML Server to uniquely identify calls. It is designed to be unique even across
machines, because the log files of multiple machines running the same applications may be combined for analyses. The format
of the session ID is IP.SECS.INCR where IP is the IP address of the VXML Server instance on which the call originated, SECS
is a large integer number representing the time the application visit was made and INCR is an automatically incremented number
managed by VXML Server. Each part is delimited by dots and contains no spaces. For example: 192.168.1.100.1024931901079.1.
Note
If a voice application uses a Subdialog Invoke element to transfer across multiple VXML Server instances, the IP address included
in the CallID is the IP address of the instance the call started on. Because of this, it is possible that a CallID in log
files on one machine may contain an IP address for another machine. This allows a physical call to be traced across multiple
servers (from a logging standpoint), even if Subdialog Invoke is used to transfer to between various voice applications.
SessionID—The session ID is used to track a visit to a specific application. Therefore, with application transfers, one call ID may
be associated with multiple session IDs. For this reason, session IDs are basically the call ID with the application name
appended to the end. For example: 192.168.1.100.1024931901079.1.MyApp.
callers—This integer represents the total number of callers interacting with the system at the time the call was received (excluding
the current call).
order—A number indicating the order of each application visited in a call. The order begins at 1. This column exists to report
the order in which a caller visited each application should the data be imported to a database.
Application—The name of the application visited.
Time—A timestamp of the application visit in the format MM/DD/YYYY HH:MM:SS.MMM where the hour is in 24-hour time and MMM represents a 3-digit millisecond value. This represents when the call was received or the application transfer occurred.
Global Error Logger
The Global Error Logger records errors that occur outside the realm of a particular application. Application-level errors
are logged by application-level loggers, which are described later in this chapter. Another type of error that the Global
Error Logger receives is an application-level error that encountered trouble with its logging. In order to prevent the loss
of the data, VXML Server activates a global logger event with the original application error as a backup.
The error log file names are in the form error_logYYYY-MM-DD.txt where YYYY, MM, and DD are the year, month, and day when the error log was first created. By default, the log folder is named
GlobalErrorLogger (though the name is set in the global_config.xml file and can be changed by the administrator). Global error log files are rotated daily.
Note
If no error occurred on a particular day, no error log is created.
The file is organized in a comma-delimited format with 2 columns:
Time—The time the error occurred.
Description—The error description. One possible value can be max_ports, indicating the caller was put on hold because all the Unified CVP license ports were taken. While the call was eventually
handled correctly, this is placed here as a notice that the license may not have enough Unified CVP ports to match caller
volume. Another value is bad_url:[URL], indicating that a request was made to VXML Server for a URL that could not be recognized. This most likely will occur if
the voice browser refers to an application that does not exist. The last description is error, indicating that some other
error occurred.
Note
The global error log is not designed to be parsed, even though the columns are separated with commas. This is because when
the error log reports a Java-related error, it may include what is called a Java stack trace, which contains multiple lines of output.
The Global Error Logger utilizes a configuration to control how it logs certain types of errors and how often the log files
should be purged. The configuration is specified as an XML file created by the designer and placed in the conf directory of %CVP_HOME%\VXMLServer.
The Global Error Log Configuration diagram displays the format for the XML Global Error Logger configuration file. The main tag for the configuration, configuration, has two attributes, name and version. Name is expected to contain the logger instance name. The version is expected to include the version of the configuration, which is currently 1.0. The subsequent sections describe the functionality of the various tags in the configuration.
Global Error Logger Configuration: Log Details
The <log_details> tag controls which errors to log and what information to include about those errors. The possible child tags are:
<stacktraces>—Indicates that any Java errors that occur should also have their stack traces printed in the log. The absence of this tag
indicates not to include stack traces.
<on_hold_calls>—Indicates that a call that was put on hold should be logged. The application_name attribute can have the values true and false, true being to include the name of the application the caller attempted to reach when being put on hold and false to not include the application name.
<http_parameters>—Indicates that an error caused by an unrecognized URL (such as a request for an application that does not exist) should include
the HTTP parameters passed to the URL. This tag can be helpful to know since it could help determine why the request was made.
The length attribute provides a limit, in a number of characters, to be included in the log. This prevents the log from being filled
up with too much parameter data.
Note
The parameter data appears on one line, no matter how long.
<http_headers>—Indicates that an error caused by an unrecognized URL (such as a request for an application that does not exist) should include
the HTTP headers passed to the URL. This can be helpful to know since it could help determine why the request was made. The
length attribute provides a limit, in a number of characters, to be included in the log. This tag prevents the log from being filled
up with too much header data.
Note
The header data appears on one line, no matter how long.
<http_session_data>—Helps debug situations where the VXML Server receives HTTP requests that it does not expect or understand. When this tag
is used, the JSession ID (if known) and its association with the VXML Server Call ID (if known) are displayed in the global
error logger. This tag is helpful in debugging bad_url errors. Bad_url errors are generally displayed when the VXML Server receives a HTTP request that cannot be recognized. Use of this option
increases the amount of memory used by the VXML Server. Use this feature only for debugging situations.
Global Error Logger Configuration: File Purging
The Global Error Logger can be configured to automatically delete files that conform to certain criteria. Properly configured,
this allows an administrator to avoid having the system’s hard drive fill up with logs, which would prevent new calls from
being logged.
Note the following information about file purging:
Because loggers are activated only when events occur in a call, the file-purging activity only takes place when an error event
occurs. As a result, a system that encounters no errors will not automatically delete files until a new error occurs.
When the Global Error Logger starts up for the first time, it applies the purging strategy on any files that exist in the
logger directory. Therefore, if an application server is shut down with files in the logger directory and then restarted a
long time later, these files might be deleted when the application server starts up and the logger initializes.
The Global Error Logger applies its purging strategy to any files found in its logger directory, including non-error log files.
Other files added to the logger folder after the application server has started could be deleted when the Error Logger encounters
a new error.
The optional <purge> tag defines the purging strategy. If this tag does not appear in the configuration, no file purging will take place. The
tag can contain one of the following child tags:
file_age—The Global Error Logger will delete error log files older than X days, where X is an integer greater than 0 specified in the older_than attribute.
file_count—The Global Error Logger will delete error log files if the logger folder contains greater than X files, where X is an integer greater than 0 specified in the greater_than attribute. When the files are deleted, the oldest ones are deleted first until the folder reaches the desired file count.
Because stack traces span multiple lines, including stack traces may complicate the process of importing the error logs into
spreadsheets or databases. This is rarely done for error logs.
If there is a bad URL error message, it will include 100 characters of the URL input parameters and 300 characters of the
HTTP headers, all on one line in the log file.
Nothing is logged for a call that is put on hold.
When a new file is added to logger instance’s dedicated directory by the Global Error Logger, if the directory contains files
that are older than 14 days (2 weeks), the files will be deleted.
Java stack traces will not appear in the error logs. When a Java exception occurs, only the error message itself will appear
in the error log without the stack trace.
When a call is put on hold, that fact will be logged along with the application name that the caller was attempting to visit.
If there is a bad URL error message, only the URL itself will be logged without any HTTP parameters or headers.
No file purging will take place. The administrator is responsible for maintaining the logs on the system.
Global Administration History Logger
The Global Administration History Logger records administration events that occur on VXML Server itself. Application-level
administration history is logged by application-level loggers, which are described later in this chapter. These events are
triggered by an administrator running administration script (see Administration for more on administering VXML Server).
The administration log file names begin with admin_historyYYYY-MM-DD.txt where YYYY, MM, and DD are the year, month, and day when the administration log was first created. By default, the log folder
is named GlobalAdminLogger (though the name is set in the global_config.xml file and can be changed by the administrator). Administration history log files are rotated daily.
Note
If no administration activity occurred on a particular day, no administration history log will be created.
The file contains three columns: the time, what script was run, and its result, separated by commas. The result is usually
success and if not, contains the description of the error encountered. The possible values of the result are:
server_start—Listed when the VXML Server web application archive initializes. This occurs if the Java application server on which VXML
Server is installed starts up or the administrator of the application server explicitly started up the VXML Server web application
archive.
server_stop—Listed when the VXML Server web application archive is stopped. This occurs if the Java application server on which VXML
Server is installed shuts down or the administrator of the application server explicitly stops the VXML Server web application
archive.
deploy_all_new_apps—Listed when the deployAllNewApps script is run.
flush_all_old_apps—Listed when the flushAllOldApps script is run.
suspend_server—Listed when the suspendServer script is run.
resume_server—Listed when the resumeServer script is run.
update_common_classes—Listed when the updateCommonClasses script is run.
Note
Running the status script does not trigger an administration event and thus does not update the history log.
Application Loggers
Application loggers are defined in the settings for that application. The application designer can choose any number of application
loggers they want to listen to events for a particular application, giving each instance a name. A logger may or may not require
a configuration that will allow the designer to customize how the logger performs. The configuration files must be placed
in the data/application directory of the deployed application.
Unique to application loggers is the ability for one to specify that all logging events for a call be passed to the logger
it in the order in which they occurred in the call. Some application loggers may even require this functionality to be turned
on as their functionality depends on the events arriving in order. The application designer can choose to ensure this functionality
is the case even for application loggers that do not explicitly require it to have logs appear orderly. There is some performance
degradation as a result of this functionality so an application logger that does not require this should not enable it.
VXML Server provides the logs folder of a particular application for log file storage should the loggers require it. To keep each application logger instance’s
logs separate, a subfolder with the name of the instance is created and all logs created by the logger instance are stored
there.
By default, VXML Server includes four loggers that provide various application-specific information: an activity logger that
records caller behavior, an application administration history logger that records administration activities, an error logger
that lists errors that occur within calls to the application, and a debug logger that provides additional information useful
when creating and debugging a new application. The activity logger and error logger require configurations that allow for
detailed control over how the loggers operate.
The following sections describe these four prebuilt application loggers, their configurations (if any), and the information
stored in their logs.
Application Activity Logger
The Activity Logger is the main application logger included with VXML Server. It records into text log files all of the activity
taken by callers when they visit an application. It stores information about the call itself such as its ANI, what elements
the caller encountered and in what order, and even detailed actions such as the values entered by the caller or the confidences
of their declaration. The names of the log files created by the Activity Logger begin with activity_log and are delimited for easy importing into spreadsheets and databases. These logs have a fixed number of columns:
SessionID—The session ID of the application visit as described in the VXML Server Call Log section.
Time—A timestamp of the event in a readable format.
[Element name]—The name of the current element the activity belongs to. Only functional elements (voice elements, action elements, decision
elements, and insert elements) can appear here. This column would be empty if the activity does not apply to an element.
Category—The category of the action:
start—Information on new visits to the application.
end—Information on how the application visit ended.
element—Information on the element visited and how the element was exited. The element column is empty for the start and end categories.
interaction—Detailed information about what a caller did within a voice element.
data—Element data to be logged.
custom—Custom developer-specified data to log.
Action—A keyword indicating the action taken. A list of actions is given in the following table.
Description—Some qualifier or description of the action.
The following table lists all of possible category and actions that can appear in the activity log and descriptions on what
they represent.
Category
Action
Description
start
newcall or source
newcall is used when the application visit is a new call. The description is empty. source is used when another application transferred to this application. The name of the application transferred from is listed
in the description.
start
ani
The description is the ANI of the caller. NA if the ANI is not sent.
start
areacode
The area code of the ANI. NA if the ANI is not sent.
start
exchange
The exchange of the ANI. NA if the ANI is not sent.
start
dnis
The description is the DNIS of the call. NA if the DNIS is not sent.
start
iidigits
The description is the IIDIGITS of the call. NA if the IIDIGITS is not sent.
start
uui
The description is the UUI of the call. NA if the UUI is not sent.
start
uid
The application visit is associated with a user. The UID is listed in the description.
start
parameter
An HTTP parameter attached to the initial URL that starts a Unified CVP application. The description lists the parameter name
followed by an "=" followed by the value. A separate line will appear for each parameter passed.
start
error
An error occurred in the on-call start action (either a Java class or XML-over-HTTP). The description is the error message.
end
how
How the call ended. The description is either hangup to indicate the caller hung up, disconnect to indicate the system hung up on the caller, application_transfer:APPNAME to indicate a transfer to another Unified CVP application occurred (where APPNAME stands for the name of the destination
application), call_transfer to indicate a telephony blind transfer occurred, or app_session_complete to indicate that the call session ended by another means such as a timeout or the call being sent to an VRU system outside
of Unified CVP.
end
result
The description explains why the call ended. normal indicates the call ended ordinarily, suspended indicates the application is suspended, error indicates an error occurred, timeout indicates that the VXML Server session timed out, and invalidated indicates the application itself invalidated the session.
end
duration
The duration of the call, in seconds.
end
error
An error occurred in the on call end action (either a Java class or XML-over-HTTP). The description is the error message.
element
enter
The element was entered. The description is empty. This is always the first action for an element.
element
hotlink
A hotlink was activated while in the element. This can be either a global or local hotlink. The description lists the hotlink
name.
element
hotevent
A hotevent was activated while in the element. The description lists the hotevent name.
element
error
An error occurred while in the element. The description lists the error message.
element
flag
A flag was triggered. The description lists the flag name.
element
exit
The element was exited. The description lists the exit state of the element or is empty if a hotlink, hotevent or error occurred
within the element.
interaction
audio_group
An audio group was played to the caller. The description is the audio group name.
interaction
inputmode
How the caller entered data. The description can be dtmf or speech.
interaction
utterance
The caller said something that was matched by the speech recognition engine. The description lists the match it made of the
utterance. This action will always appear with the interpretation and confidence actions.
interaction
interpretation
In a grammar, each utterance is mapped to a certain interpretation value. The description holds the interpretation value for
the caller’s utterance. This action will always appear with the utterance and confidence actions.
interaction
confidence
The confidence of the caller's matched utterance. This is a decimal value from 0.0 to 1.0. DTMF entries will always have a
confidence of 1.0. This action will always appear with the utterance and interpretation actions.
interaction
nomatch
The caller said something that did not match anything in the grammar.
interaction
noinput
The caller did not say anything after a certain time period.
data
[NAME]
When an element creates element data, one can specify if to log the element data. Element data slated to be logged will appear
here with the element data name as the action and the value as the description.
custom
[NAME]
Anywhere the developer adds custom name/value information to the log will have the name appear as the action and the value
stored within as the description.
Note the following guidelines about the Activity Logger:
Due to its complexity, the Activity Logger requires that the enforce call event order option to be set for the logger instance
using it and will throw an error if it is not set.
When one Unified CVP application performs an application transfer to another application, the reported timestamps of the end category of the source application and the start category of the destination application could be imprecise when the source application ends with the playing of audio content.
This is due to the fact that voice browsers typically request VoiceXML pages in advance if the current page contains only
audio and a submit to the next page. In other words, the browser could be playing audio to the caller while making a request
for the next VoiceXML page. If that page were the last of an application, the subsequent request would begin the process of
entering the new application including having the Activity Logger handle start and end of call logging for the two applications.
It would then report the end time for the source application as being before the time the caller actually experienced the destination application by hearing its audio.
The Activity Logger utilizes a configuration to control the finer details of the information it stores in its log files. The
configuration controls five different aspects of the Activity Logger:
Format of the files
How much data to store in them
How often to rotate the files
How caching should work
How often should log files be purged
This configuration is specified as an XML file created by the designer in Builder for Call Studio. The following figure shows
the format for the XML Activity Logger configuration file.
The main tag for the configuration, configuration, has two attributes, name and version. Name is expected to contain the logger instance name although can be given any name desired. The version is expected to include the version of the configuration, which is currently 1.0. The subsequent sections describe the functionality of the various tags in the configuration.
Activity Logger Configuration: Format
The <format> tag allows for the modification of how the activity log files are formatted. All Activity Logger configurations are required
to define a format. The possible attributes are:
delimiter—This required attribute defines the delimiter to use to separate columns on a line. Delimiters can be any string value, though
typically will be a comma or tab. To use a special white space character such as a new line or tab, use the escaped version.
The possible values are:
\n (denoting a new line)
\t (denoting a tab)
\r (denoting a return)
\f (denoting a line feed)
remove_delimiter_from_content—When this required attribute is set to true, the Activity Logger attempts to eliminate the delimiter from any content appearing in the logs to ensure that the log file
can be imported flawlessly. For example, if the delimiter is a comma and the configuration is set to remove the delimiter,
when it is to log the content This, is the description, it will appear in the log as This is the description so that it does not affect the accuracy of the importing process. This extra step, though, does incur a slight performance
hit. This step will not be performed if this attribute is set to false.
end_of_line—This optional attribute controls the delimiter used to separate lines. When this optional attribute is set to true, the Activity Logger will separate lines appropriate to the operating system on which VXML Server is running. Set the attribute
to explicitly set the new line delimiter. Delimiters can be any string value, though typically will be a white space character.
To use a special white space character such as a new line or tab, use the escaped version.
The possible values are:
\n (denoting a new line)
\t (denoting a tab)
\r (denoting a return)
\f (denoting a line feed)
date_format and date_granularity—These required attributes set how the second column of the activity log references a date when the event occurred. The format
and granularity are specified.
There are three possible values for the date_format attribute:
standard—This is a standard readable date format in the form MM/DD/YYYY HH:MM[:SS][.MMM] where the hour is in 24-hour time and the last three digits are the milliseconds. The seconds and milliseconds are displayed
with brackets to indicate that their appearance is based on the date_granularity attribute. For a date_granularity attribute set to minutes, just the hours and minutes of the time will be displayed. For a granularity set to seconds, just the hours, minutes and seconds will be displayed. For a granularity set to milliseconds, all components will be displayed.
minimal—This is a minimal time value that omits the date and is in the form HH:MM[:SS][.MMM] where the hour is in 24-hour time and the last three digits are the milliseconds. The seconds and milliseconds are displayed
with brackets to indicate that their appearance are based on the date_granularity attribute. For a date_granularity attribute set to minutes, just the hours and minutes will be displayed. For a granularity set to seconds, just the hours, minutes and seconds will be displayed. For a granularity set to milliseconds, all components will be displayed.
number—This displays a large integer number representing the full date and time as an elapsed time since January 1, 1970, 00:00:00
GMT. For a date_granularity attribute set to minutes, the number will be 8 digits in length (representing the number of minutes elapsed since that date). For a granularity set
to seconds, the number will be 10 digits in length (representing the number of seconds elapsed since that date). For a granularity set
to milliseconds, the number will be 13 digits in length (representing the number of milliseconds elapsed since that date).
Activity Logger Configuration: Scope
The Activity Logger configuration provides the administrator the ability to control what is logged based on their own needs.
This configuration is done by defining logging levels and the events that each level contains. During the debugging stage,
for example, the logging level can be set to record all events and once in production, the logging level can be set to record
more important events.
The <scope> tag defines the logging level to use in the logging_level attribute. The child tag <definitions> encapsulates all possible logging levels. All Activity Logger configurations are required to define a scope with at least
one logging level.
To define a logging level, a separate <level> tag is added within the <definitions> tag and given a name in the name attribute. This tag will include a separate <event> tag for each event the logging level includes. The id attribute defines the name of the event. The following table lists all possible event IDs and describes when that event occurs.
Note
At minimum, the start and end events are required for any logging level as these events are used by the Activity Logger to maintain information about its
log files and which calls are using them.
Event ID
Event Description
start
This event occurs when a new visit is made to the application (could be a new call or visit using an application transfer).
This event is required in all logging levels.
end
This event occurs when an application visit ends. This event is required in all logging levels.
elementEnter
This event occurs when an element is entered. This applies to both standard and configurable elements as well as VoiceXML
Insert elements.
elementExit
This event occurs when an element exits (either ordinarily or due to something occurring within it that took the call flow
elsewhere).
elementFlag
This event occurs when a flag element is visited by a caller.
defaultInteraction
This event occurs when a voice element returns interaction logging content as a result of caller activity within a VoiceXML
page.
elementData
This event occurs when element data is created that has been configured to be stored in the log.
custom
This event occurs when custom content is to be added to the log, either by visiting an element whose configuration specified
content to add or by running custom code using either the Java or XML APIs that specifies to add to the log.
hotlink
This event occurs when a global or local hotlink that points to an exit state (as opposed to throwing a VoiceXML event) is
activated by the caller.
hotevent
This event occurs when a hotevent that has an exit state is activated in the call.
warning
This event occurs when a warning is encountered.
systemError
This event occurs when VXML Server encounters an internal error (that is, an error that does not originate from a custom component).
This event will include a stack trace.
javaApiError
This event occurs when a custom component created with the Unified CVP Java API encounters an error. This event will include
a stack trace.
xmlApiError
This event occurs when a custom component created with the Unified CVP XML API encounters an error. This event will not include a stack trace.
vxmlError
This event occurs when an error event is received from the voice browser. This event will not include a stack trace.
Activity Logger Configuration: File Rotation
In any system that stores information in log files, high volume can cause these files to become very large. The goal is to
have a strategy for creating new log files in order to avoid files that are too large. Additionally, file rotation strategies
can help separate the log files into more logical parts. The Activity Logger defines several rotation strategies to choose
from.
Note
To ensure that the information for a single call is not split across multiple log files, the Activity Logger ensures that
all call information appears in the log that was active when the call was received. As a result, it is possible for calls
to be updating both pre- and post-rotation log files simultaneously.
Each rotation strategy determines how the log files are named (though all activity log filenames begin with activity_log). The <rotation> tag defines the rotation strategy to use by containing one of the following tags:
<by_day>—Creates a new log file every X days where X is an integer value greater than 0 specified in the every attribute. Typically this value is 1, meaning that every day at midnight, a new log file is created. For low volume systems,
the value can be given a larger value. For example, when set to 7, a new log file is created once a week. The log files are
named activity_logYYYY-MM-DD.txt where YYYY is the year, MM is the month, and DD is the day that the file is created.
<by_hour>—Creates a new log file every X hours where X is an integer value greater than 0 specified in the every attribute. There is no upper bound on this value, so it can be greater than 24. The log files are named activity_logYYYY-MM-DD-HH.txt where YYYY is the year, MM is the month, DD is the day, and HH is the hour that the file is created.
Note
The hour is measured in 24-hour time (0 - 23).
Note
In locales that use Daylight Saving Time (DST), calls that are placed after the clock is turned back an hour will continue
to be logged in the current log file for the one a.m hour (the current log file). A new log file is not created when the clock
is turned back for DST for the one a.m hour.
<by_call>—Creates a separate log file for each call made to the application. The log files are named activity_logYYYY-MM-DD-HH-SESSIONID.txt where YYYY is the year, MM is the month, DD is the day, and HH is the hour that the file is created (in 24-hour time) and SESSIONID is the VXML Server session ID (for example, activity_log2000-01-01-17-192.168.1.100.1024931901079.1.MyApp.txt). The session ID is included in the filename to ensure uniqueness of the files.
Note
Care must be taken before using this log file rotation strategy on systems with high load as this will create a very large
number of files.
<by_size>—Creates a separate log file once the previous log file has reached X megabytes in size where X is an integer value greater than 0 specified in the mb_limit attribute.
Note
Due to the fact that multiple calls will be updating the same file and that the Activity Logger will ensure that all data
for a single call appear in the same log file, the final log file may be slightly larger than the limit.
The log files are named activity_logYYYY-MM-DD-HH-MM-SS.txt where YYYY is the year, the first MM is the month, DD is the day, HH is the hour (in 24-hour time), the second MM is the minute, and SS is the second that the file is created. The time information is included in the file name in order to ensure uniqueness.
Activity Logger Configuration: Caching
The Activity Logger has the ability to use a memory cache to store information to log until either the cache fills or the
call ends. Using a cache has several advantages. The first is that it increases performance by waiting until the end of the
call to perform the file IO. Without a cache, the log file would be updated each time an event occurred. Another advantage
is that with caching on, the log file will be more readable by grouping the activities belonging to a single phone call together.
Without the cache, the events for all calls being handled by every application running on VXML Server would be intermingled.
While one can still sort the calls after the log is imported to a spreadsheet or database, it is much more difficult to track
a single call when simply reading the log file without the cache. The one disadvantage of using a cache is that the log file
is not updated in real-time, only after a call has completed. If there is a desire to have the logs updated immediately after
the events occur, then caching should be left out of the configuration.
The <cache> tag has only one child tag: <per_call>, indicating that the cache’s lifetime is a single call to an application. <per_call> defines two attributes: kb_limit, an integer value greater than 0 that defines the size of the cache in kilobytes, and allocate that defines the cache allocation strategy.
The attribute can be set to two values:
once—The Activity Logger will allocate the full memory needed for the cache once and then fill it up with logging information.
When filled, the cache is flushed to the log file and the same section of memory is cleared and then refilled.
as_needed—The Activity Logger will allocate memory as events arrive in the call until the total amount of memory has been allocated.
When it is to be flushed, the memory is released and then the allocation begins again.
The advantage of allocating the memory at once is that since a contiguous section of memory is being used, the updating, maintenance,
and flushing of that memory will be slightly faster. Additionally, with only one area of memory per call fewer memory allocations
take place, which can affect how often Java garbage collection runs. A disadvantage is that the cache size needs to be chosen
carefully. A cache incurs too small performance hits as the cache fills up and is logged multiple times within a call. A cache
means too large that a large amount of memory is allocated and then never used, potentially starving the rest of the system.
A good cache size would be approximately the size of a log for a typical call to the application. Because the cache is flushed
at the end of a call, there is little reason to make the cache much larger.
The advantage to allocating the memory as needed is that this minimizes the memory used since only the memory needed to store
the information is used. The cache size is not as important, and making it larger will not affect the overall memory usage
as drastically as if the cache was allocated all at once because the memory would not be allocated unless needed.
Configure the cache to be allocated once for performance and as needed if memory on the system is limited.
Activity Logger Configuration: File Purging
The Activity Logger can be configured to automatically delete files that conform to certain criteria. Properly configured,
this logger allow an administrator to avoid having the system’s hard drive fill up with logs, which prevents new calls from
being logged.
Note the following information about file purging:
A logger has control only over the files appearing under the logger instance’s dedicated log folder and cannot control those
files managed by other logger instances. This logger even applies to multiple instances of the same logger since each logger
instance is given its own unique folder within the logs folder of the application. Activity Logger file purging therefore applies only to those files appearing under the logger
instance’s folder.
Because loggers are activated only when events occur in a call, the file-purging activity will only take place when a call
ends. As a result, a system that receives no calls at all will not automatically delete files until a new call is received
and completes.
When the Activity Logger starts up for the first time, it will apply the purging strategy on any files that exist in the logger
directory. Therefore, if an application server is shut down with files in the logger directory and then restarted a long time
later, these files could be deleted when the application server starts up and the logger initializes. This applies to any
file appearing in the logger directory, not just activity logs.
The Activity Logger keeps information about the activity log files in memory and acts on that to determine whether to delete
them rather than by monitoring the remaining hard drive space on the system. This is done to avoid having to do file IO to
determine if a file is to be purged and so minimizes overhead (although there still is overhead in deleting files). One consequence
is that the logger keeps track only of those files it is managing. The logger is unaware of any files added to the directory after the application server initializes,
so the purging strategy will affect those files only.
The optional <purge> tag defines the purging strategy. If this tag does not appear in the configuration, no file purging takes place. The tag
can contain one of the following child tags:
file_age—The Activity Logger deletes activity log files older than X days, where X is an integer greater than 0 specified in the older_than attribute.
file_count—The Activity Logger deletes activity log files if the logger folder contains greater than X files, where X is an integer greater than 0 specified in the greater_than attribute. When the files are deleted, the oldest ones are deleted first until the folder reaches the desired file count.
The activity logs will be delimited with a tab ("\t") and will have any tabs that appear in the content removed.
The activity logs will use a Unix-style new line character ("\n") to delimit lines. As a result, these log files would not appear orderly on Windows Notepad because it does not recognize
these new line characters.
Dates in the activity logs will appear in the standard format with millisecond granularity. For example, 05/09/2006 15:45:02.654
Two logging levels are defined: Minimal, which logs only when a caller entered and exited an application, and Complete, which
logs all events. The Complete logging level is the one that will be used.
The activity log files will be rotated every two days, meaning each log file will contain two days worth of calls before a
new file is created.
The cache is set to 10 K or 5000 characters and is allocated once at the start of a call.
Files that are older than three days that appear in the logger instance’s dedicated directory will be purged.
The activity logs will be delimited with a comma and will not remove any commas that appear in the content potentially complicating
any importing of these logs into spreadsheets or databases.
The activity logs will end each line with the character appropriate for the operating system on which it is generated. If
this system is running under Windows, the activity logs can be viewed in Notepad and if this system is running under Unix,
the activity logs can use the Unix end of line characters that would not be recognized if opened by Windows Notepad.
Dates in the activity logs will appear in the minimal format with minute granularity. For example, 15:45.
Only one logging level is defined that logs when calls enter and exit an application, enter and exit an element, and when
a flag element is visited.
A new activity log is created when the previous one has reached approximately 100 MB in size, regardless on whether the calls
spanned weeks or hours.
No logging cache is used, meaning that when a logging event occurs in a call, it is placed into the activity log immediately.
It allows for real-time logging but incurs a performance overhead in managing much more IO operations.
No file purging will take place. The administrator is responsible for maintaining the logs on the system.
Application Error Logger
During the voice application development process, errors can be introduced by configuring elements incorrectly, spelling mistakes
in audio filenames, or by Java coding bugs. In each of these cases, errors occur while running the application. While the
Activity Logger does report errors, it is preferable to isolate errors in a separate file so that they are easily found and
addressed. Additionally, when reporting Java errors, a stack trace is desired. The application Error Logger provides a place
for these errors to appear. The error log file names are in the form error_logYYYY-MM-DD.txt where YYYY, MM, and DD are the year, month, and day when the error log was first created and is rotated daily.
Note
The application Error Logger will report information on errors that are affiliated with the application in which it is configured.
It can even report errors encountered by other loggers in the same application only if the Error Logger is listed before other loggers in the application. If another logger is loaded before the Error Logger, any errors it encounters will be logged
instead to the VXML Server Call Error Log. It is for this reason that by default Builder for Call Studio puts the Error Logger
at the top of the list of loggers to use for a new application.
Starting in Release 8.0(1), the application error log now reports on application timeout events. Previously, timeout events
were not located in the application activity logs.
The columns of the error log are:
SessionID—The session ID of the application visit described in the VXML Server Call Log section.
Time—The time the error occurred.
Description—The error description including a Java stack trace if applicable.
The Error Logger utilizes a configuration to control two different aspects of the error logs: the format of the files and
how often should log files be purged. This configuration is specified as an XML file created by the designer in Builder for
Call Studio, as shown in the following figure.
The main tag for the configuration, configuration, has two attributes, name and version. Name is expected to contain the logger instance name. The version is expected to include the version of the configuration, which is currently 1.0. The subsequent sections describe the functionality of the various tags in the configuration.
Error Logger Configuration: Format
The <format> tag allows for the modification of how the error log files are formatted. All Error Logger configurations are required to
define a format. The possible attributes are:
delimiter—This required attribute defines the delimiter to use to separate columns on a line. Delimiters can be any string value, though
typically will be a comma or tab. To use a special white space character such as a new line or tab, use the escaped version.
The possible values are:
\n (denoting a new line)
\t (denoting a tab)
\r (denoting a return)
\f (denoting a line feed)
remove_delimiter_from_content—When this required attribute is set to true, the Activity Logger will attempt to eliminate the delimiter from any content appearing in the logs to ensure that the log
file can be imported flawlessly. For example, if the delimiter is a comma and the configuration is set to remove the delimiter,
when it is to log the content This, is the description, it will appear in the log as This is the description so as not to affect the accuracy of the importing process. This extra step, though, does incur a slight performance hit.
This step will not be performed if this attribute is set to false.
Note
If the error log contains Java stack traces, the error logs might be difficult to import as stack traces fill multiple lines
(though their content will be cleaned of the delimiter if desired).
date_format and date_granularity—These required attributes set how the second column of the activity log references a date when the event occurred. The format
and granularity are specified.
There are three possible values for the date_format attribute:
standard—This is a standard readable date format in the form MM/DD/YYYY HH:MM[:SS][.MMM] where the hour is in 24-hour time and the last three digits are the milliseconds. The seconds and milliseconds are displayed
with brackets to indicate that their appearance is based on the date_granularity attribute. For a date_granularity attribute set to minutes,only hours and minutes of the time will be displayed. For a granularity set to seconds, only hours, minutes and seconds will be displayed. For a granularity set to milliseconds, all components will be displayed.
minimal—This is a minimal time value that omits the date and is in the form HH:MM[:SS][.MMM] where the hour is in 24-hour time and the last three digits are the milliseconds. The seconds and milliseconds are displayed
with brackets to indicate that their appearance are based on the date_granularity attribute. For a date_granularity attribute set to minutes,only hours and minutes will be displayed. For a granularity set to seconds, only hours, minutes and seconds will be displayed. For a granularity set to milliseconds, all components will be displayed.
number—This displays a large integer number representing the full date and time as an elapsed time since January 1, 1970, 00:00:00
GMT. For a date_granularity attribute set to minutes, the number will be 8 digits in length (representing the number of minutes elapsed since that date). For a granularity set
to seconds, the number will be 10 digits in length (representing the number of seconds elapsed since that date). For a granularity set
to milliseconds, the number will be 13 digits in length (representing the number of milliseconds elapsed since that date).
print_stack_traces—This required attribute is set to either true or false and determines whether the error log will contain Java stack traces. Stack traces are very useful to a developer in tracking
down the cause of a Java error. You must keep this option on.
Error Logger Configuration: File Purging
The Error Logger can be configured to automatically delete files that conform to certain criteria. Properly configured, this
allows an administrator to avoid having the system’s hard drive fill up with logs, which would prevent new calls from being
logged.
Note the following information about file purging:
Becasue loggers are activated only when events occur in a call, the file purging activity will only take place when an error
event occurs. As a result, a system that encounters no errors will not automatically delete files until a new error occurs.
When the Error Logger starts up for the first time, it will apply the purging strategy on any files that exist in the logger
directory. Therefore, if an application server is shut down with files in the logger directory and then restarted a long time
later, these files can be deleted when the application server starts up and the logger initializes.
Unlike the Activity Logger, the Error Logger applies its purging strategy to any files found in its logger directory, including
non-error log files. If other files are added to the logger folder after the application server has started, they might be
deleted when the Error Logger encounters a new error.
The optional <purge> tag defines the purging strategy. If this tag does not appear in the configuration, no file purging will take place. The
tag can contain one of the following child tags:
file_age—The Error Logger deletes error log files older than X days, where X is an integer greater than 0 specified in the older_than attribute.
file_count—The Error Logger deletes error log files if the logger folder contains greater than X files, where X is an integer greater than 0 specified in the greater_than attribute. When the files are deleted, the oldest ones are deleted first until the folder reaches the desired file count.
The error logs will be delimited with a comma and will have any commas that appear in the content removed.
Dates in the error logs will appear in the standard format with seconds granularity. For example: 05/09/2006 15:45:02.
Java stack traces will appear in the error logs.
Note
Because stack traces span multiple lines, including stack traces may complicate the process of importing the error logs into
spreadsheets or databases. This process is rarely done for error logs.
When a new file is added to logger instance’s dedicated directory by the Error Logger, if the directory contains more than
10 files the oldest file will be deleted.
Note
With a large application or a large number of applications, it is possible to fill all available disk space with logs. For
this reason, all applications have a default log retention set to 10 GB (100 logs). Customers should review this setting as
needed and modify it to suit their situation.
The error logs will be delimited with the string "***" and will not attempt to remove that string from the content.
Note
The delimiter does not need to be limited to a single character and can be a multicharacter string. Usually, a single character
makes importing into spreadsheets and databases straightforward.
Dates in the error logs will appear in the minimal format with seconds granularity. For example, 15:45:02.
Java stack traces will not appear in the error logs. When a Java exception occurs, only the error message itself will appear
in the error log without the stack trace.
No file purging will take place. The administrator is responsible for maintaining the logs on the system.
Application Administration History Logger
Whenever an application-specific administration script is run, a log file is updated with information on the script that was
run. The administration log filenames are in the form admin_historyYYYY-MM-DD.txt where YYYY, MM, and DD are the year, month, and day when the administration history log was first created and is rotated daily. The file contains
three columns: the time the script was run, what script was run, and its result. The result is usually success and if not contains the description of the error encountered.
The possible values are:
server_start—Each application’s history log contains records of each time the application server starts.
deploy_app—Listed when the deployApp script is run.
suspend_app—Listed when the suspendApp script is run.
resume_app—Listed when the resumeApp script is run.
update_app—Listed when the updateApp script is run.
release_app—Listed when the releaseApp script is run.
update_common_classes—Listed when the global updateCommonClasses script is run. The reason this global admin event is logged by the Application Administration History Logger is because elements
that appear in the common directory are reloaded by this command, causing those elements to reload their application-specific configurations.
Running the status script does not update the history log. The Administration History Logger does not use a configuration.
Application Debug Logger
At times when debugging an application, it is advantageous to see information concerning the HTTP requests made by the voice
browser and the corresponding HTTP responses of VXML Server. The Debug Logger creates a single file per call that contains
all HTTP requests and responses that occurred within that call session. The log files are named debug_logYYYY-MM-DD-HH-SESSIONID.txt where YYYY is the year, MM is the month, DD is the day, and HH is the hour (in 24-hour time) that the file is created and SESSIONID is the VXML Server session ID (for example, debug_log2000-01-01-17-192.168.1.100.1024931901079.1.MyApp.txt). The Session ID is included in the filename to ensure uniqueness of the files.
The debug log contains:
A timestamp of when each HTTP request was received from the voice browser as well as when the response was sent back by VXML
Server.
All headers of the HTTP request.
All arguments passed with the HTTP request, whether they be set with GET or POST.
The entire VoiceXML page returned in the HTTP response.
We recommend that you use the Debug Logger only when performing debugging and not in a production environment because it incurs
overhead on the system in creating and managing file IO and replicating the HTTP response, which must be generated once for
the voice browser and once for each Debug Logger instance.
Note
The Debug Logger does not require the enforce call event order to be turned on, however, without it there could be situations
where under load the HTTP requests and responses are out of order or mixed together in the file.
Correlating Unified CVP Call Server Logs with VXML Server
Logs
Starting in Release 8.0(1), VXML Server (by default) receives callid (which contains the call GUID), _dnis, and _ani as session
variables in comprehensive mode even if the variables are not explicitly configured as parameters in the ToExtVXML array.
If the variables are configured in ToExtVXML then those values are used. These variables are available to VXML applications
as session variables and they are displayed in the VXML server log.