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)
cannot use dot notation with operation names
only one TIMESTAMP:
line per program file (subsequent declarations override)
|
server operations |
TIMESTAMP: create_frame context_tracking_in paraphrase_request
turn_management 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
|
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
|
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
As of version 2.0, it is possible to log the
invocation of programs (or incoming messages
and their replies in scriptless mode). You can timestamp them by listing
them on the TIMESTAMP: list. For example:
SERVER: parser
OPERATIONS: parse_nl
TIMESTAMP: main parse_nl
PROGRAM: main
RULE: :string --> parser.parse_nl
If you want to log the incoming and
outgoing keys associated with a program, simply use LOG_IN:/LOG_OUT: at
the program level:
SERVER: parser
OPERATIONS: parse_nl
TIMESTAMP: main parse_nl
PROGRAM: main
LOG_IN: :string
RULE: :string --> parser.parse_nl
This will cause the value of the :string key
to be logged when the program is first invoked. If you want to log the
keys for a program return to a server which has called GalSS_EnvDispatchFrame,
just use LOG_OUT:.
Parameters
within the Scope of a Message
In scriptless mode, the timestamp will be
recorded without any declaration at all beyond the one on the TIMESTAMP:
list.
If you want to log incoming and outgoing
keys in scriptless mode, 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
TIMESTAMP: main 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.
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
Timestamps are recorded whenever the listed
operations are called or programs/messages are invoked.
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.
Please send comments and suggestions to:bugs-darpacomm@linus.mitre.org
Last updated September 24, 2001.
Copyright (c)
1998 - 2001
The MITRE
Corporation
ALL RIGHTS RESERVED