Saturday, May 25, 2013

Add custom dashboards to BAM2 to monitor API usage

The gadget generation tool is a step by step wizard that allows you to generate gadgets for your dashboard in a few simple steps. These steps are:
  1. Enter JDBC data source details
  2. Enter SQL to fetch data
  3. Pick UI element for gadget
  4. Enter gadget details
  5. Add gadget to dashboard
To use this tool, Click on the "Gadget Gen Tool" located in the left menu.
To explain these steps, let's create a simple gadget out of some summarized data off the KPI Definition sample.

Enter JDBC Data Source Details
Enter the necessary details, for your data source. If you are using any other data source other than h2 (mysql, oracle, mssql, etc.) the relevant driver needs to be placed in $BAM_HOME/repository/components/lib and the server should be restarted. For this example we will use same stats database.

The details entered here are:
  • JDBC URL : jdbc:mysql://datacenter1:3306/am_stats_db
  • Driver Class Name :com.mysql.jdbc.Driver
  • User Name : root
  • Password : root

To check whether the details are correct, you can click on "Validate Connection". If the connection is successful you will get a success message and a failure message if the connection cannot be made. Now, click "Next".
Enter SQL To Fetch Data
In this step, you need to enter the SQL that will fetch the required data for your gadget. You can click the "Preview SQL Results" button, to preview the results returned by the SQL Query.

Here the SQL statement used is : select * from brandSummary. The image below shows the results returned from this query. Now, click "Next". For different dashboards we will use following sql queries.

Get API usage(request count) per user.
SELECT sum(total_request_count),userId FROM API_REQUEST_SUMMARY group by userId;

Get API usage(request count) per API.
SELECT sum(total_request_count),api FROM API_REQUEST_SUMMARY group by api;

Get API response time per API/version.
SELECT serviceTime, api_version FROM API_RESPONSE_SUMMARY;

Get API usage(request count) per data center.
SELECT hostName as data_center_domain, sum(total_request_count) FROM API_REQUEST_SUMMARY group by hostname;

Pick UI Element For Gadget
This step allows you to pick the UI element for visualizing your data. Bar graphs and Tables are supported for this release. All options you pick are instantly reflected in the preview area.

Bar graph
The bar graph gives you some configuration options to customize the view of the generated gadget. These are:
  • Chart Title - Title of the char
  • Y-Axis Label - Title of the Y Axis
  • Y-Axis Column - Column for the Y Axis returned from the results
  • X-Axis Label - Title of the X Axis
  • X-Axis Column - Column for the X Axis returned from the results
The options you pick are reflected in the preview area as highlighted by the colors in the screen shot below.

The table give you a configuration option:
  • Table Title : The title of the table

Let's create a bar graph with options shown in the bar graph image for this sample. Click "Next".
Enter Gadget Details
We are at the final stage of the gadget generation. We need to enter the following details:

  • Gadget Title : Each gadget will have a title that describes what the gadget's functionality. Enter the generated gadget's title here.
  • Gadget Filename : The filename of the gadget as it will be stored in the system. In this case it will be stored in the embedded registry.
  • Refresh rate : The gadget can have a refresh rate, where it will automatically refresh and pull the latest contents out of the data source.  

    Now, click "Generate!".

    Add Gadget To Dashboard
    Now, the gadget has been generated. Copy the location of the gadget displayed in the screen.
    Next, click "View Portal" from the left hand side menu.
    Click on add gadget on the left hand side of the portal page.
    Expand the "Enter Gadget Location" section on the right hand side and paste the gadget location. Then, click on "Add Gadget".
    Now, the gadget will be shown in the dashboard as shown in the screen below. Continue same process if you need to add more graphs to dashboard.