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: 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