Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

logger(n)                             Object Oriented logging facility                             logger(n)



____________________________________________________________________________________________________________

NAME
       logger - System to control logging of events.

SYNOPSIS
       package require Tcl  8.2

       package require logger  ?0.9?

       logger::init service

       logger::import ?-all? ?-force? ?-prefix prefix? ?-namespace namespace? service

       logger::initNamespace ns ?level?

       logger::services

       logger::enable level

       logger::disable level

       logger::setlevel level

       logger::levels

       logger::servicecmd service

       ${log}::debug message

       ${log}::info message

       ${log}::notice message

       ${log}::warn message

       ${log}::error message

       ${log}::critical message

       ${log}::alert message

       ${log}::emergency message

       ${log}::setlevel level

       ${log}::enable level

       ${log}::disable level

       ${log}::lvlchangeproc command

       ${log}::lvlchangeproc

       ${log}::logproc level

       ${log}::logproc level command

       ${log}::logproc level argname body

       ${log}::services

       ${log}::servicename

       ${log}::currentloglevel

       ${log}::delproc command

       ${log}::delproc

       ${log}::delete

       ${log}::trace command

       ${log}::trace on

       ${log}::trace off

       ${log}::trace status ?procName? ?...?

       ${log}::trace add procName ?...?

       ${log}::trace add ?-ns? nsName ?...?

       ${log}::trace remove procName ?...?

       ${log}::trace remove ?-ns? nsName ?...?

____________________________________________________________________________________________________________

DESCRIPTION
       The logger package provides a flexible system for logging messages from different services, at prior-ity priority
       ity levels, with different commands.

       To begin using the logger package, we do the following:


           package require logger
           set log [logger::init myservice]
           ${log}::notice "Initialized myservice logging"

           ... code ...

           ${log}::notice "Ending myservice logging"
           ${log}::delete


       In the above code, after the package is loaded, the following things happen:

       logger::init service
              Initializes the service service for logging.  The service names  are  actually  Tcl  namespace
              names,  so  they are separated with '::'.  When a logger service is initialized, it "inherits"
              properties from its parents.  For instance, if there were a service foo, and  we  did  a  log-ger::init logger::init
              ger::init  foo::bar  (to create a bar service underneath foo), bar would copy the current con-figuration configuration
              figuration of the foo service, although it would of course, also be  possible  to  then  sepa-rately separately
              rately  configure  bar.  If a logger service is initialized and the parent does not yet exist,
              the parent is also created.  The new logger service is initialized with the  default  loglevel
              set with logger::setlevel.

       logger::import ?-all? ?-force? ?-prefix prefix? ?-namespace namespace? service
              Import  the  logger  service commands into the current namespace. Without the -all option only
              the commands corresponding to the  log  levels  are  imported.  If  -all  is  given,  all  the
              ${log}::cmd  style  commands are imported. If the import would overwrite a command an error is
              returned and no command is imported. Use the -force option to force the import  and  overwrite
              existing  commands  without  complaining.   If  the  -prefix option is given, the commands are
              imported with the given prefix prepended to their names.  If the -namespace option  is  given,
              the  commands  are  imported  into the given namespace. If the namespace does not exist, it is
              created. If a namespace without a leading :: is given, it is interpreted as a child  namespace
              to the current namespace.

       logger::initNamespace ns ?level?
              Convenience  command  for  setting  up a namespace for logging. Creates a logger service named
              after the namespace ns (a :: prefix is stripped), imports all the log commands into the names-pace, namespace,
              pace, and sets the default logging level, either to the specified level, or the default level,
              "warn".

       logger::services
              Returns a list of all the available services.

       logger::enable level
              Globally enables logging at and "above" the given level.   Levels  are  debug,  info,  notice,
              warn, error, critical, alert, emergency.

       logger::disable level
              Globally disables logging at and "below" the given level.  Levels are those listed above.

       logger::setlevel level
              Globally  enable  logging  at and "above" the given level. Levels are those listed above. This
              command changes the default loglevel for new loggers created with logger::init.

       logger::levels
              Returns a list of the available log levels (also listed above under enable).

       logger::servicecmd service
              Returns the ${log} token created by logger::init for this service.

       ${log}::debug message

       ${log}::info message

       ${log}::notice message

       ${log}::warn message

       ${log}::error message

       ${log}::critical message

       ${log}::alert message

       ${log}::emergency message
              These are the commands called to actually log a message about an event.  ${log} is  the  vari-able variable
              able obtained from logger::init.

       ${log}::setlevel level
              Enable  logging, in the service referenced by ${log}, and its children, at and above the level
              specified, and disable logging below it.

       ${log}::enable level
              Enable logging, in the service referenced by ${log}, and its children, at and above the  level
              specified.   Note  that this does not disable logging below this level, so you should probably
              use setlevel instead.

       ${log}::disable level
              Disable logging, in the service referenced by ${log}, and its children, at and below the level
              specified. Note that this does not enable logging above this level, so you should probably use
              setlevel instead.  Disabling the loglevel emergency switches logging off for the  service  and
              its children.

       ${log}::lvlchangeproc command

       ${log}::lvlchangeproc
              Set  the  script  to  call when the log instance in question changes its log level.  If called
              without a command it returns the currently registered command. The command gets two  arguments
              appended,  the  old  and the new loglevel. The callback is invoked after all changes have been
              done.  If child loggers are affected, their callbacks are called before  their  parents  call-back. callback.
              back.

                   proc lvlcallback {old new} {
                       puts "Loglevel changed from $old to $new"
                   }
                   ${log}::lvlchangeproc lvlcallback


       ${log}::logproc level

       ${log}::logproc level command

       ${log}::logproc level argname body
              This command comes in three forms - the third, older one is deprecated and may be removed from
              future versions of the logger package.  The current set version takes one argument, a  command
              to  be executed when the level is called.  The callback command takes on argument, the text to
              be logged. If called only with a valid level logproc returns the name of the command currently
              registered  as callback command.  logproc specifies which command will perform the actual log-ging logging
              ging for a given level.  The logger package ships with default commands for  all  log  levels,
              but  with  logproc  it  is possible to replace them with custom code.  This would let you send
              your logs over the network, to a database, or anything else.  For example:

                  proc logtoserver {txt} {
                      variable socket
                      puts $socket "Notice: $txt"
                  }

                  ${log}::logproc notice logtoserver

              Trace logs are slightly different: instead of a plain text argument, the argument provided  to
              the  logproc  is a dictionary consisting of the enter or leave keyword along with another dic-tionary dictionary
              tionary of details about the trace.  These include:

              •      proc - Name of the procedure being traced.

              •      level - The stack level for the procedure invocation (from info level).

              •      script - The name of the file in which the procedure is defined, or an empty string  if
                     defined in interactive mode.

              •      caller  -  The  name  of  the procedure calling the procedure being traced, or an empty
                     string if the procedure was called from the global scope (stack level 0).

              •      procargs - A dictionary consisting of the names of arguments to  the  procedure  paired
                     with values given for those arguments (enter traces only).

              •      status - The Tcl return code (e.g. ok, continue, etc.) (leave traces only).

              •      result - The value returned by the procedure (leave traces only).

       ${log}::services
              Returns a list of the registered logging services which are children of this service.

       ${log}::servicename
              Returns the name of this service.

       ${log}::currentloglevel
              Returns  the  currently  enabled  log level for this service. If no logging is enabled returns
              none.

       ${log}::delproc command

       ${log}::delproc
              Set the script to call when the log instance in question is deleted.  If called without a com-mand command
              mand it returns the currently registered command.  For example:

                  ${log}::delproc [list closesock $logsock]


       ${log}::delete
              This  command  deletes  a particular logging service, and its children.  You must call this to
              clean up the resources used by a service.

       ${log}::trace command
              This command controls logging of enter/leave traces for specified procedures.  It is  used  to
              enable  and  disable  tracing,  query tracing status, and specify procedures are to be traced.
              Trace handlers are unregistered when tracing is disabled.  As a result, there is  not  perfor-mance performance
              mance impact to a library when tracing is disabled, just as with other log level commands.

                proc tracecmd { dict } {
                    puts $dict
                }

                set log [::logger::init example]
                ${log}::logproc trace tracecmd

                proc foo { args } {
                    puts "In foo"
                    bar 1
                    return "foo_result"
                }

                proc bar { x } {
                    puts "In bar"
                    return "bar_result"
                }

                ${log}::trace add foo bar
                ${log}::trace on

                foo

              # Output:
              enter {proc ::foo level 1 script {} caller {} procargs {args {}}}
              In foo
              enter {proc ::bar level 2 script {} caller ::foo procargs {x 1}}
              In bar
              leave {proc ::bar level 2 script {} caller ::foo status ok result bar_result}
              leave {proc ::foo level 1 script {} caller {} status ok result foo_result}


       ${log}::trace on
              Turns on trace logging for procedures registered through the trace add command.  This is simi-lar similar
              lar to the enable command for other logging levels, but allows trace logging to take place  at
              any  level.  The trace logging mechanism takes advantage of the execution trace feature of Tcl
              8.4 and later.  The trace on command will return an error if called from earlier  versions  of
              Tcl.

       ${log}::trace off
              Turns off trace logging for procedures registered for trace logging through the trace add com-mand. command.
              mand.  This is similar to the disable command for other logging levels, but allows trace  log-ging logging
              ging  to take place at any level.  Procedures are not unregistered, so logging for them can be
              turned back on with the trace on command.  There is no overhead imposed by trace  registration
              when trace logging is disabled.

       ${log}::trace status ?procName? ?...?
              This  command  returns  a  list of the procedures currently registered for trace logging, or a
              flag indicating whether or not a trace is registered for one or more specified procedures.

       ${log}::trace add procName ?...?

       ${log}::trace add ?-ns? nsName ?...?
              This command registers one or more procedures for logging of  entry/exit  traces.   Procedures
              can be specified via a list of procedure names or namespace names (in which case all procedure
              within the namespace are targeted by the operation).  By default, each name  is  first  inter-preted interpreted
              preted as a procedure name or glob-style search pattern, and if not found its interpreted as a
              namespace name.  The -ns option can be used to force interpretation of all provided  arguments
              as  namespace names.  Procedures must be defined prior to registering them for tracing through
              the trace add command.  Any procedure or namespace names/patterns that don't match any  exist-ing existing
              ing procedures will be silently ignored.

       ${log}::trace remove procName ?...?

       ${log}::trace remove ?-ns? nsName ?...?
              This command unregisters one or more procedures so that they will no longer have trace logging
              performed, with the same matching rules as that of the trace add command.


IMPLEMENTATION
       The logger package is implemented in such a way as to optimize (for Tcl 8.4 and newer) log procedures
       which  are  disabled.   They are aliased to a proc which has no body, which is compiled to a no op in
       bytecode.  This should make the peformance hit minimal.  If you really  want  to  pull  out  all  the
       stops,  you  can  replace  the  ${log}  token  in  your  code  with  the actual namespace and command
       (${log}::warn becomes ::logger::tree::myservice::warn), so that no variable  lookup  is  done.   This
       puts the performance of disabled logger commands very close to no logging at all.

       The  "object orientation" is done through a hierarchy of namespaces.  Using an actual object oriented
       system would probably be a better way of doing things, or at least provide for a cleaner  implementa-tion. implementation.
       tion.

       The service "object orientation" is done with namespaces.

LOGPROCS AND CALLSTACK
       The logger package takes extra care to keep the logproc out of the call stack.  This enables logprocs
       to execute code in the callers scope by using uplevel or linking to local variables by  using  upvar.
       This may fire traces with all usual side effects.

            # Print caller and current vars in the calling proc
            proc log_local_var {txt} {
                 set caller [info level -1]
                 set vars [uplevel 1 info vars]
                 foreach var [lsort $vars] {
                    if {[uplevel 1 [list array exists $var]] == 1} {
                      lappend val $var <Array>
                    } else {
                      lappend val $var [uplevel 1 [list set $var]]
                    }
                 }
                 puts "$txt"
                 puts "Caller: $caller"
                 puts "Variables in callers scope:"
                 foreach {var value} $val {
                      puts "$var = $value"
                 }
            }

            # install as logproc
            ${log}::logproc debug log_local_var


BUGS, IDEAS, FEEDBACK
       This  document,  and  the  package  it  describes,  will undoubtedly contain bugs and other problems.
       Please  report  such  in  the  category  logger   of   the   Tcllib   SF   Trackers   [http://source -
       forge.net/tracker/? group_id=12883].   Please  also report any ideas for enhancements you may have for
       either package and/or documentation.

KEYWORDS
       log, log level, logger, service

CATEGORY
       Programming tools



log                                                  0.8                                           logger(n)