New processed metric metadata: processed metric formula

[diosmosis]

Summary

Refs matomo-org/looker-studio-connector#3
Refs matomo-org/looker-studio-connector#29
Refs #21936

In order for Looker Studio to further group processed metric data in reports after they are requested from Matomo, Looker Studio needs to know the formula used to compute these metrics. For example, bounce_rate is computed as bounce_count / nb_visits. Giving this formula to Looker Studio will allow it to aggregate different bounce_rates together.

Exposing this information via Matomo's metadata API will allow the connector to forward this information to Looker Studio.

Formula should provide the unformatted values, and, ideally, it should be possible to express these formulae via Looker Studio arithmetic/functions supported by Looker Studio (https://support.google.com/looker-studio/table/6379764).

Example API output:

<metadata>
    <processedMetricFormula>
        <bounce_rate>bounce_count / nb_visits</bounce_rate>
        <avg_time_on_page>sum_time_spent / nb_hits</avg_time_on_page>
    </processedMetricFormula>
</metadata>

[diosmosis]

Been looking into this, and for some processed/computed metrics, this is simple to add (ie, BounceRate, etc.). Some processed metrics contain complex logic that can't (and shouldn't) be expressed as formula metadata, like https://github.com/matomo-org/matomo/blob/5.x-dev/plugins/Goals/Columns/Metrics/RevenuePerVisit.php.

To be able to properly add this metadata, in a way that allows the new metadata to be easily maintained (ie, kept in sync with the actual code), it would likely be necessary to change how ProcessedMetrics work, reducing their responsibility. Instead of allowing arbitrary logic, they would need to be limited to simple operations, and the temporary metrics they use would have to be directly available as other column values.

So processed metrics like EvolutionMetric would need to have the past data included in the result DataTable, as opposed to in another DataTable. And RevenuePerVisit would need the goals array metric to be flattened. Given this would be a significant change, it's probably better the core team handle it, after deciding on what their solution would be.