You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/web/docs/site-analytics.md

71 lines
2.7 KiB
Markdown

# Site analytics
This feature stores first-party page-view statistics in the configured log
database. It does not use an external analytics script, npm, Redis, or a
third-party analytics service.
## Database
Import the schema into `log_db_database`:
```bash
mysql -u LOG_USER -p LOG_DATABASE < sql/site_analytics.sql
```
The three active tables are:
- `site_visit_events`: raw page views (no automatic deletion)
- `site_visit_daily_stats`: long-term daily aggregates, including per-IP counts
- `site_security_events`: abnormal request records (no automatic deletion)
An installation that previously imported `site_redirect_links` may leave that
table in place or remove it manually. The application no longer reads or writes
it.
## Collection rules
Every successful browser navigation is recorded as one page view. This includes
the home page, login and registration pages, and authenticated `/user` pages.
A first-party visitor cookie is retained for one year, while the session cookie
uses a sliding 30-minute lifetime for UV and session counts.
Administrator pages, APIs, internal endpoints, subscription links, payment
callbacks, password-reset paths, AJAX requests, JSON polling requests, static
assets, bots, and state-changing GET actions are not recorded. Query strings,
cookies, authorization headers, and form contents are never stored.
The administrator view includes a top-20 visitor IP ranking with PV, UV, and
location. Location lookup uses the local `storage/qqwry.dat` file and never
sends visitor IPs to an external service. If the file is missing, provide a
trusted, updated QQWry database manually. The old download command is removed.
## Abnormal requests
The security view records `401`, `403`, `404`, and `405` responses, redirects
away from protected administrator routes, unusual HTTP methods, traversal
attempts, sensitive-file probes, common software probes, and executable-script
paths. Static-file 404 noise is ignored unless the path matches a security
rule.
Logged-in requests are associated with the numeric user ID. Anonymous requests
use the direct connection IP and a daily keyed IP hash. Query strings are never
stored, and subscription or password-reset path tokens are replaced with
`{redacted}`. Repeated generic 404 requests from the same source are merged into
one row per five-minute window to limit database growth.
## Scheduled aggregation
Run the included job every five minutes:
```cron
*/5 * * * * cd /YOUR/VIRT-CLOUD/web && php xcat siteAnalyticsJob 2 >> storage/logs/site_analytics.log 2>&1
```
The argument refreshes today and yesterday. Aggregation does not delete page
views or security records; all automatic cleanup jobs were removed. For a
manual 30-day backfill, run:
```bash
php xcat siteAnalyticsJob 30
```