README.md

Rookout tutorial for debugging Java applications

A sample app for debugging Java using Rookout.

Helpful links:

• Prerequisites
• Setup
• Usage
• License
• Sign up to Rookout
• Online Documentation

Prerequisites

1. Java 8
2. Docker (optional) - https://www.docker.com/get-docker
3. Jaegar Agent - https://www.jaegertracing.io/docs/getting-started/

Setup

1. Clone the sample app from this repository:

git clone https://github.com/Rookout/tutorial-java.git
cd tutorial-java

2. Set your Rookout Token as an environment variable (for Windows, use set instead of ***export)

export ROOKOUT_TOKEN=[Your Rookout Token]

3. This application uses Jaegar for tracing and requires the Jaegar agent be running before starting the application. The simplest approach to setting this up would be to start the All-In-One pre-built Docker image as described here: https://www.jaegertracing.io/docs/1.22/getting-started/#all-in-one.

4. After starting Jaegar, ensure that the file src/main/resources/application.properties is updated with the host and port of your Jaegar agent. For example:

opentracing.jaeger.udp-sender.host=localhost
opentracing.jaeger.udp-sender.port=6831

• You can omit using Jaeger and remove the opentracing.jaeger.udp-sender.host and opentracing.jaeger.udp-sender.port options from the src/main/resources/application.properties file.

5. Build and run the app

Build and run the app using Gradle:

./gradlew bootJar run

• Optional - Run the app using docker (Java & Gradle are not required)

docker run -p 8080:8080 -e "ROOKOUT_TOKEN=[Your Rookout Token]" rookout/tutorial-java

• No Jaeger? If you just want to take the docker image for a spin without Jaeger then you can disable it by adding the --opentracing.jaeger.enabled=false argument:

docker run -p 8080:8080 -e "ROOKOUT_TOKEN=[Your Rookout Token]" rookout/tutorial-java --opentracing.jaeger.enabled=false

Usage

• Log in to the Rookout IDE.

• Select the server(s) to debug based on the labels in the server selection screen

• Add the source code according to the instructions using the left pane Source View

  More details

  Adding source code

  1. Click on Add source
  2. Choose source control
     • Github
       • Click on Connect
       • Authorize O-Auth
       • Fill Repository Owner
       • Click Repository and choose from the dropdown menu
       • Click Next
       • Choose the desired branch
       • Click View Repository
     • Local FileSystem - Server
       • Click on Setup Server
       • Choose a supported HTTP Server
       • Follow the on-screen instructions

• Open the file src/main/java/com/rookout/tutorial/TodoController.java
  

• Add a Breakpoint to the addTodo function by clicking next the line number in the file viewer

• Click on the Breakpoints tab in the left pane, and you will see the Breakpoint and the line number where you added it - it should be solid purple.
  

  • If this is not the case, check our troubleshooting guide

• Go the the app page - http://localhost:8080/ and add try to add a task to the todo list

• Check the bottom pane Messages and you'll see the dumpframe you just added - it was triggered by the handler of the web page when you accessed it!

Common Pitfalls

• Breakpoint status is pending (hollow with purple outline) -- Connection to the app was not able to be established. Make sure that you inserted the Rookout Token in the right place and that the SDK was properly installed.
• Breakpoing status is disabled (solid grey) -- The breakpoint was disabled from collecting more data due to the limits being hit.
• Brekapoint error -- something went wrong. Check the breakpoint status to get more information on the error type, and for more information go to our [breakpoint status guide][https://docs.rookout.com/docs/breakpoints-status/].

Bug Hunt

Great! You're now ready to start debugging, let's start by having some fun with our bug hunt - follow the instructions to try out some basic use cases.

Want to learn more ?

• Our documentation for more information
• our deployment examples for platform-specific integration examples

License

APACHE 2