analytics
Read Site Analytics reports, manage recordings and submit trusted server-side events.
Model paths
| GET path | Result | Permission |
|---|---|---|
recordings | Recording maps in saved order. | use mod_analytics |
overview | Map with panels and period for non-paused recordings. | use mod_analytics |
dashboard | Recordings, selected recording and its report. | use mod_analytics |
configuration | Recordings, event schemas, dimensions, status and storage usage. | Site administrator |
status | Current ingestion worker status. | Site administrator |
registry | List of declared event schemas. | Site administrator |
info/<id> | Recording details and stored payload/bucket usage. | Site administrator |
For example, {% for recording in m.analytics.recordings %}{{ recording.name|escape }}{% endfor %}
lists the configured recordings. Model GET callbacks return {ok, {Value, Rest}}.
Access failures return {error, eacces}; unsupported paths return {error, unknown_path}.
Site administrator checks use z_acl:is_admin/1, including use mod_admin_config.
POST create accepts a definition map; state/<id> accepts a map with binary key
state (active or paused); order accepts the full list of recording IDs.
These operations enforce administrator access. Deletion is available through purge/2
and the configuration page's confirmation flow, not a public model POST path.
Erlang reporting and configuration
overview(Period, Context) returns all non-paused recording panels; dashboard(Id, Period, Context)
returns one selected report with the recording list. Both enforce use mod_analytics.
Period keys are hour, day (six hours), 24hours, week, month, year and years.
Unknown periods use six hours. Reports contain aggregate counts; popular-content counts
are lower bounds with approximation metadata. configuration/1 enforces administrator access.
create(Definition, State, Context) accepts binary keys name, optional description,
event, dimension, groups and filters. Filters map dimension names to lists of
allowed values; an empty dimension records totals only. Initial state can be active,
paused or draft. Success returns {ok, Id}; invalid definitions, duplicate recordings
and exhausted storage budgets return errors. set_state/3, reorder/2 and purge/2
also enforce administrator access. Purging permanently deletes a recording and its history.
Trusted event API
After declaring an event in an observe_analytics_events/3 fold observer, submit it with:
m_analytics:record_event(<<"mod_newsletter:sent">>,
#{<<"kind">> => <<"digest">>}, Context).
record_event/3 does not implicitly associate the context's request. For request-associated
measurement use record_event(Name, Properties, z_context:get_reqdata(Context), Context).
The request must match the context. Request exclusions apply, and schema-declared request
dimensions are added by the server; callers cannot override these derived properties.
These are trusted Erlang APIs, not public model POST routes or administrator-only actions.
The calling module is responsible for its domain permissions and for avoiding personal data.
registry/1 is an internal Erlang schema lookup without the model GET permission check.
The store_* functions are trusted persistence APIs used by schema installation and
background workers; they do not enforce user ACLs and are not exposed as model routes.
Recording returns ok or {error, Reason}. Excluded requests return ok without recording;
an accepted event is not a durable-write acknowledgement. Invalid requests, unknown events,
invalid properties and full ingestion queues can return errors. Analytics failure should
not fail the domain operation. mark_page(Id, Context) returns an updated context marking
a custom controller's page; normal public-page eligibility checks still apply.