trace: github.com/seehuhn/trace Index | Files

package trace

import "github.com/seehuhn/trace"

Package trace implements a simple tracing framework which can be used to diagnose run-time problems.

Sending Messages

Code using this framework can emit diagnostic messages using the trace.T() function. Example:

trace.T("client/setup", trace.PrioError,
        "failed to connect to server %q, using offline mode", serverName)

The first argument in this call is a path which gives information about the origin of the message, the second argument indicates the importance of the message. Both, the path and the priority are used to decide which listeners receive the correponding message. The following arguments, a format string and additional optional arguments, are passed to fmt.Sprintf to compose the message reported to the listeners registered for the given message path.

Receiving Messages

Listeners can subscribe to messages, either for a given path or for all paths, using the Register() method. A minimum priority for messages to be delivered can be used. Example:

func printTrace(t time.Time, path string, prio trace.Priority, msg string) {
        fmt.Printf("%s:%s: %s\n", t.Format("15:04:05.000"), path, msg)
}

func main() {
        listener := trace.Register(printTrace, "client", trace.PrioAll)
        // ... code which calls trace.T()
        listener.Unregister()
}

This code installs printTrace as a handler which receives all messages sent for the path "client" and its sub-paths.

Index

Package Files

callers.go doc.go flags.go listener.go trace.go

func Callers Uses

func Callers() []string

Callers is a helper function to get a stack trace from within a trace listener function. The result is a list of strings, each giving a Go source file name, followed by a colon and a line number within the source file. The first string corresponds to the call of trace.T(), the last string corresponds to the program's main function. If Callers() is called from outside a trace listener, a run-time panic is triggered.

func T Uses

func T(path string, prio Priority, format string, args ...interface{})

T is used to send a trace message and to the registered listeners.

The argument 'path' indicates which component of the program the caller of T belongs to; the value consists of slash separated, hierarchical fields where the first field, by convention, should coincide with the package name. 'path' must not be the empty string and must neither start nor end with a slash.

The argument 'prio' indicates the priority of the message, higher values indicating higher importance. Messages with positive priority values (corresponding to the pre-defined priorities PrioCritical, PrioError, and PrioInfo) should be phrased in a way that they make sense to a person not familiar with the source code of the program. Messages of priority PrioDebug or higher should consist of a single line.

The argument 'format' and the following, optional arguments are passed to fmt.Sprintf to compose the message reported to the listeners registered for the given message path.

type Listener Uses

type Listener func(t time.Time, path string, prio Priority, msg string)

Listener is the type of functions which can be registered using the Register() function.

type ListenerHandle Uses

type ListenerHandle uint

ListenerHandle is the type returned by Register(). The returned values can be used in Unregister() to remove previously installed handlers.

func Register Uses

func Register(listener Listener, path string, prio Priority) ListenerHandle

Register adds the function 'listener' to the list of functions receiving trace messages.

The argument 'path' restricts the messages received to messages corresponding to the given path and its sub-paths (see the description of 'T' for details). The value must neither start nor end in a slash. The empty string can be used to receive trace messages from all paths.

The listener will receive all messages of priority 'prio' and higher. The value PrioAll can be used for 'prio' to receive all messages. The value PrioInfo can be used to receive all messages for the given path which do not require familiarity with the program source code.

func (ListenerHandle) Unregister Uses

func (handle ListenerHandle) Unregister()

Unregister removes a previously installed listener. The argument 'handle' must be the value returned by the corresponding call to Register()

type Priority Uses

type Priority int32

Priority is the type used to denote message priorities. The higher the value, the more important the message is.

const (
    // PrioCritical indicates a one-line message emitted just before
    // the program has to be aborted because of an internal error.
    // The message should contain information which may help to
    // determine the underlying problem and should be phrased in a way
    // that the text makes sense to a person not familiar with the
    // source code of the program.  A message of priority PrioCritical
    // could, for example, give the name of a missing but required
    // configuration file.
    PrioCritical Priority = 2000

    // PrioError indicates a non-fatal, one-line message which is
    // likely to be of interest to an administrator of the system
    // running the program.  The message should be phrased in a way
    // that the text makes sense to a person not familiar with the
    // source code of the program.  A message of priority PrioError
    // could, for example, indicate that the program runs with reduced
    // functionality because of a configuration error.
    PrioError Priority = 1000

    // PrioInfo indicates one-line status messages which allow to
    // track the activity of the program, and which may be of interest
    // to a person trying to understand the normal operation of the
    // program.  The message should be phrased in a way that the text
    // makes sense to a person not familiar with the source code of
    // the program.  A message of priority PrioInfo could, for
    // example, indicate that a configuration file has been read.
    PrioInfo Priority = 0

    // PrioDebug indicates a one-line message which is likely to be of
    // interest to a developer of the program.  The message text may
    // assume that the reader is familiar with the source code of the
    // program.  A message of priority PrioDebug could, for example,
    // indicate that a library returned an unexpected error code.
    PrioDebug Priority = -1000

    // PrioVerbose indicates a message which may be of interest to a
    // developer of the program.  The message text may assume that the
    // reader is familiar with the source code of the program, and the
    // text may consist of several lines.  A message of priority
    // PrioDebug could, for example, give the contents of a remote
    // server response to assist with debugging of network protocol
    // incompatibility.
    PrioVerbose Priority = -2000

    // PrioAll is used to register a listener which receives all
    // messages for a given path.
    PrioAll Priority = math.MinInt32
)

Package trace imports 8 packages (graph) and is imported by 2 packages. Updated 2016-07-21. Refresh now. Tools for package owners.