docs: Add Stats Table documentation to Reporting & Dashboard#629
docs: Add Stats Table documentation to Reporting & Dashboard#629shijithkjayan wants to merge 4 commits into
Conversation
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
Warning Review limit reached
More reviews will be available in 47 minutes and 35 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more credits in the billing tab to continue. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThis pull request adds a new documentation article to Glific's user guides explaining the Stats Table analytics system. The article introduces five time period aggregations (Hour, Day, Week, Month, Summary) for stat records and recommends using Summary for stakeholder reporting. It documents the meaning and calculation approach for twelve key metrics including contacts, active, optin, optout, messages (broken down into inbound and outbound), hsm, flows_started, flows_completed, users, and conversations. The documentation includes important caveats about metric behavior—such as "active" measuring state change frequency rather than engagement count—and a "Common Pitfalls" section that addresses frequent misinterpretations of daily active counts, opt-in/out behavior across time periods, and relationships between message counts. 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
🚀 Deployed on https://deploy-preview-629--glific-docs.netlify.app |
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/4`. Product Features/09. Reporting & Dashboard/09. Understanding the
Stats Table.md:
- Around line 7-19: Add a short note to the "Time Periods" section of the Stats
Table docs that mentions the dimensional fields used for querying: state that
each stat record includes a date field and, for hourly rows, an hour field
(e.g., "Each stat record also includes a `date` field and an `hour` field for
hourly records to help filter and group by time"). Update the paragraph near the
top of the Time Periods table (where periods are defined) to include this
sentence so readers know to use `date` and `hour` when querying the stats table.
- Line 147: Update the sentence about messages so it's unambiguous: either
remove "(approximately)" and state "messages = inbound + outbound" exactly, or
keep the caveat and enumerate which records cause divergence (e.g.,
system-generated notifications, automated bot messages, delivery
receipts/failed-send system events, or deduplicated webhook retries) and explain
how they are counted in the time window; update the line referencing the fields
"messages", "inbound", and "outbound" in the Understanding the Stats Table doc
to include the chosen wording and a short concrete example of a system-generated
record that would make totals differ.
- Line 17: Reword the existing Summary description so it matches the schema's
`period=summary` meaning: replace the current wording that implies
weekly/monthly aggregation with a clear statement that `period=summary`
represents overall/all-time totals (e.g., `contacts` shows all-time total,
`users` shows total registered), and if you must mention weekly/monthly timing,
clarify those are only the refresh cadence for the snapshot (referencing the
`date` field) rather than different aggregation types.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 566c9743-502f-43b5-b084-affa42b5225c
📒 Files selected for processing (1)
docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md
| ## Time Periods | ||
|
|
||
| Every stat record belongs to one of five time periods. The same metrics are calculated for each period independently. | ||
|
|
||
| | Period | What it covers | | ||
| |---|---| | ||
| | **Hour** | A single hour of activity | | ||
| | **Day** | A full calendar day (midnight to midnight) | | ||
| | **Week** | A full calendar week (Monday to Sunday) | | ||
| | **Month** | A full calendar month | | ||
| | **Summary** | A special snapshot generated at the end of each week and month — it covers the entire week or month in one calculation and is the most reliable figure to use for reporting | | ||
|
|
||
| > **Recommendation**: Always use the **Summary** period for reporting to stakeholders. It is calculated in a single pass and avoids the inconsistencies that can appear when comparing daily rows. |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial | 💤 Low value
Consider briefly mentioning the date and hour fields for querying.
The Stats Table schema includes date and hour fields that users need when filtering records by time. While the current documentation focuses on explaining what each metric means, a brief note about these dimensional fields would help users understand how to query the data.
For example: "Each stat record also includes a date field (and hour field for hourly records) that indicates when the stats were recorded."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/4`. Product Features/09. Reporting & Dashboard/09. Understanding the
Stats Table.md around lines 7 - 19, Add a short note to the "Time Periods"
section of the Stats Table docs that mentions the dimensional fields used for
querying: state that each stat record includes a date field and, for hourly
rows, an hour field (e.g., "Each stat record also includes a `date` field and an
`hour` field for hourly records to help filter and group by time"). Update the
paragraph near the top of the Time Periods table (where periods are defined) to
include this sentence so readers know to use `date` and `hour` when querying the
stats table.
| | **Day** | A full calendar day (midnight to midnight) | | ||
| | **Week** | A full calendar week (Monday to Sunday) | | ||
| | **Month** | A full calendar month | | ||
| | **Summary** | A special snapshot generated at the end of each week and month — it covers the entire week or month in one calculation and is the most reliable figure to use for reporting | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify how Summary period is used in the stats table documentation
rg -n -C3 'period.*summary|summary.*period' --type=md -g '!*Stats Table*'Repository: glific/docs
Length of output: 885
🏁 Script executed:
#!/bin/bash
set -euo pipefail
FILE="docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md"
echo "== Lines 1-40 =="
nl -ba "$FILE" | sed -n '1,40p'
echo
echo "== All occurrences of 'summary' in target file (with context) =="
rg -n -C2 'summary' "$FILE" --type=md
echo
echo "== Where 'Summary' row is defined (best-effort) =="
rg -n 'Summary' "$FILE" --type=mdRepository: glific/docs
Length of output: 133
🏁 Script executed:
#!/bin/bash
set -euo pipefail
FILE="docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md"
echo "== Lines 1-60 =="
awk 'NR>=1 && NR<=60 {printf "%d:%s\n", NR, $0}' "$FILE"
echo
echo "== All occurrences of 'summary' (with context) =="
rg -n -C2 'summary' "$FILE" --type=md
echo
echo "== Occurrences of 'Summary' (with context) =="
rg -n -C2 'Summary' "$FILE" --type=mdRepository: glific/docs
Length of output: 6600
🏁 Script executed:
#!/bin/bash
set -euo pipefail
FILE="docs/8. FAQ/Glific BigQuery Tables Guide.md"
# Print around the line range where `period` is defined (from earlier rg output: ~535)
awk 'NR>=520 && NR<=560 {printf "%d:%s\n", NR, $0}' "$FILE"Repository: glific/docs
Length of output: 1793
Clarify “Summary” period wording to match the period=summary schema
The line-17 text (“generated at the end of each week and month…covers the entire week or month”) reads like Summary represents two different aggregation types. Upstream schema defines period with a single value summary = “overall totals”, and this doc’s field definitions also treat Summary as all-time totals (e.g., contacts Summary returns your all-time total; users Summary returns total user accounts registered). Reword line 17 to explicitly say period=summary is overall/all-time totals, and only mention weekly/monthly timing if you clarify it’s when the all-time totals snapshot is refreshed (e.g., via the date field).
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/4`. Product Features/09. Reporting & Dashboard/09. Understanding the
Stats Table.md at line 17, Reword the existing Summary description so it matches
the schema's `period=summary` meaning: replace the current wording that implies
weekly/monthly aggregation with a clear statement that `period=summary`
represents overall/all-time totals (e.g., `contacts` shows all-time total,
`users` shows total registered), and if you must mention weekly/monthly timing,
clarify those are only the refresh cadence for the snapshot (referencing the
`date` field) rather than different aggregation types.
|
|
||
| 3. **Weekly and daily figures may not add up perfectly.** Each is calculated independently, so small differences are expected. The Summary figure is always the authoritative number for a given period. | ||
|
|
||
| 4. **`messages` = `inbound` + `outbound` (approximately).** There may be a small difference due to system-generated messages, but these three fields should roughly balance. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Search for documentation about message counting logic
rg -n -C3 'messages.*inbound.*outbound|message.*count' --type=md -g '*BigQuery*'Repository: glific/docs
Length of output: 37
🏁 Script executed:
#!/bin/bash
set -euo pipefail
FILE='docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md'
echo '--- target file: show lines 120-170 ---'
sed -n '120,170p' "$FILE" | nl -ba | sed -e 's/^/LINE /'
echo '--- repo search for field definitions/wording ---'
rg -n --hidden --no-ignore-vcs \
'(Total messages|Messages received from contacts|Messages sent to contacts|system-generated|inbound|outbound|messages\s*=\s*inbound|messages.*inbound.*outbound)' \
--type=md docsRepository: glific/docs
Length of output: 156
🏁 Script executed:
#!/bin/bash
set -euo pipefail
FILE='docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md'
echo '--- target file: show lines 120-170 (with line numbers via awk) ---'
sed -n '120,170p' "$FILE" | awk '{printf "LINE %d: %s\n", NR+119, $0}'
echo '--- repo search for field definitions/wording ---'
rg -n --hidden --no-ignore-vcs \
'(Total messages|Messages received from contacts|Messages sent to contacts|system-generated|inbound|outbound|messages\s*=\s*inbound|messages.*inbound.*outbound)' \
--type=md docsRepository: glific/docs
Length of output: 4631
🏁 Script executed:
#!/bin/bash
set -euo pipefail
DOC1='docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md'
DOC2='docs/8. FAQ/Glific BigQuery Tables Guide.md'
echo '--- target file: show lines 50-110 ---'
sed -n '50,110p' "$DOC1" | awk '{print NR+49 ":" $0}'
echo '--- target file: show around Common Pitfalls line 139-150 ---'
sed -n '135,155p' "$DOC1" | awk '{print NR+134 ":" $0}'
echo '--- BigQuery guide: show around messages/inbound/outbound definitions (510-560) ---'
sed -n '510,560p' "$DOC2" | awk '{print NR+509 ":" $0}'
echo '--- search docs for "system-generated" ---'
rg -n --hidden --no-ignore-vcs 'system-generated' --type=md docsRepository: glific/docs
Length of output: 6310
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n --hidden --no-ignore-vcs \
'(system[- ]generated|system message|generated message|other direction|flow direction.*null|inbound \+ outbound|inbound.*outbound.*balance|roughly balance|messages.*inbound.*outbound)' \
--type=md docsRepository: glific/docs
Length of output: 517
Align messages vs inbound+outbound wording with the documented definition
In docs/4. Product Features/09. Reporting & Dashboard/09. Understanding the Stats Table.md, messages is already defined as “all message records (inbound + outbound)” for the time window, and the BigQuery guide defines the same relationship. The “(approximately)” + “system-generated messages” caveat at line 147 isn’t explained anywhere else in the docs—either state the relationship without “approximately” or add a concrete description of which message records cause divergence.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/4`. Product Features/09. Reporting & Dashboard/09. Understanding the
Stats Table.md at line 147, Update the sentence about messages so it's
unambiguous: either remove "(approximately)" and state "messages = inbound +
outbound" exactly, or keep the caveat and enumerate which records cause
divergence (e.g., system-generated notifications, automated bot messages,
delivery receipts/failed-send system events, or deduplicated webhook retries)
and explain how they are counted in the time window; update the line referencing
the fields "messages", "inbound", and "outbound" in the Understanding the Stats
Table doc to include the chosen wording and a short concrete example of a
system-generated record that would make totals differ.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 participant
Summary
09. Understanding the Stats Table.mdto the Reporting & Dashboard sectioncontacts,active,optin,optout,messages,inbound,outbound,hsm,flows_started,flows_completed,users,conversations)Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit