Documentation

Documentation

    ›SDK Setup

    General

    • Getting Started
    • Use Cases

    SDK Setup

    • Introduction
    • JVM
    • .NET
    • Python
    • Ruby
    • Node.js
    • Deployment Examples

    Debug Session

    • Debug session setup
    • Source Repositories
    • Labels

    Breakpoints

    • Breakpoints
    • Breakpoint Status
    • Conditional breakpoints
    • Breakpoint Tasks

    Organizations

    • Organizations

    Advanced

    • Integrations
    • Collaborations
    • Controller Setup
    • Scripting Reference
    • OpenTracing
    • Keyboard Shortcuts

    More

    • Software Versions
    • Controller License
    Edit

    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:

    Environment Variable
    Command Line
    # 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 ValueDescription
    ROOKOUT_TOKENNoneThe 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_COMMITNoneString that indicates your git commit or a branch name
    ROOKOUT_REMOTE_ORIGINNoneString that indicates your git remote origin
    ROOKOUT_CONTROLLER_HOSTNoneIf you are using a Rookout ETL Controller, this is the hostname for it
    ROOKOUT_CONTROLLER_PORTNoneIf you are using a Rookout ETL Controller, this is the port for it
    ROOKOUT_PROXYNoneURL to proxy server
    ROOKOUT_DEBUGFalseSet to True to increase log level to debug
    ROOKOUT_SOURCESNoneSource 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:

    Ant
    javac
    <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.

    Gradle
    Maven
    Ant
    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:

    1. Export the destination process ID as ROOKOUT_TARGET_PID as environment variable.
    2. Export all of your configuration as environment variables (ROOKOUT_TOKEN for example)
    3. Run the following command line.
    ROOKOUT_TARGET_PID=1234 java -jar rook.jar
    

    Supported Versions

    ImplementationVersions
    Oracle Java7u111+, 8u74+, 11u4+, 12
    OpenJDK7u111+, 8u74+, 11u4+, 12, 13
    AdoptOpenJDK8u74+, 11u4+, 12
    Amazon Corretto8u74+, 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.

    ← Introduction.NET →
    • JVM
    • Setup
      • Java Agent
    • SDK Configuration
    • Test connectivity
    • Debug Information
    • Packaging Sources
    • Source information
    • Application Detection
    • Dynamic loading in running JVM process
    • Supported Versions
    • Dependencies
    • Serverless and PaaS deployments
      • Integrating with Serverless
      • Building
    • Illegal reflective access warning
    Documentation
    General

    WelcomeUse Cases
    SDK Setup

    Setup IntroJvm SetupDotnet SetupPython SetupRuby SetupNode SetupDeployment Examples
    Debug Session

    Debug Session SetupSource ReposProjects Labels
    Breakpoints

    BreakpointsBreakpoints StatusBreakpoints ConditionalBreakpoints Tasks
    Organizations

    Organizations
    Advanced

    IntegrationsCollaborationsController SetupBreakpoints ReferenceOpen TracingKeyboard Shortcuts
    More

    Sdk DigestsLicense
    Other

    Status
    GitHub - RookoutFacebook - RookoutTwitter - RookoutLinkedIn - Rookout