Archive data is created during the archiving process by aggregating log data.
Piwik aggregates and persists two types of archive data:
Reports will normally contain metric values, but they can also contain other data (either additionally or in lieu of metric values).
Reports and metrics are defined by plugins, letting any plugin extend the data analyzed by Piwik. However, there are several metrics, called core metrics, that are defined by Piwik Core.
Reports and metrics provide analytics data about a set of things. This set is defined by three constraints:
The website ID selects visits that were tracked for a specific website. This ID is specified in all HTTP requests with the
idSite query parameter.
The period selects visits that were tracked within a specific date range. The period is specified in all HTTP requests with the
period query parameters.
The segment selects visits based on a boolean expression that uses visit properties. It is specified in all HTTP requests by the
segment query parameter and can be used to select almost any conceivable subset of visit.
Analytics parameters are stored in reports as metadata, that means they are stored as DataTable metadata.
Core metrics are metrics that are not defined by plugins but by Piwik Core.
New reports that analyze visits, action types or conversions should contain these metrics.
Core metrics for a set of visits:
||Number of tracked visits.
A visit is series of events each of which happened no more than 30 minutes apart.
||The number of unique sources of visits.
A visit source is an entity that causes a visit to be tracked.
||The number of tracked actions.
An action is an event tracked by Piwik.
||The maximum number of actions that occurred in one visit.|
|Sum Visit Length||
||The sum of each visit's elapsed time.|
||The number of visits that consisted of only one action.|
||The number of visits that caused at least one conversion.
Includes conversions for every goal of a site.
||The number of conversions tracked for this set of visits.
Includes conversions for every goal of a site.
||The total revenue generated by these visits.
Includes revenue for every goal of a site plus its ecommerce revenue.
Core metrics for a single action type:
||The number times this action was ever done.|
|Sum Time Spent||
||The total amount of time the user spent doing this action.|
|Sum Page Generation Time||
||The total amount of time a server spent serving this action.|
|Hits With Generation Time||
||The number of hits that included generation time information.|
|Min Page Generation Time||
||The minimum amount of time a server spent serving this action.|
|Max Page Generation Time||
||The maximum amount of time a server spent serving this action.|
|Unique Exit Visitors||
||The number of unique visitors that ever exited a site after this action.|
||The total number of visits that ended with this action.|
|Unique Entry Visitors||
||The total number of unique visitors that started a visit with this action.|
||The total number of visits that started with this action.|
|Entry Sum Visit Length||
||The sum of each entry visit's elapsed time.|
|Entry Bounce Count||
||The number of visits that consisted of this action and no other.|
|Hits From Search||
||The number of times this action was done after a site search.|
Core metrics for the set of ecommerce conversions (either all orders or all abandoned carts) recorded for a set of visits:
||The total cost of every item that was a part of these orders or abandoned carts.|
||The total tax amount applied to these orders/abandoned carts.|
||The total amount of shipping applied to these orders/abandoned carts.|
||The total amount of discounts applied to these orders/abandoned carts.|
|Ecommerce Item Count||
||The total number of items in these orders/abandoned carts.|
Core metrics for a set of visits and one goal of a site:
||The conversions tracked for a specific goal and this set of visits.|
||The total revenue generated by the conversions for a specific goal.|
<idGoal> should be replaced with the ID of a goal.
Goal specific metrics are stored in the database in the
goals column of serialized reports. The column contains a PHP array mapping goal IDs with arrays of goal specific metric values. These values are set as normal column values with the metric names described above by the AddColumnsProcessedMetricsGoal DataTable filter.
In the interests of archiving and database size efficiency, some metrics are not stored in database. They are instead calculated when needed using other metrics. These metrics are called processed metrics.
Below is the list of processed metrics that are calculated using core metrics. New reports that analyze visits, action types or conversions should have these metrics added when possible.
Note: Some processed metrics will appear multiple times in the lists below. These metrics have different meanings based on the reports they are in.
Processed metrics for a set of visits:
||The percent of visits that had at least one conversion.|
|Actions Per Visit||
||The average number of actions for a single visit.|
|Average Time On Site||
||The average number of time spent per visit in seconds.|
||The percent of visits that resulted in a bounce.|
Processed metrics for a single action type:
|Average Generation Time||
||The average amount of time it took for a server to serve this action.|
|Average Number of Search Result Pages Viewed||
||The average number of search result pages viewed after a site search.
Only valid for site search keywords and site search categories.
|Average Time On Page||
||The average amount of time users spent doing this action.|
|Entry Bounce Rate||
||The percent of all visits that consisted of this action and no other.|
||The percent of all visits that ended with this action.|
Processed metrics for the set of ecommerce orders recorded for a set of visits:
|Average Order Revenue||
||The average revenue of each order.|
Processed metrics for the set of ecommerce items in a set of orders or abandoned carts:
||The average price of each item.|
||The average number of each item in an order/abandoned cart.|
|Product Conversion Rate||
||The percent of orders/abandoned carts that include this item.|
The following is a list of processed metrics that are also specific to one goal of one site:
|Average Revenue per Visit||
||The average amount of revenue generated per visit for this goal.|
Metrics calculated and persisted by plugins must be named with the following format:
PluginName_metricName. For example:
Core metrics have special names and do not follow this convention.
Reports are stored in memory using the
DataTable class. A
DataTable is a 2-dimension array composed of rows and columns.
Each row contains metrics that relate to a set of visits, actions, conversions… That set is defined and described by a special label column. How the column describes the set depends entirely upon the specific report. For example in the
UserSettings.getBrowser report, a row with the label Firefox would hold metrics for visits that used the Firefox browser.
Some reports like
VisitsSummary.get will not have a label column: they have only one row that refers to the entire set of entities.
In addition to metrics, each row can also contain metadata. This metadata will usually assist the label column in describing the set of things the row represents.
Some metadata have special meaning in Piwik, for example:
logo: the value can be a path to an image that will be shown alongside each row in the UI
url: the value can be a URL to which the row will link in the UI
Reports can be hierarchical: each row can be attached to another DataTable. Tables that are attached to rows are called subtables.
Subtables provide further analytics for the set of visits that a row represents. For example, the
Referrers.getSearchEngines report has one row per search engine. Each row has a subtable that describes keywords used with that search engine. Here is a schematic representation:
Search Engine Keyword (subtable) Visitors --------------|-------------------|---------- Google | 207 --------------|------------------------------ | piwik | 11 | libre analytics | 6 | ... --------------------------------------------- Duck Duck Go | 121 --------------|------------------------------ | ...
Reports must be named like metrics are:
PluginName_reportName. For example: