Rookout tutorial for debugging Java applications

A sample app for debugging Java using Rookout.

Helpful links:

Prerequisites

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

Setup

Clone the sample app from this repository:

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

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

export ROOKOUT_TOKEN=[Your Rookout Token]

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

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

Rookout / tutorial-java