Galaxy Communicator Documentation:
Logging
What Can Be Logged and Why
Execution of server operations, contents of key values, and spoken utterances
can be logged for purposes of debugging or playback. Logfile instructions
are useful for spot checking the system, and the resulting logs display attributes
important for debugging.
As of version 2.0, it is now possible to log incoming Hub messages and
keys in both scripted and scriptless modes, as well as Hub activity such
as alarm expirations, etc. Also, it is now possible to version your logs.
Adding
Logfile Instructions to the Program File
There is no simple way to "turn on" logging, but one can tailor a program file to log specific data.
Global Parameters
Some logging parameters are defined globally in the program
file. These instruct what to log and when. The following
table contains the logfile instruction parameters that need to be defined
globally in the program file. Note that any line breaks
in these entries are the result of browser formatting; no linebreaks are
permitted in these entries.
logging variable |
description |
what can be logged |
example |
LOG_DIR: |
top level logging directory
path can be relative or absolute
logging will not occur if not declared (no default value)
if this directory does not exist, it is created
|
n/a |
LOG_DIR: /usr/users/communicator/logs |
LOG_HUB_ACTIVITY: |
list of Hub events to log
|
legal values are serve_any_session serve_this_session_only
get_session_lock release_session_lock alarm_activity system_errors |
LOG_HUB_ACTIVITY:serve_any_session system_errors |
LOG_VERSION: |
user string to track log versions
|
an arbitrary string which can be used to differentiate different strategies
for logging a system (if, for instance, you change the names of your keys
or operations and your automatic annotation tools need to be able to tell
which strategy is being used) |
LOG_VERSION: "travel demo, version 2.3" |
TIMESTAMP: |
server operations or programs/messages to log with timestamps
timestamps are recorded whenever the specified operations are executed
or programs are invoked (see below)
legal values are any message name, with an optional operation
name prefix
entries match by identical string match or by description (.e.g, [parser].Parse
forces a timestamp entry for any Parse message routed to or
from the provider with the provider ID [parser])
only one TIMESTAMP: line per program file (subsequent declarations
override)
the special key :hub_all_operations forces all operations
to be timestamped
|
server operations |
TIMESTAMP: create_frame context_tracking_in paraphrase_request
turn_management [context].paraphrase_reply |
USER_ID: |
user identification
name of logging subdirectory (under <LOG_DIR:>)
used as prefix to the logfile
if not specified, default value is 'sls'
|
n/a |
USER_ID: travel_audio |
Parameters within
the Scope of a Rule
Other logging parameters can be defined within the scope of a given rule.
The variables below allow specific key values to be logged in association
with the execution of a particular operation.
logging variable |
description |
what can be logged |
example |
LOG_IN: |
associated with a particular program file rule or program/message
keys are specified within the scope of a rule
values are stored before the rule is fired
keys are logged from message, not from token
using LOG_IN: forces a timestamp to be recorded
|
values of keys, frame contents |
RULE: !:thin_frame & !:parse_frame & :input_string -->
nl.create_frame
IN: :input_string :domain
LOG_IN: :input_string
OUT: :thin_frame :parse_status |
LOG_OUT: |
associated with a particular program file rule or program/message
keys are specified within the scope of a rule
values are stored upom return from the server
keys are logged from message, not from token
using LOG_OUT: forces a timestamp to be recorded
|
values of keys, frame contents |
RULE: !:thin_frame & !:parse_frame & :input_string
--> nl.create_frame
IN: :input_string :domain
OUT: :thin_frame :parse_status
LOG_OUT: :thin_frame :parse_status |
It is also possible to use specify mappings between local and remote keys,
as you can with IN: and OUT:
LOG_IN: (:parse_frame :input_frame)
Both normal and error replies will be logged if you have LOG_OUT: keys specified.
All error replies are logged.
Parameters
within the Scope of a Program or Message
The LOG_IN: and LOG_OUT: directives can also be used to log messages
which the Hub receives (and the replies the Hub sends to the originating
server). There are two ways to do this.
If the Hub finds a matching program, you can use LOG_IN:/LOG_OUT: in at
the top level of the PROGRAM: block. LOG_OUT: will only be respected
if the server is awaiting a reply.
SERVER: parser
OPERATIONS: parse_nl
PROGRAM: main
LOG_IN: :string
RULE: :string --> parser.parse_nl
In scriptless mode, you can use LOG_IN: and/or LOG_OUT: under the MESSAGE:
declaration:
logging variable |
description |
what can be logged |
example |
MESSAGE: |
the name of a message which the Hub may receive |
n/a |
MESSAGE: parse_string |
This declaration might be used as follows:
SERVER: parser
OPERATIONS: parse_nl
MESSAGE: parse_nl
LOG_IN: :string
When the Hub receives the parse_nl message, it will log the :string
key value before it passes the message on to the appropriate server. If the
originating server is awaiting a reply, LOG_OUT: is also respected. Unlike
the PROGRAM: directive, but like the TIMESTAMP: directive,
the MESSAGE: directive matches both by literal name and by description;
so MESSAGE: parser.parse will support logging of any incoming
message or outgoing reply whose name is either literally parser.parse
or any parse message which is intended for a provider of service
type parser. This latter case is possible if the caller explicitly
forces the
Hub program matching to be bypassed.
Audio Logging
The MIT audio server implements a fairly complex way of logging audio. We
no longer document this method, because the MIT audio server is no longer
being distributed with Galaxy Communicator. If you're writing an audio server,
this server needs to do some basic things:
- It should capture the audio and write it to a file, allowing the filename
path and prefix to be set by calling dispatch functions
- It should report the filename back to the Hub
The fact that audio is typically shipped around by brokering can cause some
difficulty, because the Hub can't log the audio (since it doesn't pass through
the Hub), and if the Hub and audio servers can't access the same file system,
the audio files will have to be moved to the appropriate location by some
outside process.
When and How Data Get Logged
Key Values and Frame Contents
Parameters (key values and frame contents) are logged either before or after
the associated rule is fired. LOG_IN: parameters are stored before
the operation is executed. LOG_OUT: parameters are logged upon return
from the server.
Timestamps
Explicit timestamps from the TIMESTAMP: directive
are recorded whenever the listed operations are called or programs/messages
are invoked. Implicit timestamps resulting from the presence of LOG_IN: or
LOG_OUT: parameters are logged in the appropriate circumstance; those
in the context of the RULE: directive are recorded when the operations
are called, and those in the context of the PROGRAM: or MESSAGE: directives
are recorded when a new message is received by the Hub or when a reply message
is returned to the caller.
Audio
Audio should be logged by the audio server when the audio server is done
processing it.
Where Logfiles and
Data are Stored
Text logfiles are stored in the logfile directory as <LOG_DIR:>/<USER_ID:>/date/counter/<USER_ID:>-date-counter-hublog.txt, where:
USER_ID: |
user identification as specified in program file
default value is 'sls'
|
date |
date of log in yyyymmdd format
|
counter |
3-digit session identifcation in ddd format
|
hublog.text |
default suffix
|
The location of audio log files depends on the configuration of your audio
server. The value of LOG_DIR: and the remainder of the logfile prefix are
available in the Hub
scripting language to pass to your servers if necessary.
Last updated May 25, 2002