Support/MetricsDashboardPRD/implementation

[paulc] (Draft) This page will show documentation for the Metrics dashboard.

Simple tutorial

This is included first because, as a developer, my technical skills of understanding and explaining are not always intuitive, so it's better to walk through this example before you read the technical aspects below. Once that is done, you should read the rest of this document and re-do the tutorial, by correlating the steps with the information below.

Create a simple metric

• Go to /tiki-admin_metrics.php (you will need admin rights for this)
• Click on "Edit/Create Metric" at the top links, you will be taken down the page to /tiki-admin_metrics.php#editcreate
• Enter the following information:

Name: # new KB posts Range: Weekly Datatype: Integer Query:

SELECT SUM(measure) AS count, DATE(date_field) AS date_field

FROM f_events NATURAL JOIN d_date NATURAL JOIN d_eventtype

WHERE $date_range$ AND sourceType = 'knowledge base' AND actionType = 'create' $range_groupby$ ORDER BY date_field DESC;

• Click on the "Create new metric" button below this form
• Once the form is submitted, notice the new metric shows up in the list at the top under the heading "Metrics"

Create a tab

• Click on "Edit/Create Tab" at the top links, you will be taken down the page to /tiki-admin_metrics.php#editcreatetab
• Enter the following information:

Name: Overview Order: 1 Content:

<div class="metricbox">
{metric sparkline=true numpoints=5 name="# new KB posts"}
<div class="title">
<a class="toggle-button">Toggle</a>
New KB posts: {metric name="# new KB posts" count="count" }
{metric trend=true name="# new KB posts" count="count"}
</div>
<div class="toggle">
{metric table=true numpoints=5 name="# new KB posts"}
Tada!
</div>
</div>

• Click on the "Create new tab" button below this form
• Once the form is submitted, notice the new tab shows up in the list under the heading "Tabs"

Assign the metric to the tab

Now that you have a metric and a tab, it's time to assign the former to the latter.

• Click on "Assign Metric" at the top links, you will be taken down the page to /tiki-admin_metrics.php#assign
• Select the metric name "# new KB posts" and the tab "Overview"
• Click on the "Assign" button below this form
• Once the form is submitted, notice the new assigned metric shows up in the list under the heading "Assigned Metrics"

CONGRATULATIONS! You have just created a simple metrics tab!

Dashboard UI

Overview

Go to:

 /tiki-metrics.php

• No sidebar for more room
• Uses JQuery, JQuery UI and JQuery Sparklines
• Tabs fetch content through AJAX from /metrics-tab.php
• Parameters passed to /metrics-tab.php:
  • tab_id (integer)
  • date range in format yyyy-mm-dd, date_from and date_to
  • range_type - weekly, monthly, custom

Administration

Preferences

Go to:

 /tiki-admin?page=metrics

• Show past results + count => how many results to track back on. This number affects the date range for a query.
• Metrics Database => defaults to sumodw, the data warehouse where we keep all of the metrics tables

Editing Content

Go to:

 /tiki-admin_metrics.php

Creating metrics

Metrics have the following fields:

• Name - gives the name by which metrics can be retrieved in tab content
• Range - (more clearly, range type) how often this metric is to be collected, how it should be treated (not currently used in implementation, but available)
• Data type - what type of data this metric returns
• Query - the SQL query that will be run. MUST contain these tokens:
  • $date_range$ - must be placed in the WHERE clause, will be automatically replaced with something like:

 (date_field >= date_from AND date_field <= date_to)

• • $range_groupby$ - must be placed in the GROUP BY clause. If there isn't one, the $range_groupby$ token will contain the "GROUP BY" string. This looks like:

 GROUP BY WEEK(date_field,1) -- for weekly display
 GROUP BY MONTH(date_field) -- for monthly display
 GROUP BY date_field -- for custom display

• • • Note: the $range_groupby$ token does not reflect the metric range type. Instead, it reflects the selected date range in the dashboard display

Creating tabs

Tabs have the following fields:

• Name - gives the name of the tab, displayed on the dashboard
• Order - gives the order of the tab in the display (tabs are sorted ascendingly by this)
• Tab content - smarty content that will be parsed in metrics-tab.php. This, too, may contain some functions
  • The basic layout to create a metrics tab looks like this:

<div class="metricbox">

(REQUIRED) this contains the entire metric

{metric sparkline=true numpoints=5 name="# new KB posts"}

Syntax for a sparkline, numpoints is the number of data points to plot, name specifies which metric data to examine.

<div class="title">

(REQUIRED) contains metric title

<a class="toggle-button">Toggle</a>

(REQUIRED) contains the toggle button for expanding a table of past results under the metric

New KB posts: {metric name="# new KB posts" count="count" }

Gets the metric results. these are expected to be the first result of the populated array, and we're looking for the column aliased as "count" in the MySQL query, for query name "# new KB posts"

{metric trend=true name="# new KB posts" count="count"}

Gets the trend and automatically assigns a class to it: trend-red for decreasing, trend-green for increasing, trend-gray for unchanged. Note: this may not work without metrics_pastresults enabled in preferences.

</div>
<div class="toggle">
{metric table=true numpoints=5 name="# new KB posts"}

This generates the metrics table. numpoints is the number of points = number of rows (same as for the sparkline).

Tada! And this is just plain text or HTML you can include!
</div>
</div>
<div class="metrics-box">
Another metric goes here...
</div>

Assigning metrics to tabs

This process is fairly intuitive. When you assign a metric to a tab, it just means that the query for that metric will be run on that specific tab. Of course, since the tab content is customized, you can just assign all metrics everywhere. But the purpose of tabs grabbed through AJAX and assigning metrics to tabs is to ease the query load and decrease page loading time. So it's best practice to assign to each tab only the metrics that are actually going to be displayed.

How it all works

• tiki-metrics.php calculates the date range, and range type. It passes these parameters to metrics-tab.php for each tab
• metrics-tab.php grabs the tab content, runs it through smarty with the given metrics functions, and returns HTML output that then populates the tab
• metrics-tab also populates the arrays $m and $m_id, both associative arrays which contain the metrics data in the following format:

 $metric['result']

The query result, an array of rows with data returned by the metric query. This is an array of results of the SQL query. E.g. $metric['result'][0]['count'] will contain the actual count displayed result for the function:

{metric name="# new KB posts" count="count" }

And $metric['result'][1]['count'] will contain the first past result, etc.

 $metric['range']

The actual range in English (Weekly, Monthly, etc)

 $metric['range_id']

The range id (the value displayed in parentheses on the admin page)

 $metric['datatype']

The data type (Integer, Float, etc)

 $metric['datatype_id']

The data id (similar to range id, displayed in parentheses)

• $m['insert metric name here'] contains the above data (allows addressing metrics by name)
• $m_id[metric_id(integer)] contains the above data as well (allows addressing metrics by id)

These values can be fetched by using:

 {metric expr="@m['# new KB posts']['range_id']"}

The above gets the range_id of a metric named "# new KB posts" (case sensitive!)