| Visible Workings > Ruby-Trace User's Guide |
The Ruby-Trace
User's Guide |
Glossary |
Buffer: A ring buffer that contains trace messages. One kind of destination. An object of class BufferDestination (see the API).
Connector: An object that connects topics with particular themes to destinations. It governs the routing of trace messages. It may be a topic itself and have level methods. It may obey environment commands. See also the API.
Debugging theme: The default theme. It has these levels: error, warning, announce (for significant events in the life of the program), event (typically used to log traffic across subsystem or external interfaces), debug, and verbose.
Destination: a place where trace messages end up. The built-in destinations are a ring buffer, a logfile on disk, and standard output. Destination is a class in the API.
Environment command: Environment commands come from an environment variable, typically TRACEENV. Within the value of that variable, environment commands are separated by spaces, commas, or colons. Environment commands have effect only on topics belonging to connectors that obey that environment variable. The different commands are explained here.
Level: Themes consist of a list of levels. The higher levels are expected to appear less often. (See the debugging theme for a sample list of levels.) Levels are used to construct level methods. They label trace messages.
Level method: A topic with a particular theme has a level method for each level in the theme. When the level method is called, it checks the threshold for each of the destinations to which the topic is connected. If that threshold allows, the destination is sent a trace message.
Theme: Essentially a list of levels. Themes allow trace messages to be tagged with meaningful names. For example, when the debugging theme is used, the level names are "warning", "debug", and the like. If customer usage were being tracked, a usage theme might have levels like "task", "feature", and "gesture".
Threshold: Each topic may route trace messages to one or more destinations. Each topic/destination connection has an associated threshold. Messages with levels below the threshold are not passed on to the destination.
Topic: A topic is a way of grouping trace messages sent from many locations in the code. Suppose you're using tracing for debugging. You might want to see much detail for all messages from the accounting subsystem, little detail elsewhere. By having all the accounting messages sent to the accounting topic, you can control the amount of detail by adjusting that topic's threshold. Or, if you are using tracing for tracking usage, you might send all trace messages about context-sensitive help to the 'help' topic.
Trace message: A trace message is the result of invoking a level method on a topic. (When the context is clear, this invocation is called "sending a trace message".) If the threshold allows, the trace message is routed to a destination, where it may eventually become text viewed by a human. This text is also called a trace message.
Trace object: A synonym for connector. Used in the chapter on simple programs before the term "connector" is introduced.
Glossary |
Please send comments on this document to marick@visibleworkings.com. The ruby-trace mailing list is at at http://groups.yahoo.com/group/ruby-trace.
Copyright © 2001 by Brian Marick. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, draft v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub).