logsrv.script

Software Testing Automation Framework (STAF)的开发代码

.***************************************************************************
.* Software Testing Automation Framework (STAF)
.* (C) Copyright IBM Corp. 2001
.*
.* This software is licensed under the Common Public License (CPL) V1.0.
.****************************************************************************

.*************************-START-OF-PROLOG-****************************
.*
.*  File Name       : LogSrv SCRIPT
.*  Descriptive Name: Software Test Automation Framework
.*  Detail          : This file describes the STAF Log Service
.*
.**************************-END-OF-PROLOG-*****************************
:i1.log service
:ih1.services
:i2.log service
:h2 id=logsrv.Log Service
:h3.Description
The Log service is an external STAF service that provides the following
functions:
:ul compact.
:li.LOG - Write data to a log file
:li.QUERY - Query data from a log file
:li.LIST - List log file characteristics
:li.DELETE - Delete a log file
:li.PURGE - Purge records from a log file
:li.SET - Set operation characteristics
:li.&help.
:eul.
:p.The purpose of the Log service is to allow a test case to easily and
flexibly manage information that needs to be logged.  It allows you to specify
a log mask which defines which messages actually get logged to the log file.
This log mask can be dynamically changed to alter the set of log messages
written to the log file(s).  This can greatly assist in debugging.  For example,
while a test case is running, you can dynamically alter the log mask to allow
debug and trace log messages to start being logged.  The log query mechanism
allows for record selection based on many selection criteria matches.
:p.The Log service can be run in one of two modes.  In local mode, all log
requests are handled locally, and all log files are stored locally.  In remote
mode, all log requests are forwarded to a central system for processing.  In
addition, all log files are stored on the central system.  While it is possible
to delegate the log service to a central system, this has some unwanted side
effects.  The primary one being that many unwanted messages are likely to be
sent over the network, consuming time and bandwidth.
:p.The following is an example of the major difference between delegating
the Log service and using the Log service in remote logging mode.
:cgraphic scale='.8'.
Example Delegated Log

                                  NETWORK
            start                    ! start
            info                     ! info
            warning                  ! warning
 +------+   trace    +-----------+   ! trace    +-------+
 ! TEST !-> debug -> !   STAF    !-> ! debug -> ! STAF  ! -> WRITE LOG
 ! CASE !   trace    ! DELEGATED !   ! trace    ! LOG   !    =========
 +------+   error    !   LOG     !   ! error    ! Mask= !    error
            debug    +-----------+   ! debug    ! Error !    fail
            trace                    ! trace    ! Fail  !
            debug                    ! debug    +-------+
            fail                     ! fail


Example Remote Logging

                                 NETWORK
            start                    !
            info                     !
            warning                  !
 +------+   trace    +-----------+   !          +------+
 ! TEST !-> debug -> !  LOG      !-> ! error -> ! STAF ! -> WRITE LOG
 ! CASE !   trace    !  Mask=    !   ! fail     ! LOG  !    =========
 +------+   error    !  Error    !   !          +------+    error
            debug    !  Fail     !   !                      fail
            trace    +-----------+   !
            debug                    !
            fail                     !
:ecgraphic.
:p.In the above Delegated Log service example, all the messages flowed over
the network to the ultimate log server even though only error and fail
conditions were selected to be logged. In the above Remote Logging example, the
selection of the messages occur at the local box and only those
messages that are selected get sent over the network to the ultimate
log server.
:note.When using the Log service in remote logging mode, you should have the
log mask disabled (i.e. log everything) at the ultimate log server to avoid
confusion and multiple log mask filtering.:enote.
.*
.*---------------------------------------------------------------------
.*
:ih1.registration
:i2.log service
:h3.Registration
The Log service is an external service and must be registered with the SERVICE
configuration statement. The syntax is:
:xmp.
SERVICE :xph.<Name>:exph. LIBRARY STAFLog &lbrk.PARMS <Log parameters>&rbrk.
:exmp.
:p.:xph.<Name>:exph. is the name by which the Log service will be known on this
machine.  The recommended name of the Log service is "LOG"
:p.:xph.<Log parameters>:exph. are valid log parameters described below.
:h4.Example
:xmp.
service log library STAFLog
service log library STAFLog parms "Directory {STAF/Config/STAFRoot}/logdata ResolveMessage"
:exmp.
.*
.*---------------------------------------------------------------------
.*
:ih1.parameters
:i2.log service
:h3 id=logparms.Parameters
:p.The Log service accepts a parameter string in the following formats
:xmp.
&lbrk.DIRECTORY <Log Directory Root>&rbrk.
&lbrk.MAXRECORDSIZE <Size>&rbrk. &lbrk.DEFAULTMAXQUERYRECORDS <Number>&rbrk.
&lbrk.RESOLVEMESSAGE | NORESOLVEMESSAGE&rbrk.
&lbrk.ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR&rbrk.
:exmp.
or
:xmp.
ENABLEREMOTELOGGING REMOTELOGSERVER <Server name>
                    &lbrk.REMOTELOGSERVICE <Service Name>&rbrk.
:exmp.
:p.:xph.DIRECTORY:exph. specifies the root directory under which log files are
stored.  The default is :xph.{STAF/DataDir}/service/&lt;Service Name (lower-case)>:exph..
:note.Previously, in STAF 2.x, the default root directory was
:xph.{STAF/Config/STAFRoot}/data/log:exph..
So, if you want to continue to use the STAF 2.x log files with the
current version of STAF, move the log files to the new default root
directory or specify the old root directory for the :xph.DIRECTORY:exph. parameter.:enote.
:p.:xph.MAXRECORDSIZE:exph. specifies the maximum length (in characters) of a
logged message.  The default is 100000.
:p.:xph.DEFAULTMAXQUERYRECORDS:exph. specifies the maximum number of records
that will be returned if your query criteria selects more records than this number.
The default is 100.  If no limit on the maximum number of records returned by
a query is desired, specify 0.
If a non-zero value is specified, it's equivalent to specifying LAST <Number>.
This limit is only used if none of the following options are specified on a
:xph.QUERY:exph. request:  :xph.FIRST, LAST, ALL, TOTAL, or STATS:exph..
:p.:xph.RESOLVEMESSAGE:exph. specifies that variables in log messages should
be resolved by default.
:p.:xph.NORESOLVEMESSAGE:exph. specifies that variables in log messages should
not be resolved by default.  This is the default.
:p.:xph.ENABLERESOLVEMESSAGEVAR:exph. specifies that the log service should
check the value of the STAF/Service/<Name>/ResolveMessage variable to determine
if variables in log messages should be resolved.  This option will adversely
affect the performance of the Log service.  See below for more information.
:p.:xph.DISABLERESOLVEMESSAGEVAR:exph. specifies that the log service should not
check the value of the STAF/Service/<Name>/ResolveMessage variable to determine
if variables in log messages should be resolved.  See below for more information.
This is the default.
:p.:xph.ENABLEREMOTELOGGING:exph. specifies that the Log service should operate
in remote/forwarding mode.
:p.:xph.REMOTELOGSERVER:exph. specifies the server to which forwarded log
requests should be sent.  This machine must be running STAF V3.0.0 or later.
:note.From a trust perspective, the tcp interface names on the remote log
server and on the machine forwarding requests to it must match or the remote
log server must use a wildcard to match any interface in the trust statement for
the machine that is forwarding log requests to it.
:p.:xph.REMOTELOGSERVICE:exph. specifies the service to which forwarded log
requests should be sent.  The default is the same name under which the Log
service was registered on the local machine.
:note.All these parameters, with the exception of :xph.DIRECTORY:exph.,
:xph.ENABLEREMOTELOGGING:exph., :xph.REMOTELOGSERVER:exph., and
:xph.REMOTELOGSERVICE:exph. may be changed with the :xph.SET:exph. command,
see :hdref refid=logset. for more information.:enote.
.*
.*---------------------------------------------------------------------
.*
:ih1.variables
:i2.log service
:h3.Variables
The following variables will affect the behavior of the Log service.
:sl compact.
:li.:xph.STAF/Service/<Name>/Mask::exph. A string of log mask descriptions, or a 32 bit binary mask.
:li.:xph.STAF/Service/<Name>/ResolveMessage::exph. Whether to resolve variables in the message
:esl.
:h4.STAF/Service/<Name>/Mask
The variable determines what messages will and will NOT be written
to the log file. You can set it to only have FATAL and ERROR messages written
to the log file for example, or turn on DEBUG in the middle of a running test.
This allows you to put as much informational, trace, debug, status, etc.
logging messages into your testcases as you want, but based on the circumstance,
dynamically alter the logging levels via configuration, not the testcase.
:p.See :hdref refid=loglev. for a complete list of logging levels.
:p.The log mask contains the set of levels that will actually be logged to the
log file.
:sl compact.
:li.:hp2.Example::ehp2. set shared var "STAF/Service/Log/Mask=START STOP WARNING FATAL ERROR"
:li.:hp2.Default::ehp2. All logging levels will be logged
:esl.
Alternatively, a 32 bit binary string may be specified that determines which logging
levels will be applied.
:sl compact.
:li.:hp2.Example::ehp2. set shared var STAF/Service/Log/Mask=11111111000000000000000000000000
:esl.
:h4.STAF/Service/<Name>/ResolveMessage
This variable determines if messages should be resolved before writing them.
If message resolution is desired, then a call to the STAF variable
service is made and all variables in the message are resolved.  If for any reason
the resolution is unsuccessful (e.g. unbalanced braces {}, infinite recursion,
etc.) then an error is generated.
:note.This variable is not checked unless the :xph.ENABLERESOLVEMESSAGEVAR:exph.
option has been set.
:sl compact.
:li.:hp2.Example::ehp2. set shared var STAF/Service/Log/ResolveMessage=1
:li.:hp2.Default::ehp2. 0 (messages are NOT resolved)
:esl.
If a message was "Machine booted from {STAF/Config/BootDrive}" and
STAF/Service/:xph.<Name>:exph./ResolveMessage was set to 1 then what would
actually be logged would look like: "Machine booted from C:".  If
STAF/Service/:xph.<Name>:exph./ResolveMessage was not defined or set to 0 then
the original text of the message would be logged:
"Machine booted from {STAF/Config/BootDrive}".
:note.There are three places where message resolution can be affected.  They are
evaluated in the following order
:ul compact.
:li.The :xph.RESOLVEMESSAGE:exph. or :xph.NORESOLEMESSAGE:exph. options on a
:xph.LOG:exph. request.
:li.The variable STAF/Service/<Name>/ResolveMessage, if the
:xph.ENABLERESOLVEMESAGEVAR:exph. option has been set.
:li.The :xph.RESOLVEMESSAGE:exph. or :xph.NORESOLVEMESSAGE:exph. operational
parameters, setable via the :xph.PARMS:exph. option when configuring the
service or via the :xph.SET:exph. command.
:eul.
:enote.
.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.LOG
:i3.log service
:h3.LOG
Writes data to a log file.
:h4.Syntax
:xmp.
LOG <GLOBAL | MACHINE | HANDLE> LOGNAME <Logname> LEVEL <Level> MESSAGE <Message>
    &lbrk.RESOLVEMESSAGE | NORESOLVEMESSAGE&rbrk.
:exmp.
:p.:xph.GLOBAL:exph. indicates you want to write to a global log.  The global
log is intended to facilitate multiple testcases on multiple machines all
writing to a common log.
:p.:xph.MACHINE:exph. indicates you want to write to a machine log.  The machine
log is intended to facilitate multiple testcases on a single machine all writing
to a common machine name log.
:p.:xph.HANDLE:exph. indicates you want to write to a handle log.  The handle
log is intended to facilitate each testcase writing to a separate log (no matter
how many machines and processes are involved)
:p.:xph.LOGNAME:exph. contains the name of the log to which you want to write.
&varres.
:p.:xph.LEVEL:exph. determines the level that you want to log. This can be in
the form of level type such as "FATAL", "ERROR",  WARNING", etc. or a 32 byte
binary string such as "00000000000000000000000000000001". &varres.
See :hdref refid=loglev. for a complete list of logging levels.
:p.:xph.MESSAGE:exph. contains the message (data) that you want to write to the
log.  This option will not resolve messages by default but can be configured to
do so in the STAF configuration file or by using RESOLVEMESSAGE.
Any private data in the message will be masked before writing to the log.
:p.:xph.RESOLVEMESSAGE:exph. causes the LOG service to call the STAF variable
service to resolve any variables in the message before being written.  This
overrrides any other message resolution settings.
:p.:xph.NORESOLVEMESSAGE:exph. causes the LOG service to not call the STAF
variable service.  This overrrides any other message resolution settings.
:h4.Security
:p.&seclvl. 3.
:h4.Return Codes
:h4.Results
:p.The result buffer will contain no data on return from a LOG command.
:h4.Examples
:ul.
:li.:xph.LOG GLOBAL  LOGNAME stresstst LEVEL fatal MESSAGE &colon.33&colon.Testcase aborted with error "255":exph.
:li.:xph.LOG MACHINE LOGNAME stresstst LEVEL 10000000000000000000000000000000 MESSAGE Recovered:exph.
:li.:xph.LOG HANDLE  LOGNAME stresstst LEVEL start MESSAGE "Step1 in Test1 initiated":exph.
:eul.
.*
.*---------------------------------------------------------------------
.*
:ih1.service commands
:ih2.QUERY
:i3.log service
:h3 id=query.QUERY
:p.Allows you to query records from a log based on a set of selection criteria.
:note.A stand-alone utility also exists, called FmtLog, that can read a log file
and write the data to an output file in a readable format.
See :hdref refid=fmtlog. for additional information.:enote.
:h4.Syntax
:xmp.
QUERY  <GLOBAL | MACHINE <Machine> &lbrk.HANDLE <Handle>&rbrk.> LOGNAME <Logname>
       &lbrk.LEVELMASK <Mask>&rbrk. &lbrk.QMACHINE <Machine>&rbrk.... &lbrk.QHANDLE <Handle>&rbrk....
       &lbrk.NAME <Name>&rbrk.... &lbrk.USER <User>&rbrk.... &lbrk.ENDPOINT <Endpoint>&rbrk....
       &lbrk.CONTAINS <String>&rbrk.... &lbrk.CSCONTAINS <String>&rbrk....
       &lbrk.STARTSWITH <String>&rbrk.... &lbrk.CSSTARTSWITH <String>&rbrk....
       &lbrk.FROM <Timestamp> | AFTER <Timestamp>&rbrk.
       &lbrk.BEFORE <Timestamp> | TO <Timestamp>&rbrk.
       &lbrk.FROMRECORD <Num>&rbrk. &lbrk.TORECORD <Num>&rbrk.
       &lbrk.FIRST <Num> | LAST <Num> | ALL&rbrk. &lbrk.TOTAL | STATS | LONG&rbrk.
       &lbrk.LEVELBITSTRING&rbrk.
:exmp.
:p.:xph.GLOBAL:exph. indicates you want to query to a global log.  The global log is intended
to facilitate multiple testcases on multiple machines all writing to a common log.
:p.:xph.MACHINE:exph. indicates you want to query to a machine log.  Specify the machine nickname.
The machine log is intended to facilitate multiple testcases on a single machine all
writing to a common log.  &varres.
:p.:xph.HANDLE:exph. indicates you want to query to a handle log.  The handle log is intended
to facilitate each testcase writing to a separate log. &varres.
:p.:xph.LOGNAME:exph. contains the name of the log you want to query. All log files have the ".log"
extension automatically added to the file name. &varres.
:p.:xph.LEVELMASK:exph. determines the levels that are selected.  This can be in the form of
"FATAL ERROR WARNING" or a 32 byte bit string such as "00000000000000000000000000000111".  &varres.
:p.:xph.QMACHINE:exph. selects only those records that originated from a certain machine.
Multiple :xph.QMACHINE:exph. statements are handled as an "or" condition. &varres.
:p.:xph.QHANDLE:exph. selects only those records that are associated with a certain handle.
Multiple :xph.QHANDLE:exph. statements are handled as an "or" condition. &varres.
:p.:xph.NAME:exph. selects only those records with a certain registered name.
Multiple :xph.NAME:exph. statements are handled as an "or" condition. &varres.
:p.:xph.USER:exph. selects only those records with a certain user.
:xph.<User>:exph. format is :xph.<Authenticator>&colon.//<User Identifier>:exph. (e.g.
none&colon.//anonymous, SampleAuth&colon.//[e-mail]).
Multiple :xph.USER:exph. statements are handled as an "or" condition. &varres.
:p.:xph.ENDPOINT:exph. selects only those records with a certain endpoint.
Multiple :xph.ENDPOINT:exph. statements are handled as an "or" condition. &varres.
:p.:xph.CONTAINS:exph. selects only those records that contain a specified string in the message.  Note
that this match is case insensitive. Multiple :xph.CONTAINS:exph. statements are
handled as an "or" condition. &varres.
:p.:xph.CSCONTAINS:exph. selects only those records that contain a specified string in the message.  Note
that this match is case sensitive. Multiple :xph.CSONTAINS:exph. statements are
handled as an "or" condition. &varres.
:p.:xph.STARTSWITH:exph. selects only those records that start with a specified string in the message.
Note that this match is case insensitive. Multiple :xph.STARTSWITH/CSSTARTSWITH:exph. statements are
handled as an "or" condition. &varres. 
:p.:xph.CSSTARTSWITH:exph. selects only those records that start with a specified string in the message.
Note that this match is case sensitive. Multiple :xph.CSSTARTSWITH/STARTSWITH:exph. statements are
handled as an "or" condition. &varres. 
:p.:xph.FROM:exph. selects only those records that have a date and/or time from the specified format.  &varres.
:p.:xph.AFTER:exph. selects only those records that have a date and/or time after the specified format.  &varres.
:p.:xph.TO:exph. selects only those records that have a date and/or time to the specified format. &varres.
:p.:xph.BEFORE:exph. selects only those records that have a date and/or time before the specified format. &varres.
:note.:xph.<Timestamp>:exph. format is date, @time, or date@time (e.g. 19980214, @16:30:45, 19980214@16:30:45)