net.jperf.aop

Annotation Type Profiled

@Retention(value=RUNTIME)
 @Target(value={METHOD,CONSTRUCTOR})
public @interface Profiled

The Profiled annotation is used in concert with the log4j or javalog TimingAspects to enable unobtrusive performance logging. Methods with this annotation, when enabled with the TimingAspect, will automatically have their execution time logged.

Author:

Alex Devine

See Also:

The Perf4J Developer Guide Profiled Annotations Overview

Field Summary

Fields

Modifier and Type	Fields and Description
static String	DEFAULT_TAG_NAME
static String	THRESHOLD_FIELD_NAME

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
boolean	el Whether or not the tag and message elements should support Java Expression Language syntax.
String	level The level to use when logging the StopWatch.
boolean	logFailuresSeparately Whether or not separate tags should be used depending on whether or not the annotated method returns normally or by throwing an exception.
String	logger The name of the logger (either a log4J or java.logging Logger, depending on the Aspect in use at runtime) to use to log the StopWatch.
String	message The optional message element can be used to set a message on the StopWatch that is logged.
boolean	normalAndSlowSuffixesEnabled Default is false.
String	tag The tag that should be set on the StopWatch when the execution time is logged.
long	timeThreshold If the timeThreshold is set to a positive value, then the method execution time will be logged only if took more than timeThreshold milliseconds.

Field Detail

DEFAULT_TAG_NAME

public static final String DEFAULT_TAG_NAME

THRESHOLD_FIELD_NAME

public static final String THRESHOLD_FIELD_NAME

Element Detail

tag

public abstract String tag

The tag that should be set on the StopWatch when the execution time is logged. If not specified then the name of the method being annotated will be used for the tag name.

Returns:

The StopWatch tag

Default:

"@@USE_METHOD_NAME"

message

public abstract String message

The optional message element can be used to set a message on the StopWatch that is logged.

Returns:

The optional message specified for this annotation.

Default:

""

logger

public abstract String logger

The name of the logger (either a log4J or java.logging Logger, depending on the Aspect in use at runtime) to use to log the StopWatch.

Returns:

The logger name, defaults to StopWatch.DEFAULT_LOGGER_NAME

Default:

"net.jperf.TimingLogger"

level

public abstract String level

The level to use when logging the StopWatch. Defaults to INFO. Acceptable values are taken from names of the standard log4j Levels.

Returns:

The level to use when logging the StopWatch

See Also:

log4j Level class

Default:

"INFO"

el

public abstract boolean el

Whether or not the tag and message elements should support Java Expression Language syntax. Setting this to true enables the tag name to be dynamic with respect to the arguments passed to the method being profiled, the return value or exception thrown from the method (if any), and the object on which the method is being called. An Expression Language expression is delimited with curly brackets, and arguments are accessed using the following variable names:

• $0, $1, $2, $3, etc. - the parameters passed to the method in declaration order
• $this - the object whose method is being called - when a static class method is profiled, this will always be null
• $return - the return value from the method, which will be null if the method has a void return type, or an exception was thrown during method execution
• $exception - the value of any Throwable thrown by the method - will be null if the method returns normally

For example, suppose you want to profile the doGet() method of a servlet, with the tag name dependent on the name of the servlet AND the path info (as returned by getPathInfo()) of the request. You could create the following annotation:

 @Profiled(tag = "servlet{$this.servletName}_{$0.pathInfo}", el = true)
 protected void doGet(HttpServletRequest req, HttpServletResponse res) {
 ...
 }
 

If the doGet() method is called with a request whose getPathInfo() method returns "/sub/path", and the servlet's name if "main", then the tag used when logging a StopWatch will be "servletMain_/sub/path".

Returns:

True if expression language support should be enabled, false to disable support - defaults to true.

See Also:

Apache Commons JEXL

Default:

true

logFailuresSeparately

public abstract boolean logFailuresSeparately

Whether or not separate tags should be used depending on whether or not the annotated method returns normally or by throwing an exception. If true, then when the method returns normally the tag name used is tag() + ".success", when the method throws an exception the tag name used is tag() + ".failure".

Returns:

Whether or not failures should be logged under a separate tag, defaults to false.

Default:

false

timeThreshold

public abstract long timeThreshold

If the timeThreshold is set to a positive value, then the method execution time will be logged only if took more than timeThreshold milliseconds. Thus, this value can be used if you only want to log method executions that are unexpectedly slow.

Returns:

The time threshold for logging, in milliseconds.

Default:

-1L

normalAndSlowSuffixesEnabled

public abstract boolean normalAndSlowSuffixesEnabled

Default is false. When set to true, normalSuffix and slowSuffix values are appended to tags based on whether the tags' elapsed time >= timeThreshold or not.

Returns:

Default:

false