= Metrics

Metrics calculations must be executed everyday. Some `rake task` have been added to perform it.

* To execute all metrics at once. Related to previous date from _today_
+
[source,ruby]
----
bundle exec rake decidim:metrics:all
----

* To execute an specific metric. Related to previous date from _today_
+
[source,ruby]
----
bundle exec rake decidim:metrics:one["<metric name>"]
----

* To execute metrics for a given date (all or an specific one)
+
[source,ruby]
----
bundle exec rake decidim:metrics:all["YYYY-MM-DD"]
bundle exec rake decidim:metrics:one["<metric name>","YYYY-MM-DD"]
----

* It is possible to rebuild one or all metrics since some specific day. This is useful in case current metrics are no generated or corrupt. *Depending on the size of the database this can take a long time!*. The command will execute the same calculations as the commands above for *each* day between _today_ and the date specified.
* To rebuild metrics since a given date (all or an specific one)
+
[source,ruby]
----
bundle exec rake decidim:metrics:rebuild["YYYY-MM-DD"]
bundle exec rake decidim:metrics:rebuild["<metric name>","YYYY-MM-DD"]
----

== Available metrics

* Use the command `decidim:metrics:list` to list all available metrics using the console:

[source,ruby]
----
bundle exec rake decidim:metrics:list
----

Currently, available metrics are:

* *users*, created `Users`
* *proposals*, published, not withdrawn and not _hidden_ `Proposals`
* *accepted_proposals*, accepted `Proposals`
* *supports*, supports given to `Proposals`
* *assemblies*, published `Assemblies`
* *participatory_processes*, published `ParticipatoryProcesses`
* *results*, `Results` in `Accountability`
* *comments*, `Comments` generated by users, related to public elements and not _hidden_
* *meetings*, public `Meetings`

Only available for `ParticipatorySpaces` (restricted to `ParticipatoryProcesses`)

* *participants*, unique users who make at least one of the following actions:
 ** Answer a survey
 ** Create a debate
 ** Create a proposal
 ** Endorse a proposal
 ** Leave a comment
 ** Support a proposal
 ** Vote a participatory budgeting project
* *followers*, unique users who follow any participatory element in a `ParticipatorySpace`
* *endorsements*, number of `Endorsements` in `Proposals`, within a `ParticipatorySpace`
* *debates*, number of `Debates` within a `ParticipatorySpace`
* *survey_answers*, number of answered `Surveys` by users within a `ParticipatorySpace`

== Configuration

* A *crontab* line must be added to your server to maintain them updated daily. You could use https://github.com/javan/whenever[Whenever] to manage it directly from the APP. You probably want to schedule a `bundle exec rake decidim:metrics:all` every night.
* An *ActiveJob* queue, like https://github.com/mperham/sidekiq[Sidekiq] or https://github.com/collectiveidea/delayed_job/[DelayedJob]

== Persistence

The metrics module percomutes calculations and persists them into
`decidim_metrics` database table. So this module only uses one single table to
persist metrics from all times and types.

The `decidim_metrics` table has the following fields:

* `day`: the day for which the metric has been computed.
* `metric_type`: the type of the metric. One of: users, proposals, accepted_proposals, supports, assemblies.
* `cumulative`: quantity accumulated to day `"day`".
* `quantity`:  quantity for the current day, `"day`".
* `decidim_organization_id`: the FK to the organization to which this Metric belongs to.
* `participatory_space_type` + `participatory_space_id`: the FK to the participatory space to which this Metric belongs to, if any.
* `related_object_type` + `related_object_id`: the FK to the object to which this Metric belongs to, if any.
* `decidim_category_id`: the FK to the category for this Metric, if any.

Relations around `decidim_metrics` table:

[source,ascii]
----
                                                    +------------------------+
+--------------+                                    | ParticipatoryProcesses |
| Organization |                               +----+------------------------+
+------+-------+                               |
       |            +--------------------+     |    +------------+
       |            |                    |     +----+ Assemblies |
       |     +----->+ ParticipatorySpace +<----+    +------------+
       |     |      |                    |     |    +-------------+
       |     |      +--------------------+     +----+ Initiatives |
       |     |                                      +-------------+
       |     |
       |     |
 +-----+-------+---+
 |                 |
 | decidim_metrics |
 |                 |
 +--------+--------+       +----------------+
          |                | related_object |
          +--------------->+                |
                           | [polymorphic]  |
                           +----------------+
----

== Troubleshooting

If you find problems in your metrics numbers you can follow the guide xref:develop:troubleshooting_metrics.adoc[Troubleshooting metrics].