Galaxy Communicator Documentation:

Logging

License / Documentation home / Help and feedback



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


    License / Documentation home / Help and feedback
    Last updated May 25, 2002