=== Server Log Stats & AWStats ===
Tags: analytics, activity log, server logs, statistics, dashboard
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 2026.10.05.002
License: GPL-3.0-or-later
License URI: https://www.gnu.org/licenses/gpl-3.0.html

Private WordPress activity, account last seen, and server-log charts with IP sessions, bot reports, country flags, and read-only JSON.

== Description ==

Server Log Stats & AWStats brings WordPress activity and server-log reporting into a private administrator dashboard. Native activity starts after activation. Server reports require a separate hosting-administrator setup; activation alone cannot grant log access.

All included features are free. No license server, paid account, trial, or external analytics account is required.

* Record supported WordPress changes, logins, authenticated REST requests, and account last seen. Sources distinguish browser, API, CLI, system, and imported legacy events.
* Filter activity by account, date, and source. Sort table columns and preserve sorting through session/work-event pagination.
* After host setup, view AWStats traffic charts, hourly requests, observed IP sessions, server health, and selected-site file usage.
* Open Bots for monthly AWStats classifications and filtered retained request reports based on user-agent claims.
* One shared filter bar selects the retained UTC month, date, observed IP, country and public or admin/API routes across Traffic, Bots, Countries, sessions and recorded WordPress activity. Country flags and IP drilldowns preserve the selection. Missing logs and bounded exports remain visible.
* Use optional local IP geolocation. Country totals are independent of the smaller per-IP index. No external IP lookup is made.
* Read private JSON through authenticated REST endpoints and the included Python client, without a browser login cookie.

The bundled AWStats engine runs from the host command line. Its traditional public CGI interface is not enabled. Charts and tables appear in WordPress administration.

= Understand the evidence =

Reports describe successfully scanned retained logs. The dashboard displays limits, missing coverage, stale reports, and omitted rows. Monthly history may cover only part of a month.

IPs may represent proxies, shared connections, or VPN exits. Locations are approximate database matches. User agents can be spoofed; bot names do not verify identity. Sessions group the same observed IP and sanitized user agent until a 30-minute idle gap. Duration is a logged request span, not a person's working time. Native activity separately records supported operations and the authenticated account, when available.

= Server requirements =

Native WordPress activity needs no Python collector or root access. Server reports require a hosting administrator, dedicated site logs in compatible Apache/Nginx combined format, a dedicated site reader identity, Linux with systemd and /proc, POSIX ACL support, Python 3.10 or later, and Perl with JSON::XS and Try::Tiny.

Shared hosting may need provider help. Discovery refuses ambiguous mappings, shared fleet logs, and shared web-server identities.

== Installation ==

1. Back up your database/files. If the older private Server Log Stats plugin is installed, deactivate it first; never activate two copies. Install and activate the verified package through Plugins in WordPress administration.
2. Open Server stats. Native activity begins with this coverage period. Server reports display an unavailable-collector message until host setup.
3. Have your administrator copy the verified release into a private, root-owned location outside WordPress. Never run privileged code from a web-writable directory.
4. Run deploy/discover.py for the WordPress home hostname. Review its root, dedicated logs, and PHP-FPM identity. Install only a ready result with no issues.
5. Run deploy/install.py with the reviewed discovery file or all manually verified settings. The installer verifies the manifest, dependencies, ownership, and paths before changing site files.
6. Start/enable only that site's collector service/timer. Verify collection, dashboard results, recurring refresh, and rejection of unauthenticated requests.

The collector refreshes every five minutes. Default limits are 128 MiB, 250,000 lines, and 12 months. Reports older than 15 minutes are stale. A failed refresh preserves the last successful report with failure/freshness metadata. Original access logs are never changed or purged.

Configure Apache or Nginx to deny web access to collector, deploy, scripts, and awstats. The bundled engine retains its upstream source bytes under awstats.txt and runs through Perl on the host; the text suffix prevents a .pl CGI handler from executing it inside WordPress. Do not enable AWStats as CGI.

== Frequently Asked Questions ==

= Will every feature work immediately after activation? =

Native activity/last seen start after activation. Server charts, IP sessions, Bots, Countries, and host health require the host collector and verified site-specific logs. Geolocation also needs a local database.

= Does this install AWStats? =

The package includes the checksum-pinned AWStats Perl engine and upstream license. No AWStats purchase is required. A host administrator installs the collector and operating-system dependencies. The plugin does not grant itself root privileges.

= Can this recover work performed before installation? =

It can analyze retained older logs within scan limits and import supported legacy activity. It cannot recreate uncollected logs or prove an edit from a URL request. Imports preserve source labels and report omissions. Review imports before deactivating a previous plugin; original tables/metadata are preserved.

= How do I enable flags and approximate IP locations? =

A host administrator may download DB-IP City Lite MMDB from [DB-IP](https://db-ip.com/db/download/ip-to-city-lite), verify its checksums, and install it outside WordPress as an immutable root-owned file. Supply its path and SHA-256 to the installer. The database is not bundled or downloaded automatically. New releases need a separately verified file/hash.

The maxminddb reader uses Apache-2.0. DB-IP City Lite uses [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); displays include [IP Geolocation by DB-IP](https://db-ip.com) attribution. Missing/invalid data leaves locations unavailable. Flags depend on device emoji support.

= Can an AI agent read the data without signing into WordPress? =

Yes, after an administrator configures a private token. Endpoints are /wp-json/server-log-stats/v1/report and /wp-json/server-log-stats/v1/activity. Activity works without a collector; the combined report needs a server snapshot.

Send X-CS-Stats-Token or Authorization: Bearer over HTTPS. Administrator WordPress Application Passwords also work. Only a SHA-256 digest is stored in cs_server_stats_token_hash. Provision it with private administrator tooling; the dashboard displays no token. Replace the digest/private credential to rotate access, or delete the option to revoke it. Report tokens grant read access, not editing privileges. Keep tokens out of URLs, public logs, and source control.

= Are the reports public or indexed by search engines? =

Reports require an administrator identity or valid read-only token. Responses use private/no-store and noindex/nofollow/noarchive headers. The WordPress robots filter adds exclusions, preserving existing rules. Physical robots.txt files and caching proxies may need host configuration. Robot rules supplement authentication.

= Does storage show the entire server's disk capacity? =

No. Storage measures site-file bytes, excluding database, mail, and other sites. An allowance appears only when a host administrator attests one for the same scope; otherwise it stays unknown. The plugin reports quotas without enforcing them. Load, memory, and uptime describe the host.

= What happens when I deactivate or delete the plugin? =

Deactivation stops native recording and clears its scheduled cleanup; retained audit data remains. Deleting the plugin through WordPress removes its own current-site audit table, options, last-seen metadata and cleanup hook. Other plugin tables, original server logs, host collector files and independent host timers are preserved. On multisite, cleanup applies to the current blog only; other blogs require their own scoped cleanup. If another locally or network-active copy still uses the audit data, deleting a disabled duplicate preserves that shared data. When retiring a site, stop its timer/service and revoke its token. Preserve releases used by other sites and newer site content.

== Privacy ==

Recorded data includes account identifiers, operations, timestamps, observed IPs, sanitized user agents/routes, HTTP methods/statuses, and application-password UUIDs where available. Summaries and identifiers are recorded, rather than post bodies, passwords, or option values. Server query strings/referrers are discarded; credential-like path segments are redacted.

Native activity/last seen uses a 90-day window. Daily scheduled cleanup removes older plugin-owned data, preserving unrelated user metadata. Server reports follow host retention and scan/export limits; original logs are not purged. Reports can contain personal information. Restrict access, apply appropriate privacy/retention policies, and keep exports/credentials private.

WordPress's personal-data export includes retained activity for a current account matched by email. Erasure removes expired records for that account and reports security records retained within the 90-day window. Server visitor IPs cannot reliably be matched to an email. Suggested privacy-policy text is available in WordPress.

No public-page tracking script is inserted. Activity/IPs are not sent to the author or a geolocation API. DB-IP is a manual administrator download; IP lookups stay local. Agents receive reports only through authenticated requests.

== Changelog ==

= 2026.10.05.002 =
* Country clouds and observed IP details follow the selected retained month.
* Shared month, date, IP, country and public/admin/API route filters apply across report tabs.
* Filtered traffic and bot charts use retained server requests; recorded WordPress account actions retain their attribution.

= 2026.10.05.001 =
* Standardized developer attribution, calendar revision and maintenance documentation. Source checkpoint only.


= 2026.10.4.11 =
* Click country flags for a sortable IP list and country-filtered request sessions.
* Separate bounded country membership from the small display location cache; keep coverage visible.

= 2026.10.4.10 =
* Initial public package of the free administrator dashboard and native activity log.
* Bundled AWStats CLI collector, verified per-site discovery, private JSON, and read-only agent client.
* Traffic charts, sortable tables, observed IP sessions, bot reports, and country flag cloud.
* Optional local IP geolocation with visible coverage and unknown-location counts.

== Upgrade Notice ==

= 2026.10.05.002 =
Update the host collector with the plugin for monthly shared filtering. Older snapshots report unavailable monthly data rather than substituting one day.

= 2026.10.4.11 =
Native activity starts after activation. Server-log reports require separate hosting-administrator setup; optional geolocation needs a verified local database.
