org.elkoserver.util.trace
Class Trace

java.lang.Object
  org.elkoserver.util.trace.Trace

public class Trace
extends Object

This class provides output to the server log on behalf of a particular server subsystem. A number of frequently used trace subsystem objects are available as static variables on this class. Users can also create additional trace objects as needed for their own purposes.

A collection of trace priority thresholds, represented by a group of boolean variables, control which trace messages are actually output. These variables can be tested by a user of the trace code to quickly decide whether to call a trace method (thus helping avoid the costs of procedure call and string manipulation in cases where no output would be generated anyway).

Field Summary

static Trace	comm Trace object for the 'comm' (communications) subsystem.
boolean	debug Flag to control tracing of debug messages.
static int	DEBUG "Debug" level trace threshold
boolean	error Flag to control tracing of error messages.
static int	ERROR "Error" level trace threshold
boolean	event Flag to control tracing of event messages.
static int	EVENT "Event" level trace threshold
static int	MESSAGE "Message" level trace threshold.
static int	METRICS "Metrics" level (not thresholded)
static Trace	none Trace object for the 'none' subsystem.
static int	NOTICE "Notice" level (not thresholded)
static boolean	ON This variable statically controls whether tracing is enabled at all.
static Trace	runq Trace object for the 'runq' (run queue) subsystem.
static Trace	startup Trace object for the 'startup' subsystem.
static Trace	timers Trace object for the 'timers' subsystem.
static Trace	trace Trace object for the 'trace' subsystem itself.
boolean	usage Flag to control tracing of usage messages.
static int	USAGE "Usage" level trace threshold
boolean	verbose Flag to control tracing of verbose messages.
static int	VERBOSE "Verbose" level trace threshold
boolean	warning Flag to control tracing of warning messages.
static int	WARNING "Warning" level trace threshold
boolean	world Flag to control tracing of world messages.
static int	WORLD "World" level trace threshold

Method Summary

static String	byteArrayToASCII(byte[] buf, int offset, int length) Convert an array of bytes into a string suitable for output to a log.
void	debugi(String message) Output an informational log message at DEBUG level.
void	debugm(String message) Output a log message at DEBUG level.
void	debugm(String message, Object obj) Output a log message at DEBUG level, with attached object.
void	debugReportException(Throwable th, String message) Log an exception event at DEBUG level.
void	errori(String message) Output an informational log message at ERROR level.
void	errorm(String message) Output a log message at ERROR level.
void	errorm(String message, Object obj) Output a log message at ERROR level, with attached object.
void	errorReportException(Throwable th, String message) Log an exception event at ERROR level.
void	eventi(String message) Output an informational log message at EVENT level.
void	eventm(String message) Output a log message at EVENT level.
void	eventm(String message, Object obj) Output a log message at EVENT level, with attached object.
void	eventReportException(Throwable th, String message) Log an exception event at EVENT level.
void	fatalError(String message) Exit reporting a fatal error.
void	fatalError(String message, Object obj) Exit reporting a fatal error, with attached object (usually but not necessarily a Throwable of some kind).
void	metrics(String type, int id) Output an unvalued metrics message.
void	metrics(String type, int id, boolean value) Output a boolean-valued metrics message.
void	metrics(String type, int id, double value) Output a floating point-valued metrics message.
void	metrics(String type, int id, int value) Output an integer-valued metrics message.
void	metrics(String type, int id, JSONLiteral value) Output a JSON object-valued metrics message.
void	metrics(String type, int id, JSONObject value) Output a JSON object-valued metrics message.
void	metrics(String type, int id, long value) Output a long-valued metrics message.
void	metrics(String type, int id, String value) Output a string-valued metrics message.
void	msgi(Object conn, boolean inbound, Object msg) Output a log message describing a comm message.
void	noticei(String message) Output an informational log message at NOTICE level (which is unblockable).
void	setThreshold(int threshold) Set the logging threshold.
void	shred(Throwable ex, String reason) Record a Throwable along with a trace message.
Trace	subTrace(String subSubsystem) Obtain a Trace object based on another Trace object.
static Trace	trace(String subsystem) Obtain the Trace object for a given subsystem.
void	usagei(String message) Output an informational log message at USAGE level.
void	usagem(String message) Output a log message at USAGE level.
void	usagem(String message, Object obj) Output a log message at USAGE level, with attached object.
void	usageReportException(Throwable th, String message) Log an exception event at USAGE level.
void	verbosei(String message) Output an informational log message at VERBOSE level.
void	verbosem(String message) Output a log message at VERBOSE level.
void	verbosem(String message, Object obj) Output a log message at VERBOSE level, with attached object.
void	verboseReportException(Throwable th, String message) Log an exception event at VERBOSE level.
void	warningi(String message) Output an informational log message at WARNING level.
void	warningm(String message) Output a log message at WARNING level.
void	warningm(String message, Object obj) Output a log message at WARNING level, with attached object.
void	warningReportException(Throwable th, String message) Log an exception event at WARNING level.
void	worldi(String message) Output an informational log message at WORLD level.
void	worldm(String message) Output a log message at WORLD level.
void	worldm(String message, Object obj) Output a log message at WORLD level, with attached object.
void	worldReportException(Throwable th, String message) Log an exception event at WORLD level.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NOTICE

public static final int NOTICE

"Notice" level (not thresholded)

See Also:

Constant Field Values

METRICS

public static final int METRICS

"Metrics" level (not thresholded)

See Also:

Constant Field Values

ERROR

public static final int ERROR

"Error" level trace threshold

See Also:

Constant Field Values

WARNING

public static final int WARNING

"Warning" level trace threshold

See Also:

Constant Field Values

WORLD

public static final int WORLD

"World" level trace threshold

See Also:

Constant Field Values

USAGE

public static final int USAGE

"Usage" level trace threshold

See Also:

Constant Field Values

EVENT

public static final int EVENT

"Event" level trace threshold

See Also:

Constant Field Values

MESSAGE

public static final int MESSAGE

"Message" level trace threshold. Essentially the save as "Event", but flagged differently in log entries.

See Also:

Constant Field Values

DEBUG

public static final int DEBUG

"Debug" level trace threshold

See Also:

Constant Field Values

VERBOSE

public static final int VERBOSE

"Verbose" level trace threshold

See Also:

Constant Field Values

ON

public static final boolean ON

This variable statically controls whether tracing is enabled at all. By compiling against a version of this class that has this variable set to false and testing this prior to invoking trace operations, one can arrange to have the trace calls removed by the compiler.

See Also:

Constant Field Values

error

public boolean error

Flag to control tracing of error messages. Error messages report on some internal error. They don't necessarily lead to the system stopping, but they might. Error messages are always logged.

warning

public boolean warning

Flag to control tracing of warning messages. Warning messages are not as serious as errors, but they're signs of something odd.

world

public boolean world

Flag to control tracing of world messages. World messages track the state of the world as a whole. They are the sort of things server operators ask for specifically, such as "can you tell me when someone connects." They should appear only occasionally.

usage

public boolean usage

Flag to control tracing of usage messages. Usage messages are used to answer the question "who did what up to the point the bug appeared?" They are also used to collect higher-level usability information.

event

public boolean event

Flag to control tracing of event messages. Event messages describe the major actions the system takes in response to user actions. The distinction between this category and debug is fuzzy, especially since debug is already used for many messages of this type. However, it can be used to log specific user actions for usability testing, and to log information for testers.

debug

public boolean debug

Flag to control tracing of debug messages. Debug messages provide more detail for people who want to delve into what's going on, probably to figure out a bug.

verbose

public boolean verbose

Flag to control tracing of verbose messages. Verbose messages provide even more detail than debug. They're probably mainly used when first getting code to work.

comm

public static Trace comm

Trace object for the 'comm' (communications) subsystem. In particular, message traffic is logged when the trace level of this object is set to EVENT or above.

none

public static Trace none

Trace object for the 'none' subsystem. This is a trace object that will never log under any circumstances. It can be passed in method parameters that require a trace object but you don't want any tracing to result.

runq

public static Trace runq

Trace object for the 'runq' (run queue) subsystem. This is used for log messages from the event queue manager.

startup

public static Trace startup

Trace object for the 'startup' subsystem. This is used for log messages that need to be generated as a part of server boot.

timers

public static Trace timers

Trace object for the 'timers' subsystem. This is used for log messages from the clock/timer API.

trace

public static Trace trace

Trace object for the 'trace' subsystem itself.

Method Detail

trace

public static Trace trace(String subsystem)

Obtain the Trace object for a given subsystem. The Trace object will be manufactured if it does not already exist.

Parameters:

subsystem - The name of the subsystem of interest.

Returns:

a Trace object for the given subsystem.

subTrace

public Trace subTrace(String subSubsystem)

Obtain a Trace object based on another Trace object. The new trace object will acquire its initial threshold settings based on its parent.

Parameters:

subSubsystem - A name tag that will be appended to this trace object's subsystem name.

Returns:

a a Trace object derived from this trace object.

setThreshold

public void setThreshold(int threshold)

Set the logging threshold.

Parameters:

threshold - The new threshold value.

byteArrayToASCII

public static String byteArrayToASCII(byte[] buf,
                                      int offset,
                                      int length)

Convert an array of bytes into a string suitable for output to a log. Such data is usually UTF-8, or ASCII (which is a subset of UTF-8), but sometimes it is just random binary data. If we simply use Java's built-in charset conversion, it can produce illegible binary crud in the server log. Instead we convert it ourselves, rendering printable ASCII bytes as the chars they represent and non-printable bytes as hexadecimal character literal escape sequences. This will have the downside of sometimes rendering valid Unicode chars funny, but nearly everything we actually care about seeing when debugging is printable ASCII.

Parameters:

buf - Byte array containing data to be converted.

offset - Index of start position to convert.

length - Number of bytes to convert.

Returns:

a String rendering the indicated bytes in a legible form suitable for loggging.

fatalError

public void fatalError(String message)

Exit reporting a fatal error.

Parameters:

message - The error message to die with.

fatalError

public void fatalError(String message,
                       Object obj)

Exit reporting a fatal error, with attached object (usually but not necessarily a Throwable of some kind).

Parameters:

message - The error message to die with.

obj - Object to report with message.

shred

public void shred(Throwable ex,
                  String reason)

Record a Throwable along with a trace message.

To ensure that exceptional conditions are only being ignored for good reason, we adopt the discipline that a caught exception should:

1) be rethrown
2) cause another exception to be thrown instead
3) be ignored, in a traceable way, for some stated reason

Only by making #3 explicit can we distinguish it from accidentally ignoring the exception. An exception should, therefore, only be ignored by asking a Trace object to shred it. This request carries a string that justifies allowing the program to continue normally following this event. As shredded exceptions may be symptoms of bugs, this will enable them to be traced.

The reason for the shredding is logged at verbose level.

Parameters:

ex - The exception to shred.

reason - A string justifying this.

metrics

public void metrics(String type,
                    int id,
                    String value)

Output a string-valued metrics message.

Parameters:

type - Type tag

id - Session id number to associate with the message.

value - The value to record.

metrics

public void metrics(String type,
                    int id,
                    int value)

Output an integer-valued metrics message.

Parameters:

type - Type tag

id - Session id number to associate with the message.

value - The value to record.

metrics

public void metrics(String type,
                    int id,
                    long value)

Output a long-valued metrics message.

Parameters:

type - Type tag

id - Session id number to associate with the message.

value - The value to record.

metrics

public void metrics(String type,
                    int id,
                    double value)

Output a floating point-valued metrics message.

Parameters:

type - Type tag

id - Session id number to associate with the message.

value - The value to record.

metrics

public void metrics(String type,
                    int id)

Output an unvalued metrics message.

Parameters:

type - Type tag

id - Session id number to associate with the message.

metrics

public void metrics(String type,
                    int id,
                    boolean value)

Output a boolean-valued metrics message.

Parameters:

type - Type tag

id - Session id number to associate with the message.

value - The value to record.

metrics

public void metrics(String type,
                    int id,
                    JSONLiteral value)

Output a JSON object-valued metrics message.

Parameters:

type - Type tag

id - Session id number to associate with the message.

value - The value to record.

metrics

public void metrics(String type,
                    int id,
                    JSONObject value)

Output a JSON object-valued metrics message.

Parameters:

type - Type tag

id - Session id number to associate with the message.

value - The value to record.

noticei

public void noticei(String message)

Output an informational log message at NOTICE level (which is unblockable).

Parameters:

message - The message string

msgi

public void msgi(Object conn,
                 boolean inbound,
                 Object msg)

Output a log message describing a comm message.

Parameters:

conn - The connection over which the message was sent or received.

inbound - True if the message was received, false if it was sent

msg - The message itself that is to be logged

debugi

public void debugi(String message)

Output an informational log message at DEBUG level.

Parameters:

message - The message to write to the log.

debugm

public void debugm(String message)

Output a log message at DEBUG level.

Parameters:

message - The message to write to the log.

debugm

public void debugm(String message,
                   Object obj)

Output a log message at DEBUG level, with attached object.

Parameters:

message - The message to write to the log.

obj - Object to report with message.

debugReportException

public void debugReportException(Throwable th,
                                 String message)

Log an exception event at DEBUG level.

Parameters:

th - The exception to log

message - An explanatory message to accompany the log entry.

errori

public void errori(String message)

Output an informational log message at ERROR level.

Parameters:

message - The message to write to the log.

errorm

public void errorm(String message)

Output a log message at ERROR level.

Parameters:

message - The message to write to the log.

errorm

public void errorm(String message,
                   Object obj)

Output a log message at ERROR level, with attached object.

Parameters:

message - The message to write to the log.

obj - Object to report with message.

errorReportException

public void errorReportException(Throwable th,
                                 String message)

Log an exception event at ERROR level.

Parameters:

th - The exception to log

message - An explanatory message to accompany the log entry.

eventi

public void eventi(String message)

Output an informational log message at EVENT level.

Parameters:

message - The message to write to the log.

eventm

public void eventm(String message)

Output a log message at EVENT level.

Parameters:

message - The message to write to the log.

eventm

public void eventm(String message,
                   Object obj)

Output a log message at EVENT level, with attached object.

Parameters:

message - The message to write to the log.

obj - Object to report with message.

eventReportException

public void eventReportException(Throwable th,
                                 String message)

Log an exception event at EVENT level.

Parameters:

th - The exception to log

message - An explanatory message to accompany the log entry.

usagei

public void usagei(String message)

Output an informational log message at USAGE level.

Parameters:

message - The message to write to the log.

usagem

public void usagem(String message)

Output a log message at USAGE level.

Parameters:

message - The message to write to the log.

usagem

public void usagem(String message,
                   Object obj)

Output a log message at USAGE level, with attached object.

Parameters:

message - The message to write to the log.

obj - Object to report with message.

usageReportException

public void usageReportException(Throwable th,
                                 String message)

Log an exception event at USAGE level.

Parameters:

th - The exception to log

message - An explanatory message to accompany the log entry.

verbosei

public void verbosei(String message)

Output an informational log message at VERBOSE level.

Parameters:

message - The message to write to the log.

verbosem

public void verbosem(String message)

Output a log message at VERBOSE level.

Parameters:

message - The message to write to the log.

verbosem

public void verbosem(String message,
                     Object obj)

Output a log message at VERBOSE level, with attached object.

Parameters:

message - The message to write to the log.

obj - Object to report with message.

verboseReportException

public void verboseReportException(Throwable th,
                                   String message)

Log an exception event at VERBOSE level.

Parameters:

th - The exception to log

message - An explanatory message to accompany the log entry.

warningi

public void warningi(String message)

Output an informational log message at WARNING level.

Parameters:

message - The message to write to the log.

warningm

public void warningm(String message)

Output a log message at WARNING level.

Parameters:

message - The message to write to the log.

warningm

public void warningm(String message,
                     Object obj)

Output a log message at WARNING level, with attached object.

Parameters:

message - The message to write to the log.

obj - Object to report with message.

warningReportException

public void warningReportException(Throwable th,
                                   String message)

Log an exception event at WARNING level.

Parameters:

th - The exception to log

message - An explanatory message to accompany the log entry.

worldi

public void worldi(String message)

Output an informational log message at WORLD level.

Parameters:

message - The message to write to the log.

worldm

public void worldm(String message)

Output a log message at WORLD level.

Parameters:

message - The message to write to the log.

worldm

public void worldm(String message,
                   Object obj)

Output a log message at WORLD level, with attached object.

Parameters:

message - The message to write to the log.

obj - Object to report with message.

worldReportException

public void worldReportException(Throwable th,
                                 String message)

Log an exception event at WORLD level.

Parameters:

th - The exception to log

message - An explanatory message to accompany the log entry.