Java
How to setup recording & monitoring for Java applications
- Maven / Gradle project configuration:
- RevDeBug is compatible with Maven 2.0.1 or newer
- RevDeBug is compatible with Gradle 5.0 or newer
- Java application version 8 or higher
To enable RevDeBug in your Java application you will need to:
Add the following lines to the super pom.xml / build.gradle file in the Java application main node:
Maven
Gradle
pom.xml
<project>
...
<repositories>
<repository>
<id>rdb-repo</id>
<name>RevDeBug Maven Repo</name>
<url>https://release.revdebug.com/repository/maven</url>
</repository>
</repositories>
...
</project>
build.gradle
repositories {
maven {
url 'https://nexus.revdebug.com/repository/maven'
}
}
Add the following lines to the super pom.xml / build.gradle file in the Java application main node:
Maven
Gradle
pom.xml
<project>
...
<dependencies>
<dependency>
<groupId>com.revdebug</groupId>
<artifactId>revdebug-compiler</artifactId>
<version>7.0.2</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>com.revdebug</groupId>
<artifactId>revdebug-runtime</artifactId>
<version>7.0.2</version>
</dependency>
...
</project>
build.gradle
dependencies {
compileOnly 'com.revdebug:revdebug-compiler:7.0.2'
annotationProcessor 'com.revdebug:revdebug-compiler:7.0.2' // Required after Gradle v4.10.2
implementation 'com.revdebug:revdebug-runtime:7.0.2'
}
//* Use compile keyword instead of implementation for Gradle version less than 3.0
//* Use compile keyword instead of compileOnly for Gradle version less than 2.12
For spring-boot projects additional exclusion in pom.xml is needed (without it build time dependencies will be packaged with application):
pom.xml
<project>
...
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<excludes>
<exclude>
<groupId>com.revdebug</groupId>
<artifactId>revdebug-compiler</artifactId>
</exclude>
</excludes>
</configuration>
</plugin>
...
</plugins>
</build>
...
</project>
RevDeBug can be easily added to all projects in the working directory. But if you want, you can add RevDeBug to the selected subset. In the examples below substitute
[SERVER_ADDRESS]
for actual fully qualified domain address of RevDeBug server.Maven - single project
Maven - many projects
Gradle
pom.xml
<project>
...
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<configuration>
<compilerArgs>
<arg>-Xplugin:RevDeBugCompiler</arg>
<arg>-AREVDEBUG_SERVER_HOSTNAME=[SERVER_ADDRESS]</arg>
<arg>-AREVDEBUG_SECURE_CONNECTION=false</arg>
</compilerArgs>
<source>1.8</source>
<target>1.8</target>
</configuration>
</plugin>
</plugins>
...
</project>
pom.xml
<project>
<build>
...
<pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<configuration>
<compilerArgs>
<arg>-Xplugin:RevDeBugCompiler</arg>
<arg>-AREVDEBUG_SERVER_HOSTNAME=[SERVER_ADDRESS]</arg>
<arg>-AREVDEBUG_SECURE_CONNECTION=false</arg>
</compilerArgs>
<source>1.8</source>
<target>1.8</target>
</configuration>
</plugin>
</plugins>
</pluginManagement>
...
</build>
</project>
build.gradle
compileJava {
options.compilerArgs = [
"-Xplugin:RevDeBugCompiler",
"-AREVDEBUG_SERVER_HOSTNAME=[SERVER_ADDRESS]",
"-AREVDEBUG_SECURE_CONNECTION=false"
]}
If you are using a
spring-boot-starter-parent
, make sure its version is equal to or greater than 1.4.0, earlier versions are not supported.pom.xml
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.4.0.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
Starting from Java 17 you need to add additional exports to JVM arguments.
Requirements:
- Gradle 7+ or Maven
For Gradle, create or edit
gradle.properties
in your project's root directory by adding: gradle.properties
org.gradle.jvmargs = --add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED \
--add-exports=jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED \
--add-exports=jdk.compiler/com.sun.tools.javac.main=ALL-UNNAMED \
--add-exports=jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED \
--add-exports=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED \
--add-exports=jdk.compiler/com.sun.tools.javac.processing=ALL-UNNAMED \
--add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED \
--add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED \
--add-exports=jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED \
--add-exports=jdk.compiler/com.sun.tools.javac.comp=ALL-UNNAMED
Adding --add-exports directly in
build.gradle
file wouldn't work - it is a known Gradle issue (link).For Maven, create
.mvn
directory in the project's root directory (or in the user's $HOME
directory) and create a jvm.config
file in it with the following contents:jvm.config
--add-exports jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.main=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.processing=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.comp=ALL-UNNAMED
There are configurable fields in the connection section of RevDeBug DevOps Monitor:
Name | Explanation |
---|---|
-AREVDEBUG_SERVER_HOSTNAME | Usage: Fully qualified domain name (recommended) or an IP address of RevDeBug Server. RevDeBug compile process sends metadata needed to replay recordings of program execution to this server - controlled by 'UPLOAD_METADATA' settings (by default it sends the metadata). When several RevDeBug Servers should receive the emitted metadata, put all of their fully qualified domain names separated by a comma. Example value: 'revdebug.my-company.com'. Can be overridden at runtime using environment variable 'recordServerAddress'. |
-AREVDEBUG_SERVER_PORT | Usage: TCP/IP port number of RevDeBug Server. Defaults to 42734 and should not be changed in most cases. Example value: '42734'. Can be overridden at runtime using environment variable 'recordServerPort'. |
-AREVDEBUG_APPLICATION_NAME | Usage: Additional distinguishing name for desktop tray companion application. In most cases, not set up during compile time but overridden at the runtime level through environment variables. Example value: 'MainProcessingService-user1'. Can be overridden at runtime using environment variable 'applicationName'. |
-AREVDEBUG_SOLUTION_NAME | Usage: Main application name - application will be listed under this name on the applications list on the RevDeBug Server 'Monitor' tab. Usually not needed to be set as it is automatically determined from on-disk directory name of the project. Example value: 'MainProcessingService'. Can be overridden at runtime using environment variable 'solutionName'. |
-AREVDEBUG_RELEASE_NAME | Usage: Human readable release name corresponding to current commit id. Could be set to a tag name or manually incremented version number in the build file. Example value: '1.3'. Can be overridden at runtime using environment variable 'releaseDisplayName'. |
-AREVDEBUG_GIT_HASH | Usage: First eight characters of current git commit id (hash). Determined automatically, but in case it would not find the correct repository eg. when using submodules, it can be overridden by configuration in the build file. Example value: 'f937b564'. Can be overridden at runtime using environment variable 'releaseId'. |
-AREVDEBUG_METADATA_PATH | Usage: Absolute directory path where RevDeBug metadata files will be placed. Determined automatically, no need to change in most cases. Example value: (in gradle build file) '${projectDir}/build/'. |
-AREVDEBUG_UPLOAD_METADATA | Usage: Control whether the metadata generated during compilation will be sent to the server at the end of compilation. Sending metadata is required to be able to open and replay recordings. Defaults to 'true'. Example value: 'false'. |
-AREVDEBUG_SECURE_CONNECTION | Usage: Forces and expects a secure connection to RevDeBug Server. This value need to correspond to a TLS settings on the RevDeBug server. On values mismatch RevDeBut will fail to operate. Defaults to 'false'. Example value: 'true'. Can be overridden at runtime using environment variable 'forceTLS'. |
-AREVDEBUG_DISABLE_ALL | Usage: Disables RevDeBug compilation. If set to true it would make project compilation behave as RevDeBug compile-time dependency would not be added at all. Could be useful for local development and can be set via environment variable on a developers' machines. Defaults to 'false'. Example value: 'false'. Can be overridden at runtime using environment variable 'REVDEBUG_OFF'. |
-AREVDEBUG_TRACE_LOG_ERROR | Usage: Enables or disables (default) treating log.error(...) calls as if exception/error would be thrown.The message passed to log.error call will be used as an exception/error message and have associated stacktrace corresponding to the log.error call. Required to set up also REVDEBUG_LOG_ERROR_CLASS to a fully qualified name of the logger class used and REVDEBUG_LOG_ERROR_METHOD to a method used to denote an error message (ie. 'error' or 'severe'). Disabled automatically when REVDEBUG_TRACE_BEFORE_LINE is disabled. Example value: 'false'. |
-AREVDEBUG_LOG_ERROR_CLASS | Define logger class to use for log.error() recording. Must be fully qualified name, such as ‘org.apache.log4j.Logger’ |
-AREVDEBUG_LOG_ERROR_METHOD | Usage: Method name used to log error message while using the selected logger class (using REVDEBUG_LOG_ERROR_CLASS option). Example value: 'error' or 'severe'. |
-AREVDEBUG_USAGE | Usage: Displays RevDeBug Java library settings and their descriptions and immediately stops the compilation. Example value: 'true'. |
-AREVDEBUG_RDBDISPLAY_AUTOGEN | Usage: Instructs RevDeBug Compiler to automatically generate RDBDisplay rules for every class in the compiled project (i.e. which compiler compiles) that overrides toString() method. This requires a performance consideration as RevDeBug will use implemented toString() methods to serialize the state of the object during runtime. Defaults to 'false' (do not generate RDBDisplay rules automatically) Example value: 'true'. |
-AREVDEBUG_RDBDISPLAY_AUTOGEN_ARRAYS | Usage: Instructs RevDeBug Compiler to automatically generate RDBDisplay rules for displaying first elements of arrays of basic types (Integers, String, etc). This requires a performance consideration as RevDeBug will serialize the state of those arrays during runtime. Defaults to 'false' (do not generate RDBDisplay rules automatically) Example value: 'true'. |
-AREVDEBUG_RDBDISPLAY_AUTOGEN_COLLECTIONS | Usage: Instructs RevDeBug Compiler to automatically generate RDBDisplay rules for displaying first elements of collections of basic types (Integers, String, etc). This requires a performance consideration as RevDeBug will serialize the state of those/ collections during runtime. Defaults to 'false' (do not generate RDBDisplay rules automatically) Example value: 'true'. |
-AREVDEBUG_LARGE_METHODS | Usage: Comma separated list of fully qualified method names that are too large for fullRevDeBug instrumentation. Methods matching the list will only receive basic instrumentation of recording input parameters and method enter and method exit events. Methods declared in an inline declared classes cannot be matched, ie. Object obj = new ClassXYZ() { public method() { ... } }. List items should be regular expressions. White spaces around separating commas are ignored. Example: 'com.hello.World.getApplicationStatus()' - will match getApplicationStatus() method in the 'World' class of 'com.hello package'. |
-AREVDEBUG_EXCLUDE_METHODS | Usage: Comma separated list of fully qualified methods to be excluded from being recorded. Methods declared in an inline declared classes cannot be matched, ie. Object obj = new ClassXYZ() { public method() { ... } }. List items should be regular expressions. White spaces around separating commas are ignored. Example: 'com.hello.World.getApplicationStatus()' - will match getApplicationStatus() method in the 'World' class of 'com.hello package'. |
-AREVDEBUG_EXCLUDE_CLASSES | Usage: Comma separated list of classes to be excluded from being recorded. List items should be regular expressions. White spaces around separating commas are ignored. Example: 'com.hello.World' will match World class file or '.*Options$' will match every class name ending with 'Options' (keep in mind the dollar sign is escaped - in most cases it needs to be). |
-AREVDEBUG_JAVAC_VERSION | Usage: Major version of Java C Compiler RevDeBug should assume. Normally it is automatically determined, but can be overridden. Example value: '9'. |
-AREVDEBUG_ANNOTATED_ONLY | Usage: Instruments every class and method (the default and a 'false' value) or (when 'true') only classes that are annotated with @RevDeBugConfig.Annotation.Include. |
-AREVDEBUG_TRACE_ON_ERROR | Usage: Enables (default) or disables catching and recording of unhandled exceptions. Example value: 'true'. |
-AREVDEBUG_TRACE_RETURN | Usage: Enables (default) or disables recording of values of return statements. Example value: 'true'. |
-AREVDEBUG_TRACE_VALUES | Usage: Enables (default) or disables recording of changes/mutations or variables' values. Example value: 'true'. |
-AREVDEBUG_TRACE_BEFORE_LINE | Usage: Enables (default) or disables recording of before line execution events. Disabling will also disable recording of log.error(...) calls as errors (separately toggleable using REVDEBUG_TRACE_LOG_ERROR) Example value: 'true'. |
-AREVDEBUG_TRACE_METHOD_CALLS | Usage: Enables (default) or disables recording of method calls and their parameters. Example value: 'true'. |
-AREVDEBUG_TRACE_LOOPS | Usage: Enables (default) or disables recording of before line execution events. Disabling will also disable recording of log.error(...) calls as errors (separately toggleable using REVDEBUG_TRACE_LOG_ERROR) Example value: 'true'. |
-AREVDEBUG_TRACE_SWITCH | Usage: Enables (default) or disables recording of switch statement variables. Example value: 'true'. |
-AREVDEBUG_TRACE_COND | Usage: Enables (default) or disables recording of conditional statements. Example value: 'true'. |
-AREVDEBUG_TRACE_METHOD_PARAMS | Usage: Enables (default) or disables recording of mathods/lambdas parameters. Example value: 'true'. |
-AREVDEBUG_TRACE_LAMBDAS | Usage: Enables (default) or disables recording of lambdas in general. Example value: 'true'. |
-AREVDEBUG_LOG_LEVEL | Usage: Sets the verbosity of RevDeBug logging during compilation process. Defaults to INFO. Increase to VERBOSE or even ALL when encountering compilation process failures with RevDeBug. Can be overridden at runtime using environment variable 'REVDEBUG_VERBOSE'. |
-AREVDEBUG_STOP_ON_METADATA_NOT_SENT | Usage: Control whether the compilation process should hard stop when metadata would not be sent to the server Sending metadata is required to be able to open and replay recordings. Defaults to 'false'. Example value: 'true'. |
-AREVDEBUG_AUTH_TOKEN | Usage: Authorization token obtained from RevDeBug Server. If not set or with a wrong value and RevDeBug Server was set to require authorization from application will cause RevDeBug metadata and recordings to fail when sending to the Server. Example value: '2c2f4a6ea2ea467382fabaee59106907'. Can be overridden at runtime using environment variable 'authorizationToken'. |
-AREVDEBUG_MAX_RECORDING_SIZE | Usage: Size of the recording buffer limiting how many 'statements' are kept in the recording counting back from the moment the recording was stored (i.e. an error usually). Defaults to 1000. Example value: '5000'. Can be overridden at runtime using environment variable 'backlogSize'. |
-AREVDEBUG_SKIP_SETUP_GENERATION | Usage: Disables creation of RevDeBug.setup resource containing default runtime configuration for application. Only useful when used in conjunction with RevDeBug APM Agent which can supply the configuration from its own or when setting all required settings manually by environment variables (not recommended). Defaults to 'false'. Example value: 'true'. |
- Unzip the archive and modify config/agent.config file
- agent.service_name set to your app name
- collector.backend_service set to point to your record server instance
- agent.force_tls set to
true
if your RevDeBug DevOps Monitor instance has been configured to work with an SSL certificate.
- Attach unzipped agent to your app with java argument: -javaagent:[Path-to-unzipped-agent]/agent/skywalking-agent.jar
Once the application is compiled with RevDeBug it reports exceptions and traces to the RevDeBug server. If you want to put RevDeBug in standby mode you have to set those environment variables and restart your application:
SW_AGENT_ACTIVE=false
REVDEBUG_RECORDING_MODE=noop
If you want to completely disable RevDeBug from attaching to your application during compilation you can set the following environment variable on your build server and recompile:
REVDEBUG_DISABLE_ALL=true
Last modified 21d ago