logger(n)

📦
version 2.0 · 2 versions
, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

🎀 NAME 🎀

okay so this is logger(n) from the Object Oriented logging facility — it's literally the system that controls logging of events. that's the whole vibe. 💖

✨ SYNOPSIS ✨

package require Tcl 8.5 9

package require logger ?0.9.5?

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 🌸

so the logger package is this flexible little system that logs messages from all your different services, at different priority levels, using different commands. it's giving organized. it's giving main character. 💅

to start using logger, bestie, you do this:

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

... code ...

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

and in that code up there, once the package is loaded, here's everything that happens 👇

🫶 logger::init service

Initializes the service service for logging. and no, service names are not just cute little labels — they're actually Tcl namespace names, so they get separated with ::. the service name may not be the empty string, and it can't be only :'s. noted. 🙈

when a logger service is initialized, it "inherits" properties from its parents. like, say you had a service foo, and then you did a logger::init foo::bar (creating a bar service underneath foo) — bar would copy the current configuration of the foo service. though obviously you could also then separately configure bar afterward, slay. and if a logger service is initialized and the parent doesn't exist yet? the parent gets created too. no orphan services here. 💅

the new logger service is initialized with the default loglevel set with logger::setlevel.

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

Imports the logger service commands into the current namespace.

  • without the -all option, only the commands corresponding to the log levels get imported.
  • with -all, all the ${log}::cmd style commands get imported.
  • if the import would overwrite a command, an error is returned and no command is imported. rude, but fair.
  • use the -force option to force the import and overwrite existing commands without complaining. go off.
  • 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 that namespace doesn't exist, it's created. and if a namespace without a leading :: is given, it's interpreted as a child namespace to the current namespace. 🧚

✨ logger::initNamespace ns ?level?

Convenience command for setting up a namespace for logging. it creates a logger service named after the namespace ns (a :: prefix is stripped off), imports all the log commands into the namespace, and sets the default logging level — either as specified by level, or inherited from a service in the parent namespace, or a hardwired default, warn. it's giving one-stop shop. 👑

🌈 logger::services

Returns a list of all the available services. the whole roster. 💜

🔥 logger::enable level

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

💀 logger::disable level

Globally disables logging at and "below" the given level. the levels are those listed above. same list, opposite energy.

⭐ 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. so it's the trendsetter fr fr.

🎀 logger::levels

Returns a list of the available log levels (also listed above under enable). it's the same iconic lineup every time. 💅

🦋 logger::servicecmd service

Returns the ${log} token created by logger::init for this service. your golden ticket. 🎫

🍓 the logging commands

  • ${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 you actually call to log a message about an event. ${log} is the variable you got from logger::init. that's it, that's the whole job. 🌸

💜 ${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. it's a clean cutoff. periodt.

😭 ${log}::enable level

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

heads up bestie: this does not disable logging below this level, so you should probably use setlevel instead. i'm just the messenger. 🙈

🙈 ${log}::disable level

Disable logging, in the service referenced by ${log} and its children, at and below the level specified.

another heads up: this does not enable logging above this level, so you should probably use setlevel instead.

and — major detail — disabling the loglevel emergency switches logging off for the service and its children. like, fully off. 💀

🧚 ${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. and if child loggers are affected, their callbacks are called before their parents callback. hierarchy matters, always.

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 — and the third, older one is deprecated and may be removed from future versions of the logger package. so don't get attached to it, bestie. 😭

the current set version takes one argument: a command to be executed when the level is called. the callback command takes one 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 logging for a given level. the logger package ships with default commands for all log levels, but with logproc you can replace them with custom code. this would let you send your logs over the network, to a database, or literally anything else. sky's the limit. ✨

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 dictionary 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. just the little ones. 🫶

⭐ ${log}::servicename

Returns the name of this service. identity check. 💅

🌸 ${log}::currentloglevel

Returns the currently enabled log level for this service. and if no logging is enabled, it returns none.

🎀 ${log}::delproc command / ${log}::delproc

Set the script to call when the log instance in question is deleted. if called without a command, 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. don't leave your services just lying around, it's not the vibe. 🧹

🦋 ${log}::trace command

This command controls logging of enter/leave traces for specified procedures. it's used to enable and disable tracing, query tracing status, and specify which procedures are to be traced. trace handlers are unregistered when tracing is disabled — so as a result, there is no performance impact to a library when tracing is disabled, just like with the other log level commands. no cap. 💯

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. It's giving the same energy as the enable command for other logging levels, but bestie, it lets trace logging happen at any level. The trace logging mechanism literally uses the execution trace feature of Tcl 8.4 and later.
⚠️ if you call trace on from an earlier version of Tcl, it will return an error. no cap.
  • ${log}::trace off — turns off trace logging for procedures registered for trace logging through the trace add command. Similar to the disable command for other logging levels, but it allows trace logging to take place at any level. Procedures are not unregistered, so you can turn logging back on with the trace on command. And there's no overhead imposed by trace registration when trace logging is disabled. iconic.
  • ${log}::trace status ?procName? ?...? — 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 interpreted 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 existing 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 🛠️

okay so 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 performance 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 implementation.

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 Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for enhancements you may have for either package and/or documentation.

When proposing code changes, please provide unified diffs, i.e the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.

🔑 KEYWORDS 🔑

log, log level, logger, service

🏷️ CATEGORY 🏷️

Programming tools

and that's the whole vibe, bestie 💖 this page is from tcllib, version 0.9.5, manual logger(n) — periodt. 💅

📦 where this page comes from