Metrics Reporting Application

Description

The

DDF

Metrics Reporting Application provides access to historical data in graphical, comma-separated values file, Excel spreadsheet, PowerPoint, XML, and JSON formats for system metrics collected while

DDF

is running. Aggregate reports (weekly, monthly, and yearly) are also provided where all collected metrics are included in the report. Aggregate reports are available in Excel and PowerPoint formats.

Usage

The

DDF

Metrics Reporting Application provides a web console plugin that adds a new tab to the Admin console entitled "Metrics". When selected, this Metrics tab displays a list of all of the metrics being collected by

DDF

, e.g., Catalog Queries, Catalog Queries Federated, Catalog Ingest Created, etc.

With each metric in the list, a set of hyperlinks is displayed under each column entitled with the available time ranges. The time ranges currently supported, all measured from the current time that the hyperlink is selected, are: 15 minutes, 1 hour, 4 hours, 12 hours, 1 day, 3 days, 1 week, 1 month, 3 months, 6 months, and 1 year.

All metrics reports are generated by accessing the collected metric data stored in the <DDF_INSTALL_DIR>/data/metrics directory. All files in this directory are generated by the JmxCollector using RRD4J, a Round Robin Database for Java open source product. All files in this directory will have the .rrd file extension and are binary files, hence they cannot be opened directly. These files should only be accessed using the Metrics tab's hyperlinks. There is one RRD file per metric being collected. Each RRD file is sized at creation time and will never increase in size as data is collected. One year's worth of metric data requires approximately 1 MB file storage.

Do not remove the <DDF_INSTALL_DIR>/data/metrics directory or any files in it. If this is done, then all existing metrics data will be permanently lost.

Also note that if

DDF

is uninstalled/re-installed that all existing metrics data will be permanently lost.

There is a hyperlink per format that the metric's historical data can be displayed in. For example, the PNG hyperlink for 15m for the Catalog Queries metric maps to http://<DDF_HOST>:<DDF_PORT>/services/internal/metrics/catalogQueries.png?dateOffset=900 where the dateOffset=900 indicates 900 seconds (15 minutes) from current time to graph data.

All of the metric graphs displayed are in PNG format and are displayed on their own page. The user must hit the back button in the browser to return to the Admin console, or the user when selecting the hyperlink for a graph can use the right mouse button in the browser to display the graph in a separate browser tab or window, thereby keeping the Admin console also displayed. The screen shot below is a sample graph of the Catalog Queries metric's data for the previous 15 minutes from when the link was selected. Note that the y-axis label and the title use the metric's name (Catalog Queries) by default. The average, min, and max of all of the metric's data is summarized in the lower left of the graph.

The user can also specify custom time ranges by adjusting the URL used to access the metric's graph. The Catalog Queries metric data could be graphed for a specific time range by specifying the startDate and endDate query parameters in the URL.

Note that the Metrics Endpoint URL has "internal" in it. This indicates that this endpoint is intended for internal use by the DDF code. As such this endpoint is likely to change in future versions, hence any custom applications built to make use of it, as described below, should be done with caution.

For example, to map the Catalog Queries metric data for March 31, 6:00 am to April 1, 2013, 11:00 am (Arizona timezone, which is -07:00) the URL would be:

http://<DDF_HOST><DDF_PORT>/services/internal/metrics/catalogQueries.png?startDate=2013-03-31T06:00:00-07:00&endDate=2013-04-01T11:00:00-07:00

Or to view the last 30 minutes of data for the Catalog Queries metric a custom URL with a dateOffset=1800 (30 minutes in seconds) could be used:

http://<DDF_HOST>:<DDF_PORT>/services/internal/metrics/catalogQueries.png?dateOffset=1800

The table below lists all of the options for the Metrics Endpoint URL to execute custom metrics data requests:

Parameter	Description	Example
startDate	Specifies the start of the time range of the search on the metric's data (RFC-3339 - Date and Time format, i.e. YYYY-MM-DDTHH:mm:ssZ). Date/time must be earlier than the endDate. This parameter cannot be used with the dateOffset parameter.	startDate=2013-03-31T06:00:00-07:00
endDate	Specifies the endof the time range of the search on the metric's data (RFC-3339 - Date and Time format, i.e. YYYY-MM-DDTHH:mm:ssZ). Date/time must be later than the startDate. This parameter cannot be used with the dateOffset parameter.	endDate=2013-04-01T11:00:00-07:00
dateOffset	Specifies an offset, backwards from the current time, to search on the modified time field for entries. Defined in seconds and must be a positive Integer. This parameter cannot be used with the startDate or endDate parameters.	dateOffset=1800
yAxisLabel	(optional) the label to apply to the graph's y-axis. Will default to the metric's name, e.g., Catalog Queries. This parameter* is only applicable for the metric's graph display format.*	Catalog Query Count
title	(optional) the title to be applied to the graph. Will default to the metric's name plus the time range used for the graph. This parameter* is only applicable for the metric's graph display format.*	Catalog Query Count for the last 15 minutes

Metric Data Supported Formats

The metric's historical data can be displayed in several formats, including the PNG format previously discussed, CSV file, Excel .xls file, PowerPoint .ppt file, XML file, and JSON file. The PNG, CSV, and XLS formats are accessed via hyperlinks provided in the Metrics tab web page. The PPT, XML, and JSON formats are accessed only by specifying the format in the custom URL, e.g., http://<DDF_HOST>:<DDF_PORT>/services/internal/metrics/catalogQueries.json?dateOffset=1800

The table below describes each of the supported formats, how to access them, and an example where applicable. (NOTE: all example URLs begin with http://<DDF_HOST>:<DDF_PORT> which is omitted in the table for brevity).

Display Format	Description	How To Access	Example URL
PNG	Displays the metric's data as a PNG-formatted graph where the x-axis is time and the y-axis is the metric's sampled data values.	Via hyperlink on the Metrics tab or directly via custom URL.	Accessing Catalog Queries metric data for last 8 hours (8 * 60 * 60 = 28800 seconds): /services/internal/metrics/catalogQueries.png?dateOffset=28800& yAxisLabel=my%20label&title=my%20graph%20title Accessing Catalog Queries metric data between 6:00 am March 10, 2013 and 10:00 am April 2, 2013: /services/internal/metrics/catalogQueries.png? startDate=2013-03-10T06:00:00-07:00&endDate=2013-04-02T10:00:00-07:00& yAxisLabel=my%20label&title=my%20graph%20title Note that the `yAxisLabel` and `title` parameters are optional.
CSV	Displays the metric's data as a Comma-Separated Value (CSV) file, which can be auto-displayed in Excel based on browser settings. The generated CSV file will consist of 2 columns of data, Timestamp and Value, where the first row are the column headers and the remaining rows are the metric's sampled data over the specified time range.	Via hyperlink on the Metrics tab or directly via custom URL.	Accessing Catalog Queries metric data for last 8 hours (8 * 60 * 60 = 28800 seconds): /services/internal/metrics/catalogQueries.csv?dateOffset=28800 Accessing Catalog Queries metric data between 6:00 am March 10, 2013 and 10:00 am April 2, 2013: /services/internal/metrics/catalogQueries.csv? startDate=2013-03-10T06:00:00-07:00&endDate=2013-04-02T10:00:00-07:00
XLS	Displays the metric's data as an Excel (XLS) file, which can be auto-displayed in Excel based on browser settings. The generated XLS file will consist of: title in first row based on metric's name and specified time range Column Headers for Timestamp and Value 2 columns of data containing the metric's sampled data over the specified time range the total count, if applicable, in the last row	Via hyperlink on the Metrics tab or directly via custom URL.	Accessing Catalog Queries metric data for last 8 hours (8 * 60 * 60 = 28800 seconds): /services/internal/metrics/catalogQueries.xls?dateOffset=28800 Accessing Catalog Queries metric data between 6:00 am March 10, 2013 and 10:00 am April 2, 2013: /services/internal/metrics/catalogQueries.xls? startDate=2013-03-10T06:00:00-07:00&endDate=2013-04-02T10:00:00-07:00
PPT	Displays the metric's data as a PowerPoint (PPT) file, which can be auto-displayed in PowerPoint based on browser settings. The generated PPT file will consist of a single slide containing: a title based on the metric's name the metric's PNG graph embedded as a picture in the slide the total count, if applicable	via custom URL only	Accessing Catalog Queries metric data for last 8 hours (8 * 60 * 60 = 28800 seconds): /services/internal/metrics/catalogQueries.ppt?dateOffset=28800 Accessing Catalog Queries metric data between 6:00 am March 10, 2013 and 10:00 am April 2, 2013: /services/internal/metrics/catalogQueries.ppt? startDate=2013-03-10T06:00:00-07:00&endDate=2013-04-02T10:00:00-07:00
XML	Displays the metric's data as an XML-formatted file	via custom URL only	Accessing Catalog Queries metric data for last 8 hours (8 * 60 * 60 = 28800 seconds): /services/internal/metrics/catalogQueries.xml?dateOffset=28800 Accessing Catalog Queries metric data between 6:00 am March 10, 2013 and 10:00 am April 2, 2013: /services/internal/metrics/catalogQueries.xml? startDate=2013-03-10T06:00:00-07:00&endDate=2013-04-02T10:00:00-07:00 Sample XML-formatted output would look like: <catalogQueries> <title>Catalog Queries for Apr 15 2013 08:45:53 to Apr 15 2013 09:00:53</title> <data> <sample> <timestamp>Apr 15 2013 08:45:00</timestamp> <value>361</value> </sample> <sample> <timestamp>Apr 15 2013 09:00:00</timestamp> <value>353</value> </sample> <totalCount>5721</totalCount> </data> </catalogQueries>
JSON	Displays the metric's data as an JSON-formatted file	via custom URL only	Accessing Catalog Queries metric data for last 8 hours (8 * 60 * 60 = 28800 seconds): /services/internal/metrics/catalogQueries.json?dateOffset=28800 Accessing Catalog Queries metric data between 6:00 am March 10, 2013 and 10:00 am April 2, 2013: /services/internal/metrics/catalogQueries.json? startDate=2013-03-10T06:00:00-07:00&endDate=2013-04-02T10:00:00-07:00 Sample JSON-formatted output would look like: { "title":"Query Count for Jul 9 1998 09:00:00 to Jul 9 1998 09:50:00", "totalCount":322, "data":[ { "timestamp":"Jul 9 1998 09:20:00", "value":54 }, { "timestamp":"Jul 9 1998 09:45:00", "value":51 } ] }

Metrics Aggregate Reports

The Metrics tab also provides aggregate reports for the collected metrics. These are reports that include data for all of the collected metrics for the specified time range.

The aggregate reports provided are:

Weekly reports - for each week up to the past 4 complete weeks from current time. A complete week is defined as a week from Monday through Sunday. For example, if current time is Thursday, April 11, 2013, then the past complete week would be from April 1 through April 7.
Monthly reports - for each month up to the past 12 complete months from current time. A complete month is defined as the full month(s) preceding current time. For example, if current time is Thursday, April 11, 2013, then the past complete 12 months would be from April 2012 through March 2013.
Yearly reports - for the past complete year from current time. A complete year is defined as the full year preceding current time. For example, if current time is Thursday, April 11, 2013, then the past complete year would be 2012.

An aggregate report in XLS format would consist of a single workbook (spreadsheet) with multiple worksheets in it, where a separate worksheet exists for each collected metric's data. Each worksheet would display:

the metric's name and the time range of the collected data,
2 columns, Timestamp and Value, for each sample of the metric's data that was collected during the time range
a total count (if applicable) at the bottom of the worksheet

An aggregate report in PPT format would consist of a single slideshow with a separate slide for each collected metric's data. Each slide would display:

a title with the metric's name
the PNG graph for the metric's collected data during the time range
a total count (if applicable) at the bottom of the slide

Hyperlinks are provided for each aggregate report's time range in the supported display formats, which include Excel (XLS) and PowerPoint (PPT). Aggregate reports for custom time ranges can also be accessed directly via the URL http://<DDF_HOST>:<DDF_PORT>/services/internal/metrics/report.<format>?startDate=<start_date_value>&endDate=<end_date_value> where <format> is either xls or ppt and the <start_date_value> and <end_date_value> specify the custom time range for the report.

The table below list several examples for custom aggregate reports. (NOTE: all example URLs begin with http://<DDF_HOST>:<DDF_PORT> which is omitted in the table for brevity).

Description	URL
XLS aggregate report for March 15, 2013 to April 15, 2013	`/services/internal/metrics/report.xls?startDate=` `2013-03-15T12:00:00-07:00&endDate=2013-04-15T12:00:00-07:00`
XLS aggregate report for last 8 hours	`/services/internal/metrics/report.xls?dateOffset=28800`
PPT aggregate report for March 15, 2013 to April 15, 2013	`/services/internal/metrics/report.ppt?startDate=` `2013-03-15T12:00:00-07:00&endDate=2013-04-15T12:00:00-07:00`
PPT aggregate report for last 8 hours	`/services/internal/metrics/report.ppt?dateOffset=28800`

Adding Custom Metrics to the Metrics Tab

It is possible to add custom (or existing, but non-collected) metrics to the Metrics Tab by writing an application. Refer to the SDK example source code for Sample Metrics located in the DDF source code at sdk/sample-metrics and sdk/sdk-app.

The Metrics framework is not an open API, but rather a closed, internal framework which can change at any time in future releases. Please be aware that any custom code written may not work with future releases.

Installation and Uninstallation

The Metrics Reporting Application can be installed and uninstalled using the normal processes described in the Configuration section.

Configuration

No configuration can be made for the Metrics Reporting Application. All of the metrics that it collects data on are pre-configured in

DDF

out of the box.

The metrics-reporting feature can only be installed and uninstalled. It is installed by default.

Known Issues

The Metrics Collecting Application uses a “round robin” database, one that does not store individual values but, instead, stores the rate of change between values at different times. Due to the nature of this method of storage, along with the fact that some processes can cross time frames, small discrepancies - differences in values of one or two have been experienced - may appear in values for different time frames. These will be especially apparent for reports covering shorter time frames such as 15 minutes or 1 hour. These are due to the averaging of data over time periods and should not impact the values over longer periods of time.

Distributed Data Framework 2.2.X