How to apply Kieker in Java EE Environments¶
Depending on the configuration of the JavaEE application to be monitored, different instrumentation technologies (e.g., Spring AOP and SOAP/CXF interceptors) can and should be used. In this page, we show how to use AspectJ to monitor method calls in different JavaEE environments.
Jetty¶
Copy task ':aspectJJar' property 'archiveFileName' into a directory, where it can be accessed
by Jetty, e.g. jetty/kieker/.
Jetty is usually shipped with a configuration file start.ini in which start parameters are defined. Add the following snippet to this file:
--exec
-javaagent:kieker/task ':aspectJJar' property 'archiveFileName'
-Dkieker.monitoring.skipDefaultAOPConfiguration=true
-Daj.weaving.verbose=true
To use a custom Kieker configuration at the given location, the following parameter can be added:
-Dkieker.monitoring.configuration=kieker/kieker.monitoring.properties
Important: Due to a bug in the parser of Jetty, a line ending with .properties is misinterpreted and leads to an exception. We recommend to rename the extension of Kieker’s configuration file.
To use a custom AspectJ configuration at the given location, the following parameter can be added:
-Dorg.aspectj.weaver.loadtime.configuration=file://c:/jetty/kieker/aop.xml
Important: There seems to be problems with relative paths for AspectJ in JavaEE environments. We recommend to use URIs instead.
Tested with JPetStore 6 and Jetty 9.2.2.
JBoss¶
Needs documentation but ` NovaTec’s blog post <http://blog.novatec-gmbh.de/analysing-kieker-with-jboss-dvdstore-sample-application/>`__ may serve as a starting point
Tomcat¶
Copy kieker-1.10_aspectj.jar into a directory, where it can be accessed
by Tomcat, e.g. tomcat/kieker/.
Tomcat is usually shipped with start scripts bin/catalina.(sh|.bat). Add
one of the following snippets to the correct file, depending on your
operation system:
set JAVA_OPTS=%JAVA_OPTS%
-javaagent:%CATALINA_BASE%\kieker\kieker-1.10_aspectj.jar
-Dkieker.monitoring.skipDefaultAOPConfiguration=true
-Daj.weaving.verbose=true
-Dkieker.monitoring.configuration=%CATALINA_BASE%/kieker/kieker.monitoring.properties
-Dorg.aspectj.weaver.loadtime.configuration=...
set JAVA_OPTS=${JAVA_OPTS}
-javaagent:${CATALINA_BASE}\kieker\kieker-1.10_aspectj.jar
-Dkieker.monitoring.skipDefaultAOPConfiguration=true
-Daj.weaving.verbose=true
-Dkieker.monitoring.configuration=${CATALINA_BASE}/kieker/kieker.monitoring.properties
-Dorg.aspectj.weaver.loadtime.configuration=...
…
Needs documentation but ticket/566 may serve as a starting point
Glassfish¶
On Glassfish 4, this can be achieved with adding properties to the domain.xml. The default domain in glassfish is normally called domain0. Let further assume that glassfish was installed in /opt/glassfish-4.0 then the domain.xml file will be located in /opt/glassfish-4.0/glassfish/domains/domain0/config. In that file search for jvm-options. You will find multiple such entries between
<java-config ...>
<jvm-options>...</jvm-options>
</java-config>
After the last entry in that XML environment, add the following lines and adapt the paths to your situation.
<jvm-options>-javaagent:${com.sun.aas.installRoot}/lib/task ':aspectJJar' property 'archiveFileName'</jvm-options>
<jvm-options>-Dkieker.monitoring.skipDefaultAOPConfiguration=true</jvm-options>
<jvm-options>-Daj.weaving.verbose=true</jvm-options>
<jvm-options>-Dkieker.monitoring.configuration=${com.sun.aas.installRoot}/kieker/kieker.monitoring.properties</jvm-options>
<jvm-options>-Dorg.aspectj.weaver.loadtime.configuration=${com.sun.aas.installRoot}/kieker</jvm-options>
WebSphere¶
Needs documentation
JBoss (Wildfly)¶
An alternative approach to run Kieker within a JBoss environment is described here.
Requires:
Kieker-1.13 or above (1.12 and below cause an error in JBoss environments)
Kieker packed as Wildfly module
AspectJ Weaver packed as Wildfly module
Kopiere beide Module einfach in das folgende Wildfly-Verzeichnis:
modules/system/layers/base
Kopiere die Dateien kieker.properties und aop.xml in das
(neue) Verzeichnis “kieker” auf oberster Ebene von Wildfly. Passe nun
den Ausgabepfad von Kieker an und schränke das Instrumentieren auf den
gewünschten Paketnamen ein.
[in der Datei standalone.xml]
Unter dem folgenden, vorhandenen Subsystem müssen die beiden, neuen Module als globale Module registriert werden:
<subsystem xmlns="urn:jboss:domain:ee:4.0">
<global-modules>
<module name="kieker"/>
<module name="org.aspectj"/>
</global-modules>
[in der Datei standalone.conf]
Dort, wo die Systempakete deklariert werden, müssen die folgenden ergänzt werden: org.jboss.logmanager, com.manageengine, org.aspectj, kieker. Du musst im Folgenden nur darauf achten, dass ich Windows-Syntax für die Skriptbefehle genutzt habe.
set "JAVA_OPTS=%JAVA_OPTS% -Djboss.modules.system.pkgs=org.jboss.byteman,org.jboss.logmanager,com.manageengine,org.aspectj,kieker"
set "WILDFLY=I:\Software-Engineering\wildfly-10.1.0.Final"
Weiterhin muss der Aspectjweaver als Javaagent eingetragen werden und für Wildfly entsprechende notwendige Ergänzungen vorgenommen werden, die das Verwenden von AspectJ überhaupt erst ermöglichen:
set "JAVA_OPTS=%JAVA_OPTS% -javaagent:%WILDFLY%/modules/system/layers/base/org/aspectj/main/aspectjweaver.jar"
set "JAVA_OPTS=%JAVA_OPTS% -Djava.util.logging.manager=org.jboss.logmanager.LogManager"
set "JAVA_OPTS=%JAVA_OPTS% -Xbootclasspath/p:%WILDFLY%/modules/system/layers/base/org/jboss/logmanager/main/jboss-logmanager-2.0.4.Final.jar;%WILDFLY%\modules\system\layers\base\kieker\main\task ':mainJar' property 'archiveFileName';%WILDFLY%\modules\system\layers\base\org\aspectj\main\aspectjweaver.jar"
Anschließend werden Einstellungen für das Monitoring durch Kieker vorgenommen:
set "JAVA_OPTS=%JAVA_OPTS% -Dkieker.monitoring.configuration=%WILDFLY%/kieker/kieker.monitoring.1.13.properties"
set "JAVA_OPTS=%JAVA_OPTS% -Dkieker.monitoring.skipDefaultAOPConfiguration=true"
set "JAVA_OPTS=%JAVA_OPTS% -Daj.weaving.verbose=true"
set "JAVA_OPTS=%JAVA_OPTS% -Dorg.aspectj.weaver.loadtime.configuration=file:%WILDFLY%/kieker/aop.xml"
Wenn du nun Wildfly startest, sollten keine Fehler erscheinen. Da das Instrumentieren erst beim Laden der entsprechenden Klassen erfolgt, siehst du an dieser Stelle nur Konsolenausgaben von AspectJ. Erst wenn du das Szenario ausführst, wird Kieker gestartet und der Log-Ordner angelegt und mit Daten gefüllt.