Tutorial details

The goal of this tutorial is to describe step by step on how to create dynamic real time HTML dashboards with a custom layout that can be viewed in both desktop as well as mobile and table browsers.

Author

Christian Grimm (christian.grimm@compuware.com)

dynaTrace Versions

dynaTrace 5.0

License

dynaTrace BSD

Support

Experimental - Not Supported

Release History

2013-01-21 Initial release

Download

HTML Dashboard Prototype

XSL Template
XSL Static Example
XSL Dynamic Example

Source Code (Eclipse Project)

Examples

Real time web dashboards:

Web Dashboards

Desktop Browser




Mobile Phone (WP8)



iPad



About dynaTrace dashboards

Compuware dynaTrace offers a great way to design and view dashboards within the Java based rich client. These dashboards are fully interactive and display analytics data in real time.

Documentation about dynaTrace dashboards:
https://apmcommunity.compuware.com/community/display/DOCDT50/Dashboards

Great video about building fancy dashboards:
https://apmcommunity.compuware.com/community/display/LEARN/dynaLearn+Webinar+-+Fancy+dashboards+in+dynaTrace+-+June+13%2C+2012

Situation

Sometimes it could be helpful to display dashboards as HTML for viewing analytics data in a regular web browser or on mobile devices.
To accomplish this goal, dynaTrace offers a built in dashboard export functionality which is described in the reporting section of the dynaTrace documentation: https://apmcommunity.compuware.com/community/display/DOCDT50/Reporting

Problematic

The out of the box HTML report function exports all dashboard components in vertical sequence, without any chance to manually configure the individual components or layout. This means the original layout of the designed dashboard will not be exported to the HTML document.

Icon

If a custom layout for the HTML dashboard is not an essential requirement, it is highly recommended to use the out of the box HTML reporting function.

If a custom HTML dashboard with individual layout and functionality is a fundamental requirement, this tutorial will help to accomplish this.

Goal of this tutorial

This tutorial describes step by step how to create dynamic real time HTML dashboards with a custom layout.
The resulting HTML dashboards are viewable in any regular web browser or mobile device.

Preconditions

For mastering this tutorial requires basic knowledge of the following technologies:

  • HTML (Create HTML documents)
  • XML (Read and understand XML documents)

Going one step further and extend or debug parts of this project, an engineer level for the following technologies is essential:

  • JAVA
  • HTML
  • XML
  • XSL

The basics

How it works

(1) Getting the data from dynaTrace

Every dynaTrace dashboard can be exported as XML. This means all the underlaying data, which is visualized by the dynaTrace Rich Client can be exported as XML from the dynaTrace server.
Example (REST Inteface Call): http://dynatraceserver:8020/rest/management/reports/create/easyTravel%20Operations%20Console?type=xml
This REST call exports the raw data for the dashboard "easyTravel Operations Console" as XML. The exported data can be real time data or static data, depending on the configuration of the dashboard.

(2) Creating the HTML document

After getting the data as XML, XSL can be used to transform the raw XML data into HTML. For this tutorial a custom Apache Tomcat Web App (Servlet) will be used to execute this transformation.
This means for every web request to the Apache Tomcat Web Server, an internal REST call to the dynaTrace Server will be made to grab the XML and convert it on the fly into HTML.
The only thing needed is a HTML document on the Apache Tomcat Web Server, which contains the page style and defines at which location the charts should be rendered. That’s basically it.

Note: The HTML layout is packed into an XSL file.

Let's start!

As the "how it works" graphic above is suggesting, this tutorial explains how to make a HTML version of the dashboard "easyTravel Operations Console". However, it’s about the same process for any other dashboard.
For this tutorial, a working dynaTrace installation configured with easyTravel is required. Please refer to the following guide how to set up easyTravel: https://apmcommunity.compuware.com/community/display/DL/Demo+Applications+-+easyTravel#DemoApplications-easyTravel-InstallingeasyTravel

(1) Installation and Configuration

This section explains how to install and configure the Apache Tomcat Web Server.

(1.1) Install JRE

If the system, which is intended to run the Apache Tomcat Web Server, does not yet have a Java Runtime installed the JRE should be downloaded and installed from http://www.java.com

Hint: After the installation it’s very important to make sure the "JRE_HOME" system variable is set correctly.

(1.2) Install Apache Tomcat

Download the latest version from http://tomcat.apache.org. It’s recommended to download the ZIP file version and extract it to installation location. At the time this article has been written, Apache Tomcat 7.0.35 was the current version. This is also the only tested version for this tutorial.
The following screenshot shows an example of the extracted Apache Tomcat Installation:

After the installation it should be verified if the Apache Tomcat is running fine with the default configuration. The startup script "startup.cmd" will start the Apache Tomcat:

If Apache Tomcat is running fine, the following output on the console should be visible and the URL http://localhost:8080 should display the Apache Tomcat welcome page.

(2) Configuring the Apache Tomcat Web Server:

As an optional step the file "server.xml" from Apache Tomcat can be modified to run on port "80" instead of "8080".

(3) Installation and configuration of the HTML dashboard generator Web App:

After successfully setting up Apache Tomcat, the Web App which is doing to do all the XML to HTML processing needs to be deployed. Please download the file dynaTraceWebDashboardsApp-Step3.zip and extract it into the "webapps" sub folder of the Apache Tomcat installation directory.

The next step is to configure the Web App. It is important for the Web App to know how to access the dynaTrace server. Please edit the file "configuration.properties" and specify the dynaTrace server hostname, port (for the REST service) and credentials.

At this point the Web App can be tested. Opening the URL http://localhost:8080/dynaTraceWebDashboards/generate with a web browser should look as following.

The message "no style parameter supplied" is okay for now:

(4) Creation of a prototype HTML Dashboard

Now, it is time to craft a HTML document and design the desired dashboard. A professional tool such as Adobe Dreamweaver (http://www.adobe.com/products/dreamweaver.html) is strongly recommended during this process.
The goal is to design a static web page and substitute the dynamic dashboard parts (like traffic lights, charts, etc.) with image place holders for now.

An example of the HTML prototype for the "Operations Console" dashboard can be downloaded from here (easyTravel Operations Console Dashboard HTML Prototype.zip) and looks like this:

The HTML file should be saved to the root folder of the dynaTraceWebDashboards app while additional resources are stored in the "img" or "lib" sub folder.

If everything is working, the static dashboard is available through the Apache Tomcat Web Server. The following URL assumes the example dashboard (easyTravel Operations Console - HTML Prototype.html) is used:

http://localhost:8080/dynaTraceWebDashboards/easyTravel%20Operations%20Console%20-%20HTML%20Prototype.html

(5) Convert the HTML prototype into an XSL template

After getting the static version of the dashboard to work with Apache Tomcat, the dynamic version can be built. The first step of doing this is to embed the static HTML into an XSL file. Please download this template (template.xsl) and use it for creating the XSL file:

After pasting the HTML code into place, the XSL file should look like this:

The final XSL file must be stored into the dynaTrace Web App root directory. An example of the final static XSL is available here:
easyTravel Operations Console - Static.xsl (Please rename it properly after downloading)

Important Note:
It is imperative to save the XSL file with exactly the same name as the dashboard in dynaTrace. The dynaTraceWebDashboards app will call the dynaTrace Server via the REST service to get the XML data. This only works, if the XSL has exactly the same name as the dashboard in dynaTrace – otherwise the Web App has no chance to know which dynaTrace dashboard to use as XML data source.

If everything went well, the XSL should now be available through the Apache Web Server.
Example for http://localhost:8080/dynaTraceWebDashboards/easyTravel%20Operations%20Console.xsl:

(6) Adding dynamics Elements (Traffic lights, charts, etc.):

This last section will cover how to replace the static placeholder elements with dynamic traffic lights, charts etc.

(6.1) Example for a traffic light

For the easyTavel Operation Console example described so far, there are placeholder elements in the HTML document which defines where a dynamic component should be inserted. Example:

Simply replace the placeholder with the following code to get a full dynamic traffic light:

(6.2) Example for a chart

Also replace the placeholders for chart elements with the following code to get a full dynamic chart:

Important note:
The traffic light as well as the chart needs to know which dashlet and measures from dynaTrace dashboard XML data should be used. To define this, the following argument has to be matched with the XML output from the dynaTrace server:

XML output from dynaTrace server (http://localhost:8020/rest/management/reports/create/easyTravel%20Operations%20Console?type=xml):

An example of the final dynamic XSL is available here:
easyTravel Operations Console - Dynamic.xsl (Please rename it properly after downloading)

(7) Done!

If everything went well, the following result can be achieved:

http://localhost/dynaTraceWebDashboards/generate?style=easyTravel%20Operations%20Console.xsl

(8) Optional: Extensions and debugging

This section covers how to develop custom extensions to this project or just debugging it in general.

(8.1) Debugging the Java Servlet

The Java Servlet "com.compuware.apmcommunity.TransformationServlet" is responsible for the XSL to HTML conversion. The servlet is called with a style parameter (http://localhost/dynaTraceWebDashboards/generate?style=easyTravel%20Operations%20Console.xsl for example).
Internally the Servlet connects to the dynaTrace server, downloads the XML and transforms it using XSL finally into HTML. For this purpose the Saxon Java library is used.

Setting up the IDE (Eclipse) for debugging:
Please refer to the following tutorial for setting up Eclipse to debug Apache Tomcat Applications:
http://www.coreservlets.com/Apache-Tomcat-Tutorial/tomcat-7-with-eclipse.html

Just as described in the section "Import and Test a Sample App" from the listed tutorial above, projects can be imported from a ZIP file into Eclipse. The file EclipseProject.zip includes everything which is necessary and can be imported and run in Eclipse just the same way as described.

(8.2) Debugging the XSL to HTML transformation

Step by step debugging of XSL can be very tricky as this cannot be done within Eclipse. The "Oxygen XML Editor" from http://www.oxygenxml.com/ is maybe one of the best tools out there to handle this task.

Please follow these steps if step by step debugging of the XSL to HTML transformation is required:

(8.2.1) Download the "Oxygen XML Editor" from http://www.oxygenxml.com.

Unfortunately it’s not an open source tool available for free. However, Oxygen offers a 30 day trial to prove it's worth the money.

(8.2.2) Download a reference XML from the dynaTrace server

As already mentioned the XSL transformation cannot be debugged together with the Apache Tomcat Servlet. However, this is not so much of a handicap. The only thing needed to debug with Oxygen is a reference dashboard exported as XML from the dynaTrace Server. For the "easyTravel Operations Console" dashboard this could be downloaded from the dynaTrace server with this URL:
http://localhost:8020/rest/management/reports/create/easyTravel%20Operations%20Console?type=xml

Just save the resulting XML to the Eclipse project workspace folder

(8.2.3) Create a new Oxygen Project

After starting up Oxygen, an Oxygen project needs to be created. It’s recommended to save it in the "WebContent" of the Eclipse project.

Adding files and folders to the project ...

.. to make the Oxygen project look like this:

(8.2.4) Configure the Run/Debug Config

After this double click on the "easyTravel Operations Console.xsl" file from the Oxygen project and hit the "Appy" or "Debug" button from the toolbar.

Use the following settings

Afterwards the following error may appear:

This error occurs because "DateUtil.xsl" is calling a Java method which is only available when executed within the Apache Tomcat environment. To overcome this issue, just comment (disable) the following line:

Afterwards debugging within Oxygen should work like a charm.
Example:

  • No labels
  1. Anonymous (login to see details)

    I think I just found my next project. Thanks for all the hard work, Christian!

    1. Anonymous (login to see details)

      Hi Michael, please let me know if everything worked well for you or the documentation is missing something.
      Thank you
      Christian

  2. Anonymous (login to see details)

    I can only see gray vertical lines plotted on the graph and not the same as yours

    1. Anonymous (login to see details)

      Hi,
      Thank you for you post. Unfortunately the project consists out of many parts and pieces, so without having more information available it's difficult to say why it didn't work in your case.
      Could you please answer the following questions:
      1) What dynaTrace version / easyTravel version are you using?
      2) Did you exactly follow all steps from the tutorial above?
      3) Is dynaTrace configured with the default admin password?
      4) If you open the "Operations Console" dashboard in the dynaTrace Client, do you see data in the response times charts for the business transactions?
      5) Could you please send me your eclipse project as zipped file to christian.grimm(at)compuware.com?

      Thank you
      Chris

      1. Anonymous (login to see details)

        It seemed to be a cache issue,i cleared the cache and now it works perfectly fine,another question is can we use the date/time control with this as currently what ever the duration is saved for the DB the x-axis is going to reflect .
        Secondly is there any way to format the x axis because currently it shows it as day:hour e.g. 16:5 meaning 5 o'clock on 16th june

        1. Anonymous (login to see details)

          Hi,
          Great to hear it's working for you now. To your questions:

          1) X-Axis
          I am sorry, I'm not sure what your question is here. The x-axis calculation works like this: depending what timeframe your dynaTrace dashboard is saved for (example: last 30 minutes) this will be exported to xml. The xslt function "drawBarChart" in BarChart.xls will then parse the xml to find the minimum and maximum time stamp from the xml document and renders this as a bar chart. To make it simple: the time/date range is controlled by the dynaTrace dashboard.

          2) Date Format
          The date format is controlled by the DateFormatUtil.java class. Feel free to modify the output format there.

          Kind regards
          Chris

          1. Anonymous (login to see details)

            Thanks for the suggestions,I will try on that.

  3. Anonymous (login to see details)

     

    Hi Christian,

    It's really great to create custom dashboards with less work. I'm wondering if we can do the below stuffs,

    1) Create different type of charts - Line chart, Area chart, pie chats etc. Do you use custom xsl library? If not where can i find the libraries for them?

    2) The bar chart in the example showed only one attribute. Can we add more attributes to show multiple bars in the chart? The reason being, the data i've has multiple atributes. ie There will be 7 lines in the chart in dynatrace. But the xsl chart I tried showed only one bar chart in orange.

    Thanks for the good work (smile)

     

  4. Anonymous (login to see details)

    Is this the only way to publish a dashboard? Seems extremely convoluted? Is there an IIS alternative? I want to publish a single dashboard and creating an Apache instance for this seems like overkill.

    1. Anonymous (login to see details)

      Hi Matt

      EVERY Dashoard automatically provides an HTML representation. Simply open your browser and go to http://dtserver:8020 - from there you will find the way to view all dayshboards as HTML. The option that is shown here is a nicer formatting of the HTML Dashboards

  5. Anonymous (login to see details)

    Ok cool. To embed that into a web page simply create a log on account with no password and just give it access to that dashboard?

    1. Anonymous (login to see details)

      Hi Matthew,

      The method described by this article works as following:
      WebBrowser -> Tomcat -> dynaTrace Server

      Apache Tomcat needs to be configured as described in section "(3) Installation and configuration of the HTML dashboard generator Web App" with a username and password to access the dynaTrace server. This dynaTrace user does only need read-only permission for the affected dashboard(s).

      The accessing web browser does not need any credentials for displaying the dashboards. This should make it very easy to integrate the HTML dashboard into a portal. However, If security does matter, you can configure the Apache Tomcat to restrict dashboard access to certain users.

      I hope this answers your question
      Christian

       

  6. Anonymous (login to see details)

    WorldMap extension

     

    let me add a humble extension to the brilliant initiative started by Christian GRIMM.

    This set of files (containing xsl and javascript), that you can add to the infrastructure described above, will give you the ability to render a worldmap from the REST API.

    Requirements : 

    • save a dashboard containing at least one Worldmap dashlet.
    • give your xsl file the same name as your dashboard (in the provided archive, the file is called "worldmap.xsl", thus expecting the dashboard to be named "worldmap").
    • edit the xsl file and look for references to the worldmapdashlet. Change the name attribute to match the name you gave to your worldmap dashlet (in the provided archive, the name attribute has a value of "World Map", thus expecting a worldmap dashlet to be called "World Map" in the saved dashboard).

    You're basically done.

    You'll notice that this will produce a slideshow effect between different maps (visits/frustration/APDEX). The page is refreshed automatically every minute.

    You can edit further to change colors, sizes, ... 

    By default, it should look like the following (with cross-fading effects between maps) : 

    Any feedback welcome

    Regards

    --

    Laurent IZAC

    1. Anonymous (login to see details)

  7. Anonymous (login to see details)

    Hi! I am curious exactly what you place in the html for the dashlet name that allows it to be pulled form dynatrace into the dashboard. Whenever i live preview the dashboard i created the dashlet and traffic signs that are supposed to be dynamic, dont show up, leaving just a black background, however the element itself seems to exist within the browers. How can i find the XML outputted by the dynatrace server to see the name of the chart dashlet that I am trying to pull into the custom dashboard.


    Also, as previously stated, where can one find the possibility to insert other types of charts/dashlets. Thank you for your help!