RevDeBug
RevDeBug main website
Search
⌃K
Links

Java

How to setup recording & monitoring for Java applications

Requirements

To enable RevDeBug in your Java application you will need to:

Adding RevDeBug repository

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'
}
}
​

Adding RevDeBug dependency

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>

Configure the connection to RevDeBug Server

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"
]}
​

Spring Boot Starter Parent

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>

Additional configuration for Java 17+

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

Settings overview

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'.

Add RevDeBug Java Agent

  • Download java-agent from nexus repo (link)
  • 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

Controlling RevDeBug with environment variables

Put RevDeBug in Standby mode

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

Disable RevDeBug from instrumenting application

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
​
Previous
Data masking
Next
API
Last modified 21d ago