Article ID:	179
Last updated:	January 12, 2007

Would you like to...

Print this page

Post a comment

User Opinions

No users have voted.

---

How would you rate this answer?

Helpful

Not helpful

Thank you for rating this answer.

SUMMARY

This article explains each of the logs that are recorded by Audium Call Services, including the data that they store.

SYMPTOMS

N/A

RESOLUTION

Audium Call Services maintains five types of log files on the system. They fall under three categories, logs of caller behavior within an application, logs of general information, and administration script activity logs. Application-specific logs (including application-level administration logs) are stored in the logs folder of that particular application. System-level logs (including Call Services-level administration logs) are stored in the logs folder of Call Services.

Each log is "rotated" on a daily basis. This means that each day calls are received, a new log is created and appended to. The format for the log filenames is "LOGNAMEYYYY-MM-DD.txt" where the LOGNAME is the name of the appropriate log file and the current day is listed with a four digit year, month, then day separated by dashes. Rotating logs allows the administrator to analyze the caller behavior of a range of time by simply selecting the appropriate days. It also allows the administrator to delete or move older log files from the system while Call Services is running without affecting the logging for new calls (Call Services itself does not remove old log files, this is the responsibility of the administrator). This becomes necessary for high volume systems since log files can take a significant amount of disk space depending on the detail stored in them. Note that if nothing occurs that would update the log in a particular day, no log file will be created.

Most log files are comma-delimited, making them simple to import into databases, spreadsheets, and reporting packages. The only log that is not comma-delimited is the application-specific error logs, which are not designed to be exported.

The call log records a single line for every application visit handled by an install of Audium Call Services. Most calls will be to a single application so in this case a line in the call log is equivalent to a physical phone call. For situations where one Audium application performs and application transfer to another Audium 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. Since 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 rotated call log file names begin with "call_log" and can be found in the logs directory of Call Services. The columns of the data are:

• CallID. This is a Call Services-generated non-repeating value used to uniquely identify calls. It is designed to be unique even across machines, as 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 machine on which Call Services is installed, SECS is a large integer number representing the time the application visit was made and INCR is an automatically incremented number managed by Call Services. Each part is delimited by dots and contains no spaces. For example: 192.168.1.100.1024931901079.1.

• 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 simply 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 (including 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 a readable format. This represents when the call was received or the application transfer occurred.

The activity log is the main log managed by Audium Call Services. It contains all 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 utterances. The rotated activity log names begin with "activity_log" and are stored in the logs directory of the specific application it applies to.

While detailed logs are useful for application development and tuning, they are not always necessary when a voice application goes into production. The amount of detail stored in the activity log can be controlled by changing the logging level application setting in Audium Builder for Studio. Applications can even be configured to change the logging level on a per-call basis depending on some developer-specified criteria. There are four logging levels: complete (the default), moderate, minimal, and none (which creates no activity log). Table 5-1 lists what data is stored in the log for each logging level. The columns of the data are:

• SessionID. The session ID of the application visit as described in the 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. A list of categories is given in Table 5-1.

• Action. A keyword indicating the action taken. A list of actions is given in Table 5-2.

• Description. Some qualifier or description of the action.

Unlike any other log, the activity log utilizes a per-call memory cache that stores the events to log until either the cache fills or the call ends. Audium Call Services uses a cache for performance purposes and to make the log file 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 Call Services 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 administrator has the option to change the size of the cache. A very small value will essentially make Call Services act as if there were no cache since each logging event will fill the cache and get saved to the file. This can be useful if memory is tight or it is desirable to instantly log events.

The cache size is specified in a file named global_config.xml found in the conf directory of Call Services. This XML file contains a tag named that encapsulates the size of the cache in characters. If no value is specified, the cache defaults to a size of 100,000 characters. Any change will take affect the next time Call Services is started.

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 error messages appear in the Activity Log, it is preferable to isolate errors in a separate file so that they are easily found and dealt with. Additionally, when reporting Java errors, a stack trace is desired. The application Error Log provides a place for these errors to appear. The application Error Log is designed for readability, not for importing. The rotated error log file names begin with "error_log" and can be found in the logs directory of the specific application it applies to. The columns of the data are:

• SessionID. The session ID of the application visit described in the Call Log section.

• Time. The time the error occurred.

• Description. The error description including Java stack trace if applicable.

There are a few isolated cases where an error occurs outside the realm of a particular application. In order to report these errors, the Call Error Log is used. Like the application error log, the call error log is designed for readability. The rotated error log file names begin with "error_log" and can be found in the logs directory of Call Services. The columns of the data are:

• 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 Audium license ports were taken. While the call was eventually handled correctly, this is placed here as a notice that he license may not have enough Audium ports to satisfy caller demand. Another value is bad_url:[URL], indicating that a request was made to Call Services for a URL that could not be recognized. This most likely will occur if the voice browser refers to an application that either doesn’t exist or no longer exists. The last description is error, indicating that some other error occurred.

Whenever an application-specific administration script is run, a log file is updated with information on the script that was run. The rotated administration log file names begin with "admin_history" and can be found in the logs directory of the specific application it applies to. 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.

Note that running the releaseApp and status scripts do not update the history log.

Whenever a Call Services-specific administration script is run, a log file is updated with information on the script that was run. The rotated administration log file names begin with "admin_history" and can be found in the logs directory of Call Services. The file contains three columns: the time, 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 - Listed when the Java application server starts up.

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

Note that running the status script does not update the history log.