Getting started with nerd.vision for Java applications

Mikey

September 23, 2019

Getting started with nerd.vision for Java applications

Configure your first project and install an agent on your Java Application.

By following the steps in this blog post you will be able to install and configure nerd.vision so you are able to debug your applications in any environment. The process will typically take around 10 minutes. We also have a handy video which demonstrate how to install and configure nerd.vision.

In this blog, getting started will be split into 3 simple steps:

  1. configuring the agent on your application,
  2. configuring a workspace within the nerd.vision Web App,
  3. setting breakpoints to start debugging

These 3 steps are the same in any environment, whether it is hosted locally, in the cloud or in a virtualized platform.


Configuring the client on your application

The nerd.vision Java client is installed as a Java agent, this allows you to install the agent in various ways depending on how you start your Java application.


There are 3 steps required to configure the agent:

  1. Download the nerdvision.jar file
  2. Configure the javaagent property
  3. Launching your Java application

Downloading the nerdvision.jar file

You can download the nerdvision.jar file via directly from https://get.nerd.vision/java/latest/nerdvision.jar or alternatively by a curl / or other web retrieval tool request.


An example curl request would be:


curl "https://get.nerd.vision/java/latest/nerdvision.jar" -o nerdvision.jar

Retrieving your API key

Your API key can be found within the quick start guide within the product, where the key is already contained in a javaagent argument you can copy straight into your java configuration and is also available in the nerd.vision account web app

Configure the javaagent property

Depending on how you are running your application, you can configure the java agent in multiple ways. Below are 3 common examples, however, there will be other configurations you may have to use in your environment.


Configuring the java agent in your environment is done through configuring the -javaagent argument as follows:

-javaagent:{path}/nerdvision.jar=api.key=xxxxxxxxxxxxxxxxxxxx


Directly running through the java command

java -javaagent:{path}/nerdvision.jar=api.key=xxxxxxxxxxxxxxxxxxxx -jar application.jar

Running through maven

export MAVEN_OPTS="-javaagent:{path}/nerdvision.jar=api.key=xxxxxxxxxxxxxxxxxxxx"

Running through a server configuration file

export JAVA_OPTS="$JAVA_OPTS -javaagent:{path}/nerdvision.jar=api.key=xxxxxxxxxxxxxxxxxxxx"


(Optional step) Tagging your clients

You can set a defined list of tags for your client. This could be tags such as  “environment=production”. A tag is made of a key-value pair and can be any combination of key/value you like.


Tags can we add by adding a second parameter directly after the javaagent. An example configuration would be:

-javaagent:{path}/nerdvision.jar=api.key=xxxxxxxxxxxxxxxxxxxx -Dnerdvision.tags=env=production,cluster=1,app=test


These tags can be used to dictate if a breakpoint is fired on a particular client.

Launching your Java application

Start your application through a service or console.


In the log of your application, you will see a code block similar to:

INFO nerdvision: ---------------------------------------------------------
INFO nerdvision: nerdvision - Copyright (C) Intergral GmbH. All Rights Reserved
INFO nerdvision: ---------------------------------------------------------

This indicates that nerd.vision is successfully installed and running.


Configuring a workspace within the NerdVision Web App

At the time of writing this blog post, the only 2 supported repositories are GitLab and GitHub. Support for BitBucket and local file system workspaces is planned and will come in a later version.


Access to Git private or group projects is granted by logging into GitLab / GitHub through NerdVision, public repositories can be added by inputting a Git URL with no authentication required.

Creating a workspace

When configuring a GitLab or GitHub project for the first time, you will be prompted to sign in to either GitLab or GitHub depending on the workspace you are trying to create.



When your accounts have been linked, you will immediately have access to all your projects. You can search your projects or add a URL for any public repository not linked to your account.

Filtering the client's breakpoints will fire on

You can add filters for your clients based on a number of tags. Tags such as hostname, IP address and client name are default options, however, any custom tags such as environment, cluster number or any other key value specified can be used as a filter.

Debugging your application

Now that you have configured your client and workspace, you are ready to debug your application.

Settings breakpoints

You can select your application from the left-hand menu and navigate your application code using the file tree underneath the application selector or searching for a file name.



Clicking on the file name will show the contents of the file in the center panel, here you set breakpoints and see any breakpoints that are already installed. By clicking on the left margin you can create a breakpoint.

Configuring your breakpoints

A breakpoint highlighted in green, whereas a breakpoint in grey indicates it has been disabled. Breakpoints can be configured on the right-hand panel. Where you can disable the breakpoint by clicking the tick or right-clicking to edit or delete the breakpoint.


When editing the breakpoint, you can configure email notifications, set a condition and add watches to your breakpoint.


Email notifications will be sent when breakpoints trigger so you know when to go to nerd.vision and view the breakpoint information

Conditional breakpoints allow you to trigger a breakpoint based on the state of the application, for example breaking only if a variable is set to a specific value. Some examples of conditional breakpoints include:

  • !array.isEmpty()
  • String1.equals”test1234”
  • Int1 > 6

Watches allow you to see the state of a variable or the outcome of a function called on a variable so you can see the information without inspecting the variable tree.

Viewing your fired breakpoints


When your breakpoints fire, you can view the information captured in the breakpoint from the events section of the debugger. This element is at the bottom menu and can be dragged upwards to be given more real estate on your monitor.

Each breakpoint fired is visible on the left-hand side, clicking the event will show all stack frames and the top frame variables. With this data, you can see what caused your breakpoint to fire and the state of all variables at the time it fired.


Mikey

Mikey

Technical Support Engineer and Developer advocate for nerd.vision and other software projects. Background in object-oriented software development and data analysis. Personal hobbies include simulation gaming and watch collecting.