Report glossary

Every report, what each column counts, and what it does not.

Every reporting landing page under the Reports menu is a shell of permission-gated tabs; each tab has its own view-report-* permission. The sections below group those tabs by what they actually query, since that's what determines how fresh and how granular the numbers are.

Account reports

Tabs: Summary, Expiry, Creator/Creation, Voucher Activation, Voucher Availability, Voucher Groups, Topup Availability. All read kiwire_users live — not a report bucket — so these always reflect the current state of the accounts table, not a snapshot from some earlier hour.

• ktype — voucher (one-time code), account (registered login), simcard.
• status — active, inactive, expired, suspend/suspended (both spellings exist in the data — voucher/PMS/bulk-update paths write suspend, everything else writes suspended; reports that bucket by status combine both).

Voucher Groups (view-report-account-voucher-groups) — one row per voucher batch, which the report calls a group. How to fill in the group details is in Counting group visits with vouchers.

• Date — the batch's visit date; otherwise the first time any of its codes was used; otherwise when the batch was created. The source is printed under the date and in the CSV (Date Source). Periods and dates are in the tenant's timezone.
• Show — With group details counts only batches with a name, visit date or number of people; All batches counts every batch that still has codes. Vouchers created one at a time without group details are never counted. Scheduled copies use With group details.
• People — the number of people entered on the batch. Blank when not entered; blanks add nothing to the total, and the tile's tooltip says how many groups have a headcount.
• Codes issued / Codes used — codes still in the batch now (deleted codes are not counted); a code is used once it has an activation date or at least one login.
• Devices — distinct device MACs that have logged in with any code in the batch. Not a headcount: a shared code can serve many people on one device, and one person can bring two.
• Data (MB) — upload plus download over the life of the batch's codes.
• Range: whole months, up to 24 at a time; grouped by month or year.

Voucher Utilization (view-report-account-voucher-utilization) — how well the vouchers created in the range were used, one row per batch, profile or zone (Group by).

• States — every code is in exactly one, checked in this order, so they add up to Codes: Used (an activation date or at least one login — the same test as Voucher Groups and Voucher Availability) → Suspended (never used, status suspend/suspended) → Expired unused (never used, status expired or expiry date already past) → Unused (valid) (everything else: still sellable stock).
• Data / Time — upload plus download and session time totalled over the life of the codes, from the running totals accounting keeps on each account. Avg per used code divides by used codes only.
• Devices (batch view) — distinct device MACs that logged in with the batch's codes.
• Value issued / used / expired unused — face value (price on each code) in the tenant's currency. It is not money taken: payments are in Finance and the Payment Transactions report.
• Batch — vouchers created one at a time share one row, Individual vouchers. Profile is the profile the code was issued with. Zone is the zone list the code is restricted to (Any zone when unrestricted), not where it was used.
• Share used by period — of the codes created in each day/week/month, the percentage used so far. Recent periods are still filling up, so a falling line at the end is normal.
• Range: up to 366 days, default the last 90 days including today. The detail panel lists up to 1,000 codes (heaviest data users first); the detail CSV has every code.

Login reports

The largest group of tabs (Active Session, Summary, Frequency, Frequency by Profile, Dwell Time, Dwell Time by Profile, Session Concurrency, Return Account Summary, Device Frequency, Heatmap, Zone Comparison, Login Error, Browser Fingerprint, Auto Login, Termination). Two different sources back them:

• Live — Active Session reads kiwire_active_session directly: currently-connected devices, no aggregation delay.
• Hourly buckets — everything else reads a monthly table named kiwire_report_login_general_YYYYMM (or a sibling: kiwire_report_login_profile_YYYYMM for the by-profile tabs, kiwire_report_login_dwell_YYYYMM for dwell-time buckets, kiwire_report_login_error_YYYYMM for Login Error, kiwire_report_login_device_YYYYMM for Device Insight under Insight reports). These are created on demand, as a copy of the base template table, the first time a month needs one.

Data freshness — the hourly buckets are not written directly. Kiwire increments Redis counters per tenant/zone/hour as events happen; the scheduled command kiwire:aggregate-reports runs hourly at :05 and flushes the previous completed hour's Redis counters into the monthly MySQL table, then deletes those Redis keys. That means the current hour — and up to the first five minutes of the next hour, before the cron runs — has no row in any kiwire_report_login_* table yet. A report queried at 14:03 will not show anything from 14:00 onward, and may not yet show the 13:00 hour either if the :05 run hasn't landed.

The Login Error tab aggregates by date + error type; the error types are the AUTH:* rule-engine labels raised by the login check — e.g. AUTH:invalid_credentials, AUTH:account_suspended, AUTH:zone_access_denied, AUTH:time_limit_reached, AUTH:quota_limit_reached, AUTH:max_simultaneous_reached — see Portal error codes for what triggers each one.

The Heatmap tab buckets successful logins by weekday × hour from the same hourly table; its "Average" mode divides each cell by how many times that weekday occurred in the selected range, so a 30-day window and a 7-day window are comparable.

Bandwidth reports

• Summary, Vs Login — hourly buckets (kiwire_report_login_general_YYYYMM), same freshness caveat as Login reports.
• Account, Top Usage — read the monthly session tables (kiwire_sessions_YYYYMM, UNION ALL'd across months in range) instead of the hourly buckets. These are written per-session (start/interim-update/stop), so they're more granular than an hourly rollup, but a session in progress won't show its final totals until it closes or its next interim-update lands (interval set by the profile's reply:Acct-Interim-Interval, default 300 s).
• Current Top — genuinely live: reads kiwire_active_session directly, ranked by download (quota_out). No aggregation delay at all.

DPI

Deep Packet Inspection — only available for ubnt-console (UniFi) controllers. Unlike every other report, this data isn't stored in Kiwire's own database at all: it's pulled live from the UniFi controller's own API for a 1/6/24-hour window, cached for 2–5 minutes to avoid hammering the controller. Two tabs:

• Site-level — per-application/category traffic totals (rx/tx bytes) for the whole UniFi site.
• By Client — per-client DPI breakdown, plus a session list for that controller (either currently-active sessions from kiwire_active_session, or the last 24 hours including disconnected sessions from the current month's kiwire_sessions_YYYYMM).

Impression and engagement

All from the hourly kiwire_report_login_general_YYYYMM bucket (same freshness caveat as Login reports), plus a campaign-specific variant:

• impression — a portal page render served to a guest device (SUM(impression)).
• login_total (succeed) / login_unique (account_unique) — successful logins and unique accounts in the same range, shown alongside impressions as the summary KPIs.
• impress / u_impress — per-campaign impressions / unique impressions, grouped by campaign name + source.
• click / u_click — per-campaign clicks / unique clicks.
• execute_total — offline-campaign executions (SUM(execute)); offline campaigns are always recorded under zone nozone since they aren't zone-scoped, so no zone filter applies to that tab.

Delivery log

Three independently-permissioned tabs:

• SMS, Email send logs — daily totals from the hourly kiwire_report_login_general_YYYYMM bucket, capped at a 30-day range. Same freshness caveat as Login reports.
• PMS — reads kiwire_int_pms_transaction directly (not a report bucket, so no aggregation delay): check_in_date, check_out_date, room, first_name, last_name, status, vip_code. Capped at a 30-day range and 5,000 rows.

Insight

• Device Insight — device class + brand aggregates from the hourly kiwire_report_login_device_YYYYMM bucket.
• Registration Insight — raw, per-account rows straight from kiwire_users (created_at, username, fullname, email_address, phone_number, login_type, register_from_nas, register_from_zone, status, plus a hidden extra_fields column shown only in the row detail view) — live, not aggregated.
• Social Network Insight — type / gender / age-group aggregates computed live from kiwire_users where login_type is a non-empty, non-system value (i.e. a social login).
• Social Network Data — the raw per-account rows behind that aggregate, filterable by network type, same live source.

Payment

Payment Transactions reads the monthly-partitioned kiwire_payment_transactions_YYYYMM tables directly — live, not the hourly bucket, since it reflects the payment gateway/webhook state as it happens. Columns: reference, username, plan_label, amount, provider, status, paid_at.

• status — pending, paid, failed, cancelled.
• provider filter options come from the tenant's configured payment-gateway connectors (e.g. Stripe, Billplz) — only providers actually set up for the tenant appear.