Metrics
Metrics define what exactly your widgets measure. Metriox supports four metrics, and together they cover most analytics scenarios.
Core metrics
1. Events
Counts the total number of events.
Formula: COUNT(events)
When to use it:
- Overall activity in the bot
- How often an action happens
- How much a feature is used
Examples:
| Question | Metric | Filter | Result |
|---|---|---|---|
| How many times was the "Buy" button clicked? | Events | Event Name equals "button_click" AND button_name equals "buy" | 1,542 events |
| How many messages were sent in a day? | Events | Event Name equals "message_sent" | 12,345 events |
Details:
- A single user can generate many events
- It says nothing about how many users are behind them
- Useful for measuring usage intensity
Widgets:
- Series: how the event count changes over time
- Top: the most frequent events
- KPI: the total for the period
- Table: a breakdown by category
2. Users
Counts the number of unique people who did something themselves during the period.
Not counted: recipients of messages the bot sent (a broadcast does not make someone active), the bot itself, and rows with no identifiable author. In a group, every member who posted is counted rather than the group. See Vitals.
Formula: COUNT(DISTINCT event author), where the author comes from $tg.from_id, falling back to platform_user_id when it is absent
When to use it:
- Active user counts (DAU, MAU)
- Audience reach
- Whether an action is unique per user
Examples:
| Question | Metric | Filter | Time range | Result |
|---|---|---|---|---|
| How many users bought a subscription? | Users | (prop) tg.callback_data (op) equals "purchase_completed" | — | 342 users |
| DAU (Daily Active Users) | Users | any events | the range you select | 3,542 users |
| User activity | Events per User | any events | last 24 hours | 12,51 events per user |
Details:
- Every user is counted only once
- It is the basis for conversion calculations
- Important for sizing your audience
Widgets:
- KPI: active users
- Series: DAU/MAU over time
- Funnel: conversion between steps
- Top: the most active users (by user_id)
3. Events per User
Calculates the average number of events per unique user.
Formula: COUNT(events) / COUNT(DISTINCT platform_user_id)
When to use it:
- Usage intensity
- Engagement
- Comparing activity across segments
Examples:
| Question | Metric | Filter | Result |
|---|---|---|---|
| How many messages does a user send on average? | Events per User | Event Name equals "message_sent" | 8.7 events per user |
Details:
- Shows how deeply users engage
- Normalizes metrics across segments
- Can be a fractional number
Widgets:
- KPI: average activity
- Series: engagement over time
- Table: segment comparison
- Top: groups by activity
4. Sum
Adds up the values of a single numeric property — payment totals, for example.
Formula: SUM(property value) over the events of one source
Unlike the other metrics, Sum needs two settings:
- Property — which numeric field to add up, e.g.
$tg.total_amount. Only numeric properties are offered: summing a text field would not raise an error, it would quietly return zero. - Source — whose events to count (Bot API, the MTProto worker, Mini App).
Why the source is mandatory. If a bot is connected through both the SDK and the MTProto worker, the same payment is recorded twice — they are separate sources and they do not collapse into one record. Without pinning to a single source a money figure would double. On a bot with one source it would look perfectly correct, which is what makes the mistake so hard to notice, so the server refuses a request without a source rather than assuming one.
Such an event is billed once — but both rows stay in storage, precisely so that a report pinned to one source still finds its data. Deduplication applies to the quota, not to the rows, which is why naming a source remains mandatory for money metrics.
Values are not converted. Sums come back exactly as Telegram sends them — in smallest units (Stars,
cents), never converted between currencies. Group by $tg.currency to keep currencies apart: several
correct numbers are more useful than one meaningless one.
Examples:
| Question | Metric | Settings | Result |
|---|---|---|---|
| How many Stars were spent this week? | Sum | $tg.total_amount, Bot API source | 48,250 |
| Revenue by currency | Sum | $tg.total_amount, grouped by $tg.currency | several rows |
Widgets: Series, Top, Table, KPI. It is unavailable on Histogram and Heatmap — there is nowhere to name the property and source there, so such a request is refused rather than quietly summed across every source.
Comparing the metrics
| Metric | What it counts | When to use it |
|---|---|---|
| Events | Total number of events | Volume, frequency, intensity |
| Users | Unique users | Reach, DAU/MAU, conversion |
| Events per User | Average events per user | Engagement |
| Sum | The total of a numeric property | Money, order values, any numeric field |
Comparison example
The button_click event over a 7-day period:
| Metric | Value |
|---|---|
| Events | 10,000 events |
| Users | 2,500 users |
| Events per User | 4.0 events per user |
How to read it:
- There were 10,000 clicks
- 2,500 unique users clicked
- On average each user clicked 4 times
Using metrics in widgets
Top widget
Available metrics:
- Events — top events by frequency
- Users — top events by reach
- Events per User — top events by engagement
- Sum — top by the total of a numeric property (revenue by currency, for example)
Example — the top 5 events by Users:
| Event | Users |
|---|---|
bot_started | 3,542 users |
screen_view | 2,987 users |
button_click | 2,314 users |
purchase_viewed | 1,234 users |
message_sent | 876 users |
Funnel widget
Available metric:
- Users (only)
Why only Users?
- A funnel tracks the path users take
- Events can repeat
- Conversion is measured in users
Example:
| Step | Users | Conversion |
|---|---|---|
1. bot_started | 10,000 | — |
2. view_pricing | 3,500 | 35% conversion |
3. purchase_completed | 850 | 8.5% from the start |
Table widget
Available metrics:
- All four metrics at once
Example:
| Event | Events | Users | Events/User |
|---|---|---|---|
| button_click | 10,000 | 2,500 | 4.0 |
| screen_view | 15,000 | 3,000 | 5.0 |
| message_sent | 8,000 | 1,000 | 8.0 |
KPI widget
Available metrics:
- Any single metric
Examples:
| Key metric | Value | Change | Metric |
|---|---|---|---|
| DAU | 3,542 | ↑ 8% vs yesterday | Users |
| Average activity | 12.7 events/user | ↑ 5% vs last week | Events per User |
Histogram widget
Available metrics:
- Events
- Users
Sum is unavailable here: a Histogram has nowhere to name the property and source.
Example — the distribution of activity by hour of day with the Users metric.
Series widget
Available metrics:
- All four metrics (several lines are allowed)
Practical examples
DAU, WAU, MAU
| Key metric | Metric | Filter | Time range |
|---|---|---|---|
| DAU (Daily Active Users) | Users | any events | a day |
On the Vitals page these three report the last complete UTC calendar day, week and month rather than a rolling 24 hours / 7 / 30 days. In your own widget you choose the range.
| WAU (Weekly Active Users) | Users | any events | last 7 days | | MAU (Monthly Active Users) | Users | any events | last 30 days |
Purchase conversion
A funnel on the Users metric:
| Step | Users | Share of the start |
|---|---|---|
1. bot_started | 10,000 | 100% |
2. view_pricing | 3,500 | 35% |
3. purchase_completed | 850 | 8.5% |
Conversion = 850 / 10,000 = 8.5%
Engagement metrics
Average number of screens per user:
| Metric | Filter | Result |
|---|---|---|
| Events per User | Event Name equals "screen_view" | 7.2 screens per user |
Premium vs free activity:
| Segment | Events | Users | Events/User |
|---|---|---|---|
| Premium | 5,000 | 250 | 20.0 |
| Free | 8,000 | 2,000 | 4.0 |
Premium users are 5 times more active.
Retention analysis
Counting returning users:
| Metric | Filter | Time range |
|---|---|---|
| Users | days_since_signup > "7" | last 24 hours |
Result:
| Period | Users |
|---|---|
| Day 0 | 1,000 new users |
| Day 7 | 350 active (35% retention) |
Best practices
Choosing a metric
Events:
- How many times an action was performed
- Total volume of activity
- Not suitable for counting users
Users:
- How many users performed an action
- DAU, MAU, reach
- Conversion funnels
- Does not show usage intensity
Events per User:
- How active your users are
- Comparing engagement across segments
- Behaviour changes over time
- Can be skewed when the user count is small
Combining metrics
Use several metrics together for the full picture:
- KPI dashboard
- DAU (Users)
- Overall activity (Events)
- Average activity (Events per User)
- Series chart
- Line 1 — Users (left-hand scale)
- Line 2 — Events per User (right-hand scale)
Interpreting results
- Events grow while Users stay flat — your existing users became more active
- Users grow while Events per User falls — an influx of new, less active users
- Events and Users grow proportionally — healthy product growth
Technical details
How ClickHouse computes them
Events:
SELECT COUNT(*) FROM events WHERE ...
Users:
SELECT COUNT(DISTINCT platform_user_id) FROM events WHERE ...
Events per User:
SELECT
COUNT(*) / COUNT(DISTINCT platform_user_id)
FROM events WHERE ...
Performance
- Events: the fastest metric
- Users: requires deduplication (slower)
- Events per User: two operations (the slowest)
Optimization:
- Use filters to reduce the volume of data
- Keep the time range narrow
- Cache frequently used queries