Skip to content
This repository has been archived by the owner on Nov 15, 2022. It is now read-only.

Home

Jump to bottom
thacau edited this page Apr 12, 2017 · 41 revisions

Welcome to the Docs wiki!

The following sections describe how to create the necessary preconditions for ExplorViz as well as how to install and configure it. The first section describes the general procedure how to get started with ExplorViz. The second section offers more detailed information how to get started with ExplorViz as a developer. The last section is intended for the users and therefore more detailed.

General procedure:

  1. Install the latest Chrome Browser
  2. Start a server on which ExplorViz is monitored
  3. Start monitoring a java application
  • Start Guide for developers

Start Guide for developers:

  1. Download and install Java SE Development Kit 8.

  2. Download and extract the Eclipse IDE for Java and DSL Developers.

  3. Start the IDE and install /Google Plugin for Eclipse/Google Plugin for Eclipse 4.4/4.5/4.6 and /SDKs/Google Web Toolkit SDK 2.7.0.

  4. Download the projects Common, Analysis, Monitoring and ExplorViz (Server) from Github.

  5. Import the projects into the previously downloaded Eclipse IDE.

    Hint: Import the project ExplorViz (Server) as the last.

  6. Wait until validation is complete and the working directory has build up properly. You can see the progress right next to the heap size in the picture below.

    Hint: Errors can be avoided by restarting Eclipse.

workspace

  1. You can skip step 8. if there is already a run launch history containing five entries.

  2. Select the project ExplorViz and click run to start the server component. Wait at least until there is a Thread listening on port 10133 and restart Eclipse. The run launch history now contains five entries.

  3. Start the server component by clicking ExplorViz Server in the run menu.

  4. Start your Chrome Browser and navigate to http://localhost:8888.

  5. Get access to ExplorViz by clicking Sign In without adding any login data.

  6. You can use the Start Monitoring Test App as shown in the picture below to get input. Another way to get input is to use your own source code as described in the user’s guide.

run-menu

Start Guide for Users:

This section is divided into different parts and shows how to monitor a java program with ExplorViz. Therefore a local server is needed on which ExplorViz is monitored.

Installing and configuring the server:

  1. Download ExplorViz Binaries.

  2. Download and install Java Runtime Environment (JRE, Java Runtime).

    Hint: You have to rename the destination directory if there is already a directory containing parts of Java Runtime Environment.

  3. First Copy the file ROOT.war from ExplorViz Binaries to your application server (webapps). Then copy the file explorviz-monitoring.jar to your server’s lib folder.

  4. This example illustrates the installation and configuration of an Apache Tomcat 8.5 Server on windows.

  5. Start the server.


The desired program has to be launched with certain parameters to monitor it with ExplorViz. The following paragraphs show two possible ways to monitor your program. Reminder: Keep the server running.

Start monitoring a java application

The following subparagraphs describe how to monitor a java application in two different ways

Start monitoring java applications with Eclipse:

  1. Click right on your project, go to Run as and select Run Configuration.

  2. Open the tab Arguments and add the following instruction to the category VM arguments:

    -javaagent: yourpath\lib\explorviz-monitoring.jar

    important: yourpath has to contain the absolute path to the file explorviz-monitoring.jar which resides in your server’s lib folder.

    In our example it looks like this:

    -javaagent:C\Programme\Apache" "Software" "Foundation\Tomcat" „8.5\lib\explorviz-monitoring.jar

eclipse

  1. Run the main class with the new configuration.

  2. Start your Chrome Browser and navigate to http://127.0.0.1:8080.

  3. Get access to ExplorViz by clicking Sign In without adding any login data.

  4. Navigate to the tab Visualization and monitor your application.

    Hint: It might take a few seconds until your application is monitored. Furthermore relaunch the monitored application if the data stream was incomplete.

Start monitoring java applications with windows command-line:

  1. Export your project as an executable jar file. For details see this documentation .

  2. Open the command-line and enter following instruction:

    java -javaagent: yourpath\lib\explorviz-monitoring.jar -jar jarpath\filename.jar

    yourpath has to contain the absolute path to the file explorviz-monitoring.jar which resides in your server’s lib folder. jarpath has to contain the absolute path to the target jar file.

    In our example it looks like this:

    java -javaagent:C:\Program" "files\Apache" "Software" "Foundation\Tomcat" "8.5\lib\explorviz-monitoring.jar -jar jarpath\filename.jar

  3. Start your Chrome Browser and navigate to http://127.0.0.1:8080.

  4. Get access to ExplorViz by clicking Sign In without adding any login data.

  5. Navigate to the tab Visualization and monitor your application.

    Hint: It might take a few seconds until your application is monitored. Furthermore relaunch the monitored application if the data stream was incomplete.

Set Up the Monitoring

This paragraph deals with the monitoring configuration regarding to which components of the software are visualized.

  1. The monitoring configuration file aop.xml resides in the file explorviz-monitoring.jar which is stored in your server’s lib folder.

    In our example aop.xml resides in the file C:\Program" "files\Apache" "Software" "Foundation\Tomcat" "8.5\lib\explorviz-monitoring.jar.

  2. Open the jar file with an extractor for example winzip or winrar. Navigate to the folder META-INF and extract the file aop.xml.

    Hint: You can use an editor to open the file.

  3. Open the extracted file aop.xml and update the <include within="*"/> statement according to your needs. For instance replace it with: <include within="com.ibatis..*" /> to monitor only method calls in the com.ibatis package and its subpackages. Add further <include within="more.packages..*“/> statements below to include more than one package. The mentioned statement and especially the last advice is shown in the picture below.

aop

  1. After modifying the file just replace it in the jar file.

    Hint: The server on which ExplorViz is monitored has to be terminated. For authorization problems see the troubleshooting below.

Configuration Options

This paragraph shows more configuration options to adapt ExplorViz to your expectations.

  1. The ExplorViz configuration file explorviz.live_trace_processing.default.properties also resides in the file explorviz-monitoring.jar which is stored in your server’s lib folder.

    In our example it resides in the file C:\Program" "files\Apache" "Software" "Foundation\Tomcat" "8.5\lib\explorviz-monitoring.jar.

  2. Open the jar file with an extractor for example with winzip or winrar. Navigate to the META-INF folder and extract the file explorviz.live_trace_processing.default.properties.

  3. Open the extracted file explorviz.live_trace_processing.default.properties and look up the the options in the table below.

    Hint: You can use an editor to open the file. If you have formatting problems using windows editor alternatively use WordPad.

  4. After modifying the file just replace it in the jar file.

    Hint: The server on which ExplorViz is monitored has to be terminated. For authorization problems see the troubleshooting below.

Parameter Default Value Description
writer_target_ip 127.0.0.1 Defines the target ip where the analysis component/visualization server is running.
writer_target_port 10133 Defines the target port where the analysis component/visualization server is running.
writer_load_balancing_enabled false Used for cloud scaling. If true, the writer_target_ip paramter is ignored. Instead the monitoring queries the load balancer for an ip adress.
system_name <UNKNOWN-SYSTEM> The name of the system belonging to the application
ip_address one ip address of the server The IP address of the server where the application is running
host_name hostname of the server The hostname of the server where the application is running
application_name <UNKNOWN-APPLICATION> The displayed name of the application
programming_language Java The programming language of the application

Troubleshooting:

If you don't have the permission to change the file explorviz-monitoring.jar take the following steps:

  1. Move the file explorviz-monitoring.jar out of the actual directory

  2. Replace the modified files in explorviz-monitoring.jar.

  3. Move the file explorviz-monitoring.jar back to the original directory.

© 2013 - 2020 by the ExplorViz project

Clone this wiki locally