JVM SDK Instrumentation
This page will dive into the nitty gritty details on installing Rookout under various configurations.
If you are encountering any difficulties with deploying Rookout, this is the place to look.
JVM
The JVM SDK provides the ability to fetch debug data from a running application in real time.
It can be download directly to the target system by running the following command:
curl -L "https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=com.rookout&a=rook&v=LATEST" -o rook.jar
Setup
Java Agent
Simply add the Rookout SDK as a Java Agent to your environment:
# Add the Rookout Java Agent to your application using an environment variable
export JAVA_TOOL_OPTIONS="-javaagent:$(pwd)/rook.jar -DROOKOUT_TOKEN=[Your Rookout Token]"
# Optional, see Labels section below Projects
export ROOKOUT_LABELS=env:dev
# Add the Java Agent, token and the labels to your application using command line
java -javaagent:$(pwd)/rook.jar MyClass -DROOKOUT_TOKEN=[Your Rookout Token] -DROOKOUT_LABELS=env:dev
Using in OSGi apps
To use Rookout in an OSGi application, the Rookout package must be whitelisted (delegated) to the OSGi container.
This is done by setting the following JVM options
org.osgi.framework.bootdelegation=com.rookout.*
This is done where all other JVM options are set (via -D flags, JVM_OPTS, etc.).
SDK Configuration
Configuration is performed using OS Environment Variables or Java System Properties.
Environment Variable | Default Value | Description |
---|---|---|
ROOKOUT_TOKEN | None | The Rookout token for your organization. Should be left empty if you are using a Rookout ETL Controller |
ROOKOUT_LABELS | {} | A dictionary of key:value labels for your application instances. Use k:v,k:v format for environment variables |
ROOKOUT_COMMIT | None | String that indicates your git commit or a branch name |
ROOKOUT_REMOTE_ORIGIN | None | String that indicates your git remote origin |
ROOKOUT_CONTROLLER_HOST | None | If you are using a Rookout ETL Controller, this is the hostname for it |
ROOKOUT_CONTROLLER_PORT | None | If you are using a Rookout ETL Controller, this is the port for it |
ROOKOUT_PROXY | None | URL to proxy server |
ROOKOUT_DEBUG | False | Set to True to increase log level to debug |
ROOKOUT_SOURCES | None | Source information (see below) |
Test connectivity
To make sure the SDK was properly installed and test your configuration (environment variables only), run the following command:
java -jar rook.jar
Debug Information
Rookout requires your application to be built with debug information. While most modern Java build tools such as Gradle
and Maven
do so by default, some such as Ant
and javac
do not.
Here a few examples on how to configure them:
<javac srcdir="${source-directory}"
destdir="${classes-directory}"
classpath="${lib-directory}"
debug="true"
/>
javac -g MyClass.java
Packaging Sources
To make sure you are collecting data from the source line where you have set the breakpoint, include your source files within your JAR/WAR/EAR library.
jar {
from sourceSets.main.allSource
}
<resources>
<resource>
<directory>${basedir}/src/main/java</directory>
</resource>
</resources>
<jar destfile="${target.dir}/my-app.jar">
<fileset dir="${target.dir}/classes" />
<fileset dir="${source-directory}" includes="**/*.java"/>
</jar>
Source information
Use the environment variable ROOKOUT_SOURCES
to initialize the SDK with information about the sources used in your application.
ROOKOUT_SOURCES is a semicolon-separated list with either a source control repository and revision information, or a path on the local filesystem to a JAR file.
Example
ROOKOUT_SOURCES=https://github.com/Rookout/Rookout#afe123;/path/to/lib.jar
To load source information from a jar file, you need to add the following attributes to the JAR manifest:
Rookout-Repository
: Repository URL
Rookout-Revision
: Revision identifier
Application Detection
Rookout uses the semi-documented sun.java.command
system property to identify your application and display it for within the Web Application.
Some Java based runtimes such as Jsvc don't set it as expected. If missing, you may set it manually:
jsvc -Dsun.java.command=my.main.class
Dynamic loading in running JVM process
The Rookout SDK can be loaded to a running JVM process by following these steps:
- Export the destination process ID as
ROOKOUT_TARGET_PID
as environment variable. - Export all of your configuration as environment variables (
ROOKOUT_TOKEN
for example) - Run the following command line.
ROOKOUT_TARGET_PID=1234 java -jar rook.jar
Supported Versions
Implementation | Versions |
---|---|
Oracle Java | 7u111+, 8u74+, 11u4+, 12 |
OpenJDK | 7u111+, 8u74+, 11u4+, 12, 13 |
AdoptOpenJDK | 8u74+, 11u4+, 12 |
Amazon Corretto | 8u74+, 11u4+ |
The following languages are officially supported: Java, Scala, Kotlin, Groovy, ColdFusion.
If the environment you are trying to debug is not mentioned in the list above, be sure to let us know: https://www.appdynamics.com/support/
Dependencies
None.
Serverless and PaaS deployments
Integrating with Serverless
When integrating Rookout into a Serverless application, you should explicitly flush the collected information.
This requires using the including the Rookout SDK API as a dependency and packaging it with your applications.
For more information, please check out our deployment-examples.
Note: Adding the Rookout SDK will slow down your Serverless cold-start times. Please make sure your timeout is no less then 30 seconds.
Building
In some Serverless environments (such as AWS Lambda), the tools.jar library is missing and must be included within your package as well.
Illegal reflective access warning
When using JVM versions 9 and above, you may see the following harmless warning:
WARNING: An illegal reflective access operation has occurred
WARNING: Illegal reflective access by com.rookout.rook.Processor.NamespaceSerializer
WARNING: Please consider reporting this to the maintainers of com.rookout.rook.Processor.NamespaceSerializer
WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
WARNING: All illegal access operations will be denied in a future release
This warning is generated by the latest protobuf implementation for Java.
You can safely ignore this warning.