AspectJ Instrumentation Example¶
AspectJ allows to weave code into the byte code of Java applications and libraries without requiring manual modifications of the source code. We show below how to use Java annotation to instrument code and how to do this without any change of the source code. Kieker includes the AspectJ-based monitoring probes
OperationExecutionAspectAnnotation,
OperationExecutionAspectAnnotationServlet,
OperationExecutionAspectFull
, andOperationEx-ecutionAspectFullServlet
which can be woven into Java applications at compile time and load time.
These probes monitor method executions and corresponding trace and
timing information. The probes with the postfixServlet
store a
session identifier within theOperationExecutionRecord
. When the
probes with name elementAnnotation
are used, methods to be
monitored must be annotated by the Kieker
annotation@OperationExecutionMonitoringProbe
.
This section demonstrates how to use the AspectJ-based probes to monitor traces based on the Bookstore application.
The Java sources of the example presented in this section, as well as a
pre-compiled binary, can be found in
theexamples/userguide/ch5-trace-monitoring-aspectj/
directory of
the binary release.
The directory structure used in this example is as follows:
examples
userguide/
ch5–trace-monitoring-aspectj/
build/
Directory for the Java class fileslibs/
BookstoreApplication.jar
gradle/
wrapper/
Directory for the gradle wrapperlib/
Directory for the needed librariestask ':aspectJJar' property 'archiveFileName'
src/kieker/examples/userguide/ch5bookstore/
Directory for the source code filesBookstore.java
BookstoreHostnameRewriter.java
BookstoreStarter.java
Catalog.java
CRM.java
src-resources/META-INF/
Directory for the configuration filesaop.xml
aop-event.xml
aop-full.xml
kieker.monitoring.adaptiveMonitoring.conf
kieker.monitoring.properties
build.gradle
gradlew
gradlew.bat
README.txt
The jar-filetask ':aspectJJar' property 'archiveFileName'
already includes the
AspectJ weaver, which is registered with the JVM and weaves the
monitoring instrumentation into the Java classes. It will be configured
based on the configuration fileaop.xml
, for which a working sample
file is provided in the example’sMETA-INF/
directory. Instead of
registering thetask ':aspectJJar' property 'archiveFileName'
as an agent to
the JVM, theaspectjweaver-1.8.2.jar
can be used. In this case,
thetask ':mainJar' property 'archiveFileName'
needs to be added to the classpath.
Instrumentation by Annotation¶
Once the necessary files have been copied to the example directory, the
source code can be instrumented with the
annotation OperationExecutionMonitoringProbe
. The below listing
shows how the annotation is used.
1 2 3 4 5 6 7 8 9 10 11 12 | public class Bookstore { private final Catalog catalog = new Catalog(); private final CRM crm = new CRM(this.catalog); @OperationExecutionMonitoringProbe public void searchBook() { this.catalog.getBook(false); this.crm.getOffers(); } } |
As a first example, each method of the Bookstore application will be
annotated. The annotation can be used to instrument all methods except
for constructors.The aop.xml
file has to be modified to specify
the classes to be considered for instrumentation by the AspectJ weaver.
The listing below shows the modified configuration file.
1 2 3 4 5 6 7 8 9 | <!DOCTYPE aspectj PUBLIC "-//AspectJ//DTD//EN" "http://www.aspectj.org/dtd/aspectj_1_5_0.dtd"> <aspectj> <weaver options=""> <include within="kieker.examples.userguide.ch5bookstore..*"/> </weaver> <aspects> <aspect name="kieker.monitoring.probe.aspectj.operationExecution.OperationExecutionAspectAnnotation"/> </aspects> </aspectj> |
Line 5 tells the AspectJ weaver to consider all classes inside the
example package. AspectJ allows to use wildcards for the definition of
classes to include, e.g.,
<include within=”bookstoreTracing.Bookstore∗”/>
to weave all classes
with the prefix Bookstore
located in
apackage bookstoreTracing
. Line 9 specifies the aspect to be woven
into the classes. In this case, the Kieker
probe OperationExecutionAspectAnnotation
is used. It requires that
methods intended tobe instrumented are annotated by
@OperationExecutionMonitoringProbe
, as mentioned before. Below we
show how to compile and run the annotated Bookstore application.
The aop.xml
must be located in a META-INF/
directory in the
classpath – in this case the build/
directory. The AspectJ weaver
has to be loaded as a so-called Java-agent. It weaves the monitoring
aspect into the byte code of the Bookstore application. Additionally,
a kieker.monitoring.properties
is copied to
the META-INF/
directory. This configuration file may be adjusted
as desired.
Unix version:
1 2 3 4 5 6 7 8 9 | mkdir build/META−INF javac src/kieker/examples/userguide/ch5bookstore/∗.java \ -d build/ -classpath lib/task ':aspectJJar' property 'archiveFileName' cp src−resources/META−INF/aop.xml build/META−INF/ cp src−resources/META−INF/kieker.monitoring.properties build/META−INF/ java -javaagent:lib/task ':aspectJJar' property 'archiveFileName' \ -classpath build/ kieker.examples.userguide.ch5bookstore.BookstoreStarter |
Windows version:
1 2 3 4 5 6 7 8 9 10 | mkdir build\META−INF javac src\kieker\examples\userguide\ch5bookstore\∗.java -d build -classpathlib\task ':aspectJJar' property 'archiveFileName' copy src−resources\META−INF\aop.xml build\META−INF\ copy src−resources\META−INF\kieker.monitoring.properties build\META−INF\ java -javaagent:lib\task ':aspectJJar' property 'archiveFileName' -classpath build\kieker.examples.userguide.ch5bookstore.BookstoreStarter |
After a complete run of the application, the monitoring files should appear in the same way as described in manual instrumentation including the additional trace information.
Instrumentation without Changing the Code¶
Instrumentation without annotations AspectJ-based instrumentation
without using annotations is quite simple. It is only necessary to
modify the fileaop.xml
, as shown in the following listing. In the
example directory a prepared version is provided named aop-full.xml
.
1 2 3 4 5 6 7 8 9 | <!DOCTYPE aspectj PUBLIC "-//AspectJ//DTD//EN" "http://www.aspectj.org/dtd/aspectj_1_5_0.dtd"> <aspectj> <weaver options=""> <include within="kieker.examples.userguide.ch5bookstore..*"/> </weaver> <aspects> <aspect name="kieker.monitoring.probe.aspectj.operationExecution.OperationExecutionAspectFull"/> </aspects> </aspectj> |
The alternative aspect OperationExecutionAspectFull
is being
activated in line 9. As indicated by its name, this aspect makes sure
that every method within the included classes/packages will be
instrumented and monitored. Line 5 illustrates how to limit the
instrumented methods to those of the classBookstoreStarter
.
This configuration file may be adjusted as desired. Please note here the
aop-full.xml
is copied to the META-INF
folder and renamed to
aop.xml
, as this is necessary for AspectJ to find the aspect
configuration.
Unix version:
1 2 3 4 5 6 7 8 9 10 | mkdir build/META−INF javac src/kieker/examples/userguide/ch5bookstore/∗.java \ -d build/ -classpath lib/task ':aspectJJar' property 'archiveFileName' cp src−resources/META−INF/aop-full.xml build/META−INF/aop.xml cp src−resources/META−INF/kieker.monitoring.properties build/META−INF/ java -javaagent:lib/task ':aspectJJar' property 'archiveFileName' \ -classpath build/ kieker.examples.userguide.ch5bookstore.BookstoreStarter |
Windows version:
1 2 3 4 5 6 7 8 9 10 | mkdir build\META−INF javac src\kieker\examples\userguide\ch5bookstore\∗.java -d build -classpathlib\task ':aspectJJar' property 'archiveFileName' copy src−resources\META−INF\aop-full.xml build\META−INF\aop.xml copy src−resources\META−INF\kieker.monitoring.properties build\META−INF\ java -javaagent:lib\task ':aspectJJar' property 'archiveFileName' -classpath build\kieker.examples.userguide.ch5bookstore.BookstoreStarter |
After a complete run of the application, the monitoring files should appear in the same way as described in manual instrumentation including the additional trace information.