# TIP 390: A Logging API for Tcl
	Author:		Jeff Rogers <dvrsn@diphi.com>
	State:		Draft
	Type:		Project
	Tcl-Version:	8.7
	Created:	27-Oct-2011
	Vote:		Pending
	Post-History:	
-----

# Abstract

This TIP proposes a standard API for logging in Tcl applications, both at the
Tcl and C level.

# Rationale

Logging is needed in most applications.  There is no standard, documented
logging API in Tcl, for either Tcl or C code, leading most people to roll
their own. The TIP proposes a standard Tcl and C API that handles the most
common logging functions.

The default implementation of the logger should just print the message \(with
substitutions performed as if with **format**\) to the standard error
channel.

# Specification

 1. **Tcl\_Log**\(_interp_, _level_, _message_, ...\)

	 > This is the main C api call; it logs the formatted message at the specified
   loglevel. If interp is specified, it operates within the context of that
   interp; if NULL then it logs in a maner not associated with any interp.

 2. **Tcl\_SetLogLevel**\(_interp_, _level_\)

	 > Instructs the logging system to set the loglevel to the given value.  Legal
   levels are TCL\_LOG\_DEV, TCL\_LOG\_DEBUG, TCL\_LOG\_INFO, TCL\_LOG\_NOTICE,
   TCL\_LOG\_WARNING, TCL\_LOG\_ERROR, TCL\_LOG\_FATAL, TCL\_LOG\_BUG

 3. **Tcl\_SetLogHandler**\(_interp_, _logHandler_\)

		    struct Tcl_LogHandler {
		        Tcl_LogHandlerProc(interp, level, message, ...)
		        Tcl_SetLogLevelProc(interp, level)
		    }

	 > Installs a new loghandler for a specified interp or globally.  If no log
   handler is installed, the default action is to print the formatted message
   on standard error if the message level is equal to or greater than the
   loglevel; in the context of an interp the default action is to call the
   configured log handler \(which does the same thing by default\)

 4. **interp logger** ?_loggerCommandFragment_?

	 > Gets or sets the log handler for an interp.  The log handler will have
   these arguments appended on invoke: _level message args_

 5. **log** _level message_

	 > Tcl equivalent of **Tcl\_Log**.

# Copyright

This document has been placed in the public domain.

