org.erights.e.develop.trace
Class Trace

Untamed: This might better be called TraceCache, but the name is retained
for backward compatibility. The major purpose of this class is to
hold a cache of a relevant trace priority threshold, so that a user
of the trace code can quickly decide whether to call a trace
method. Methods on this object communicate with the master
TraceController, which does the real work of tracing.

Secondarily, this class holds some miscellaneous functions useful in
tracing.

FROM_DEFAULT
When referring to thresholds, are we talking about those
from the default thresholds, or ones specific to a subsystem?
XXX These could be interned strings, but interning didn't work
right in 1.0.4.

ON

Enabled: Set this to false to compile out all tracing. This also has
to be set in TraceDummies.java

error

public boolean error

Enabled: 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

Enabled: Warning messages are not as serious as errors, but they're
signs of something odd.

world

public boolean world

Enabled: World messages track the state of the world as a whole. They
are the sort of things world operators ask for specifically, such
as "can you tell me when someone connects." They should appear
only occasionally, much less often than once per second. This is
probably the level used for the on-disk log in the shipped
version.

usage

public boolean usage

Enabled: Usage messages are used to answer the question "who did what up
to the point the bug appeared?" ("Spock entered Azturf. Spock
started trading with Kyra. Kyra gave Spock a diamond in exchange
for a lump of coal. Kyra spoke.") They are also used to collect
higher-level usability information. This is the level probably
used for the transient log in the shipped version; during
development, we can set the on-disk log to this level.

event

public boolean event

Enabled: 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 gestures for usability testing, and to log information for
testers.

debug

public boolean debug

Enabled: 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

Enabled: Verbose messages provide even more detail than debug. They're
probably mainly used when first getting the code to work.

timing

public boolean timing

Enabled: Timing messages are for performance tuning. Whether timing
messages are logged is independent of the values of all the
other trace variables.

NUM_ACCEPTORS

acceptorNames

ERROR

public static final int ERROR

The different trace thresholds. See the Trace class for
documentation. There is space between the levels for
expansion. If you add or delete a level, you must change
Trace.java to add new methods and variables.

WARNING

public static final int WARNING

WORLD

public static final int WORLD

USAGE

public static final int USAGE

EVENT

public static final int EVENT

DEBUG

public static final int DEBUG

VERBOSE

public static final int VERBOSE

MAX_THRESHOLD

public static final int MAX_THRESHOLD

TIMING

public static final int TIMING

As a late addition, there's a "timing" boolean that can be
set orthogonally from the thresholds. The above values are
overloaded: thresholds, but also identifiers for the original message
(was it sent with errorm(), etc.). The TIMING "level" is added
for the latter purpose, but it has nothing to do with thresholds.
To avoid confusion, it's set negative, thus below the minimum
threshold.

FROM_DEFAULT

public static final int FROM_DEFAULT

When referring to thresholds, are we talking about those
from the default thresholds, or ones specific to a subsystem?
XXX These could be interned strings, but interning didn't work
right in 1.0.4. That is, two "default" strings weren't eq.

setTraceMode

shred

Enabled: 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 will likely be symptoms of
bugs, one will be able to have them traced.

timingm

Enabled: These methods take an Object in addition to a string.
Note that logging a null object is the same thing as logging
no object at all. (Fix this if anyone complains.)

touch

static void touch()

Invoking this method causes this class to be loaded, which
causes all the static trace objects to be defined. In
particular, Trace.trace becomes defined. That's convenient, in that
it allows more tracing of the tracing startup itself.