Installation

Edited on November 23, 2016

Quick Client Setup

  1. Download the zip archive of our latest release in the Release section of our github repository or via direct download from the Download section on our web page .

  2. Extract it to a local folder.

  3. Simply double click the startClient.bat, .command or .sh file from the bin folder, depending whether you're using windows , mac os or linux. If Java isn't on your PATH, then set an explicit JRE or JDK Path inside the startClient script, as shown in the commentary. If Java is not installed on your machine, you can download it here and install it.

  4. Once the GUI opens, click the "+" sign to choose a connector.

connection screen

We strongly recommend using the JMX connector as a starter, as it is one of the simplest ways to connect to a remote JVM and use the sampler mode of djigger.

Direct JMX Connection

Only requirement : the following flags need to be set on the command line the remote JVM :

-Dcom.sun.management.jmxremote
-Dcom.sun.management.jmxremote.port={your_jmx_port} 
-Dcom.sun.management.jmxremote.authenticate=false 
-Dcom.sun.management.jmxremote.ssl=false
  1. Choose JMX and enter the hostname & JMX port number of the remote JVM which you want to monitor. If a user and password authentication is used on the remote JVM side, you need to provide those as well.

  2. Connect and start sampling by hitting the Play button and then refreshing the view by clicking the button with the circling blue arrows.

Agent mode

  1. Set the following command line flags on the target jvms and make the jar files available on the underlying host :
-javaagent:{path_djigger_folder}\djigger\agent\javaagent.jar=port:{agent_port}

2 . Reboot the target JVM.

PS: If djigger isn't installed on the remote machine, you can just copy our "javaagent" Jar File from the "agent" folder of the zip archive and reference it locally in the command line of the remove JVM by setting the javaagent flag above.

Store mode

  1. Requirements : installing a collector (go to the "Installing a collector" section, down below)

  2. Click the "Store" connector mode and provide the hostname on which the mongoDB instance of the collector is hosted (the client will directly connect to the mongoDB instance).

  3. Query your samples in the new filter found at the very top of the screen, next to the date range selector. You can query the properties that you set in the collector configuration, this is why it's important to set your own attributes there.

For example, I can query the key values provided in the sample CSV file by executing the following query :

env=myPc and app=test and myAttributeKeyX=myAttributeValueX and ( node=1 or node=2)

Installing a collector

  1. Requirements : available mongoDB binaries (mongod daemon, preferably 3.0+), open JMX ports on the monitored JVM (see the "Direct JMX Connection" above in this page), java 6+ JRE or JDK (JDK needed for process attach)

  • You can download the mongoDB community edition here.
  • You can download a JRE or JDK here.

  1. if the binaries aren't accessible via your system PATH variable, set your java and mongoDB bin paths in the startMongo and startCollector scripts of the djigger/collector/bin folder

  2. configure your Collector.xml file (under the conf folder) so as to set the retention policy (TTL) you want in seconds, configure your mongodb host and point at the list of connections that you wish to set up via the following XML block. You can add as many files as you want and combine XML and CSV formats :
    <connectionFiles>
       <string>../conf/Connections.xml</string>
    </connectionFiles>

  3. configure your list of JMX connections (either via XML format for agent connections and subscriptions or simple flat CSV lines if you only want JMX connections and want to work with a simple file), in the /conf folder (you can set as many key-values as you want to tag your thread dumps and query them later on via the store functionality in the client)

    • If XML : the attributes are listed as nested entries and the connection properties as leaves, just open the example given in the Collector.xml file, and define your own connections
    • If CSV : all you need is to set a few attributes on each line, representing a different connection. The columns work as follows :
hostname;jmx_port_number;jmx_user;path_to_file_containing_jmx_password;sampling_rate;attribute_key_1;attribute_value_1;attribute_key_n;attribute_value_n;

4 . make sure that your target JVM's are JMX enabled. You need the following command line flags to be set :

-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port={your_jmx_port} 
-Dcom.sun.management.jmxremote.authenticate=false 
-Dcom.sun.management.jmxremote.ssl=false

5 . start your mongoDB instance via the startMongo script and then start the collector (startCollector script in the /bin folder)

You should now see documents being inserted in the threaddump collection of your mongoDB instance JVM, which means that the target JVM is being monitored. You can use the Store connector of the client to query your data !

Process attach

  1. Add the tools.jar file from the corresponding JDK (needs to be the same version as the target JVM) to your client's classpath. You'll find it under jdk_1.x.y_z/lib . If you set the path to the java.exe (<system_prefix>/<jdk_version>/bin/java.exe) of your JDK in the variable "JVM_PATH", djigger will automatically pick up the tools.jar. See example given inside the startClient script.

  2. Start your djigger client and use the process attach connector to connect to the process you want. The available Java processes will appear in the list.

jstack output files

  1. start your djigger client

  2. provide jstack-style (hotspot) formated thread dump outputs that you've previously gathered and dumped into one file, separated by empty lines (EOF character). You can also use the kill -3 PID command (on Windows) and Ctrl+Break key combination of the CMD window of your java process (on Windows) to issue a SIGQUIT signal which will also dump the thread stacks. Simply gather that stuff into a text file and open it via the jstack connector in the djigger client.