com.neeve.trace

Class Tracer

java.lang.Object

com.neeve.trace.Tracer

public final class Tracer
extends Object

The platform trace logger.

Tracers provide facilities to log trace messages. A tracer is bound to one or more loggers and is associated with a level - SEVERE, WARNING, INFO, CONFIG, FINE, FINER and FINEST. The level serves as a level based filter for trace messages being logged. Each trace message is associated with a level and the message is suppressed by the tracer in case the message level is less than the tracer level at the time the message is logged.

By default, a tracer is not bound to any logger. A tracer can be bound to either loggers maintained by TraceLoggerFactory or SLF4J loggers. A user binds and unbinds loggers to and from a tracer via the bind(java.lang.Object) and unbind(java.lang.String) methods. The nv.trace.useSlf4j system property determines whether the tracer gets loggers from SLF4j or TraceLoggerFactory.

A tracer is created with the Tracer.Level.INFO level. A user can change the tracer level either by directly specifying the new level or by specifying a system property from which the new level is obtained. A user requests to log a trace message via the log(java.lang.String, com.neeve.trace.Tracer.Level) method. The method compares the message level with the tracer's level and if greater or equal dispatches the message to all the bound loggers. The messages will be suppressed by the loggers in case the logger level is greater than the tracer level.

The act of binding a tracer to an SLF4J logger will cause the tracer's level to be set using the level of the logger. Programmatic setting of the level will cause the level to be overriden. This allows for the trace level to be set using centralized SLF4J mechanisms and then optionally overriden using environment variables/system properties.

Threading:

This class is safe for concurrent access by multiple threads.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Tracer.Level Defines the various trace levels.

Field Summary

Fields

Modifier and Type	Field and Description
boolean	debug
static Tracer.Level	defaultLevel
boolean	fine
boolean	verbose

Method Summary

Methods

Modifier and Type	Method and Description
void	bind(String name) Bind to a logger by name.
static Tracer	create(String name, Tracer.Level defaultLevel) Create a tracer bound to the specified logger using a specified level
static Tracer	create(Tracer.Level level) Create a tracer using a specified level.
Tracer.Level	getLevel() Get the tracer level.
static Tracer.Level	getLevel(org.slf4j.Logger logger) Get a trace level from an SLF4J logger.
static Tracer.Level	getLevel(Properties props, String name) Get a trace level from a property.
static Tracer.Level	getLevel(Properties props, String name, Tracer.Level defLevel) Get a trace level from a property.
static Tracer.Level	getLevel(String str) Get a trace level from a string.
boolean	isEnabled(Tracer.Level level) Tests whether the given trace level is enabled.
void	log(String msg, Tracer.Level level) Log a trace message.
void	setLevel(Properties props, String name) Set the tracer level from a property.
void	setLevel(String level) Set the tracer level.
void	setLevel(Tracer.Level level) Set the tracer level.
void	setPrefix(String prefix) Deprecated. Trace prefix functionality is no longer supported for performance reasons.
void	unbind(String name) Unbind from a logger.

Methods inherited from class java.lang.Object

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

Field Detail

defaultLevel

public static final Tracer.Level defaultLevel

debug

public volatile boolean debug

fine

public volatile boolean fine

verbose

public volatile boolean verbose

Method Detail

create

public static Tracer create(String name,
            Tracer.Level defaultLevel)

Create a tracer bound to the specified logger using a specified level

Parameters:

logger - The name of the tracer

defaultLevel - The default trace level. All trace messages greater than this trace level will be suppressed. If the logger does not have a configured trace level this default level will be used.

Threading:

This method is safe for concurrent access by multiple threads

create

public static Tracer create(Tracer.Level level)

Create a tracer using a specified level.

Parameters:

level - The tracer level. All trace messages greater than this trace level will be suppressed.

Threading:

This method is safe for concurrent access by multiple threads

getLevel

public static Tracer.Level getLevel(String str)

Get a trace level from a string.

Parameters:

str - The level string.

This method returns a trace level with name equal to the supplied string. The string to level mapping is done case insensitively.

Throws:

IllegalArgumentException - Thrown in case the supplied string does not correspond to one of the defined levels.

Threading:

This method is safe for concurrent access by multiple threads.

getLevel

public static Tracer.Level getLevel(Properties props,
                    String name,
                    Tracer.Level defLevel)

Get a trace level from a property.

Parameters:

props - The property table to use.

name - The property name.

Returns:

Returns the level with the name equal to the specified property value. defLevel is returned in case the property is not found in the table or the property value does not correspond to a valid level.

Threading:

This method is safe for concurrent access by multiple threads.

getLevel

public static Tracer.Level getLevel(Properties props,
                    String name)

Get a trace level from a property.

Parameters:

props - The property table to use.

name - The property name.

Returns:

Returns the level with the name equal to the specified property value. defaultLevel is returned in case the property is not found in the table or the property value does not correspond to a valid level.

Threading:

This method is safe for concurrent access by multiple threads.

getLevel

public static Tracer.Level getLevel(org.slf4j.Logger logger)

Get a trace level from an SLF4J logger.

Parameters:

logger - The logger to map the trace level from.

Returns:

Returns the tracer level corresponding to the tracer level set in an SLF4J logger.

Threading:

This method is safe for concurrent access by multiple threads.

setLevel

public final void setLevel(Tracer.Level level)

Set the tracer level.

Parameters:

level - The level to set

Threading:

This method is safe for concurrent access by multiple threads

setLevel

public final void setLevel(String level)

Set the tracer level.

Parameters:

level - The level to set

Threading:

This method is safe for concurrent access by multiple threads

setLevel

public final void setLevel(Properties props,
            String name)

Set the tracer level from a property.

Parameters:

props - The property table to use.

name - The property name.

This method sets the level of a trace object from a property value. The absence of the property in the provided table or an invalid level name in the property value leaves the trace level unchanged.

Threading:

This method is safe for concurrent access by multiple threads

getLevel

public final Tracer.Level getLevel()

Get the tracer level.

Threading:

This method is safe for concurrent access by multiple threads

isEnabled

public final boolean isEnabled(Tracer.Level level)

Tests whether the given trace level is enabled.

Parameters:

level - The level to check.

Threading:

This method is safe for concurrent access by multiple threads

setPrefix

@Deprecated
public final void setPrefix(String prefix)

Deprecated. Trace prefix functionality is no longer supported for performance reasons.

Parameters:

prefix - The prefix to set.

Threading:

This method is safe for concurrent access by multiple threads

bind

public final void bind(String name)

Bind to a logger by name.

Parameters:

name - The name of the logger to bind to.

Threading:

This method is safe for concurrent access by multiple threads

unbind

public final void unbind(String name)

Unbind from a logger.

Parameters:

name - The name of the logger to unbind from.

Threading:

This method is safe for concurrent access by multiple threads

log

public final void log(String msg,
       Tracer.Level level)

Log a trace message.

Parameters:

msg - The message to log

level - The message level.

This method outputs a line of trace of a trace level if the level is greater than or equal to the trace level of this object.

Threading:

This method is safe for concurrent access by multiple threads