Custom diagnostic logging and alarms
Voice Platform automatically sends service alarms to the Management Station and writes them to diagnostic logs whenever there is an alarm raised on one of the services. You can also send custom alarms to the Management Station and generate diagnostic log entries for your VoiceXML application. There are two ways to do so:
- Generate alarms in your VoiceXML application code in a <log> element in a <script> element.
- Using the ManagerServlet, a Java-based API that integrates applications with the Management Station.
Generating alarms in VoiceXML
The simpler method is to code alarm messages directly in a VoiceXML document with a <log> element, or within a <script> element.
Using the <log> element
When you send an alarm using the <log> element, the syntax is:
<log label="trace:?level=ALARM_LEVEL"> message_text <value expr="variable1"/>
</log>
The ALARM_LEVEL is the desired level to be assigned to the alarm (MINOR_ALARM, MAJOR_ALARM, or CRITICAL_ALARM). The message_text summarizes the event or error. This text appears in the Management Station and is also written to disk in the diagnostic log file. The <value> element is optional. If used, variable1 is the variable whose value is to be included in the alarm summary text.
For example, suppose you want your application to generate a minor alarm if 10 consecutive no-speech timeouts (<noinput> events) are received for a given field. You could do so by including the following code in the <field>:
<!-- Send an alarm for too many no-speech timeouts-->
<catch event="noinput" count="10">
<log label="trace:?level=MINOR_ALARM">
User timed out without speaking 10 times.
</log>
<exit/>
</catch>
This triggers a minor alarm that appears in the Management Station Alarms table. The alarm message is “User timed out without speaking 10 times.”
Using ECMAScript
To generate an alarm in VoiceXML using ECMAScript, use the following method on the browser object:
<script>
browser.log("message-url", "message_text"); </script>
For example, you could send the same alarm as that used in the <log> example:
<script>
browser.log=("trace:?level=MINOR_ALARM","User timed out without speaking 10 times.");
</script>
This will send the same alarm to the Management Station and diagnostic logs.
Using the ManagerServlet and AppServ servlets
The other method for sending custom alarm messages to the Management Station is to use the ManagerServlet and AppServ servlets. These servlets, included with the installation, provide examples of how you can integrate your applications with the Management Station. The files are extensively commented so you can understand what they are doing at each point in the code.
ManagerServlet
ManagerServlet gets executed when the Application Container service is launched. This servlet serves two purposes:
- First, it sets up communication with the Management Station—the Application Container service is visible in the Management Station because the ManagerServlet establishes this communication. It also starts a thread to wait for a quiesce command from the Management Station to bring the Application Container service down. These actions make the Application Container service manageable through the Management Station.
- Second, it provides an HTTP interface that allows other servlets (such as the AppServ servlet in PizzaTalk) to generate logs and send alarms to the Management Station by posting an HTTP request to the ManagerServlet URI.
The ManagerServlet Java file is located in:
%NVP_HOME%\appservice\applications\webapps\ManagerServlet\WEB-INF\src
AppServ servlet
The AppServ servlet serves PizzaTalk to the Voice Browser service when the HTTP server checks the ...\PizzaTalk\WEB-INF subdirectory. In there, the HTTP server finds an XML file (web.xml) that tells it to send requests to the AppServ servlet, which then tells it how to find the initial PizzaTalk page. This means that every time PizzaTalk’s initial page is accessed, the AppServ servlet executes, working with the ManagerServlet to allow PizzaTalk to do logging and send alarms to the Management Station.
For example, it sends an alarm to the Management Station when an nonexistent URL is being accessed. The AppServ servlet constructs an HTTP query containing a log or alarm message string, and posts the HTTP query to the ManagerServlet URI. The ManagerServlet then extracts the log or alarm message from the HTTP query and writes it to a log, or sends it to the Management Station as an alarm.
The AppServ servlet Java file is located in:
%NVP_HOME%\appservice\applications\webapps\PizzaTalk\WEB-INF\src
