Birdseye

Karl

LR Birdseye is forum analytics with no JavaScript, no cookies and no outside tracker. Everything is recorded and counted on your own server, and the history stays in your own database.

What you get

Visitors, pageviews, bounce rate and average visit length, with a chart per day and a "today so far" strip that updates live.
Top pages, top discussions and top tags.
Where visitors come from (search engines, other sites), what they use (desktop, phone, tablet) and which countries they're in, with a world map.
Forum health, not just traffic: new members per day, discussions people read but nobody answers, and what people search for on your forum.
History by month and year, and a CSV download of every card.
A weekly email to admins every Monday comparing last week with the week before. One switch turns it off.
Share it without admin access. A View forum analytics permission lets any group you choose open the dashboard from their user menu. Nobody has it until you grant it.

Privacy

No IP address is ever stored and no cookie is ever set. Visitors are counted with a hash that changes every day, so nobody can be followed from one day to the next.
Raw events are kept for 72 hours at most, then rolled up into a few small rows per day. That's the permanent history, a few kilobytes a month.
There's no account, no license key and no outside service. The only thing it ever downloads is a free country lookup file, once a month, and that carries no visitor data. You can turn it off.

Countries work out of the box. Behind Cloudflare it reads the country Cloudflare already sends. Everywhere else it uses that monthly file, and you can point it at your own MaxMind-format file instead.

Because it counts on the server, bounce rate and visit length come out a little lower than with script-based trackers. That's the trade for shipping no JavaScript at all.

Requirements

Flarum 2.0 or later, PHP 8.3+
A working scheduler (the usual php flarum schedule:run cron entry), which builds the daily totals

Install

composer require linkrobins/birdseye

Then enable it under Admin, Extensions. It starts counting straight away, and the dashboard fills in as each day finishes.

Source: https://github.com/linkrobins/birdseye
Packagist: https://packagist.org/packages/linkrobins/birdseye

Every release is posted below.

The screenshots use demo traffic on a test forum.

Karl

v2.3.3 — Permission keys move from linkrobins-birdseye.* to lr-birdseye.*. A migration renames your existing grants in place, so there is nothing to do after updating: every group keeps exactly the permissions it had.

Why: fof/links reads a link id out of any granted permission whose name starts with "link" and contains "view". On MySQL and MariaDB the mismatch was silently ignored; on PostgreSQL it failed every page for forums running both extensions. The new prefix cannot collide.

Update

composer update linkrobins/birdseye

Release notes on GitHub: https://github.com/linkrobins/birdseye/releases/tag/v2.3.3
On Packagist: https://packagist.org/packages/linkrobins/birdseye

Karl

Birdseye 2.4.0

The world map and the Countries card now tell you when no visitor countries are being recorded, instead of drawing an empty map that looks exactly like a forum nobody has visited.

Birdseye reads a visitor's country from a trusted proxy header such as CF-IPCountry, or failing that from a local MaxMind country database. A forum with neither collects no country at all. That has been true for any forum not behind such a proxy since version 2.3.0 moved all processing onto your own server, and until now nothing on screen said so. Two admins reported the blank map as a bug, which was fair, because it was indistinguishable from one.

If you see the new notice, either set the country database file in the extension's settings, or point the trusted country header at whatever your proxy sends. Countries then appear from the next day processed onwards. Days that have already been summarised cannot be filled in afterwards, because the raw events behind them are deleted once their totals are written.

Nothing changes for a forum whose country lookup is already working, and a forum with too little recent traffic to judge is left alone rather than warned.

Thanks to Tutrix and SpikeNit for the reports.

After updating

Run php flarum cache:clear so your forum serves the rebuilt files instead of the copies it already has cached.

Update

composer update linkrobins/birdseye

Release notes on GitHub: https://github.com/linkrobins/birdseye/releases/tag/v2.4.0
On Packagist: https://packagist.org/packages/linkrobins/birdseye

Karl

LR Birdseye 2.4.1

When country lookup isn't working, the world map now tells you why, instead of always saying "not configured".

Until now the map said "not configured" whenever no visitor countries could be found, even when a country database file was set but couldn't be used. That sent admins looking for a setting they had already filled in.

If the country database file is set but can't be used, the map now names the problem and how to fix it:

The path isn't a full path. It needs to start with a slash, such as /home/you/geoip/GeoLite2-Country.mmdb.
The path points at a folder, not the file inside it.
There is no file at that path, or your host doesn't let PHP open files in that folder.
PHP can't read the file. Permissions of 644 usually work.
The file is still compressed. MaxMind's download is a .tar.gz archive; extract it and use the GeoLite2-Country.mmdb file inside.
The file isn't a MaxMind database.

It also tells you when the database is fine but "Country lookup via anonymized IP prefix" is turned off, which means the database is never used.

The help text for the country database setting now gives an example path, and recommends keeping the file outside your public web folder (such as public_html) so it can't be downloaded from your site. The extension's page has a new step-by-step guide to setting up visitor countries.

Thanks to Tutrix for the report and SpikeNit for the suggestion.

After updating

Run php flarum cache:clear so your forum serves the rebuilt files instead of the copies it already has cached.

Update

composer update linkrobins/birdseye

Release notes on GitHub: https://github.com/linkrobins/birdseye/releases/tag/v2.4.1
On Packagist: https://packagist.org/packages/linkrobins/birdseye

Karl

LR Birdseye 2.5.0

Visitor countries now work out of the box, with no database to download or set up yourself.

If you haven't set a country database file, Birdseye now downloads the free country database from DB-IP by itself and refreshes it once a month. Only the database file is downloaded: no visitor data leaves your server, and every country lookup still happens on your own forum.

Nothing to configure. The world map and Countries card fill in from the next day processed, as long as Flarum's scheduler is running (Birdseye already needs it for its stats). To fetch the database right away instead of waiting for the next hourly check, run php flarum birdseye:country-database.
Your own database still wins. If you've already set a MaxMind database file, Birdseye keeps using it and downloads nothing.
You can turn it off with the new "Download a country database automatically" setting.
If the download fails (some hosts block outgoing connections), the world map says so and shows the error, and Birdseye keeps whatever copy it already has. It tries again every few hours.
If it hasn't run yet, the map tells you to check that the scheduler is running.
The map shows a small "IP Geolocation by DB-IP" credit when DB-IP's database is in use, as its free licence requires.

After updating

Run php flarum cache:clear so your forum serves the rebuilt files instead of the copies it already has cached.

Update

composer update linkrobins/birdseye

Release notes on GitHub: https://github.com/linkrobins/birdseye/releases/tag/v2.5.0
On Packagist: https://packagist.org/packages/linkrobins/birdseye

SpikeNit

Dang! I wish I knew you were going to add the database auto monthly download. Earlier this week (with trial and error), I set up Cron jobs, using MaxMinds GeoIP update program, which checks and does this twice a week.

As always, I/we appreciate all you do my friend!

Karl

LR Birdseye 2.6.0

Birdseye now tells you when your statistics have stopped updating, and why.

Birdseye adds up each finished day in an hourly job on Flarum's scheduler. If that job never runs, today's numbers keep moving while every chart quietly stops at the last day it added, which looks like Birdseye losing your data.

A notice at the top of the dashboard says which day the statistics stop at. It shows on the admin page and in the forum's Analytics window.
If Flarum's scheduler isn't running, the notice says so and links to Flarum's guide to setting it up. This is the usual cause: the scheduler needs a cron job on your server.
If the scheduler is running but the statistics still stopped, the notice says that instead, so you know to look in storage/logs for an error.

Birdseye keeps raw visits for 3 days. Once the scheduler is set up, run php flarum birdseye:sync to catch up on the days it missed.

After updating

Run php flarum cache:clear so your forum serves the rebuilt files instead of the copies it already has cached.

Update

composer update linkrobins/birdseye

Release notes on GitHub: https://github.com/linkrobins/birdseye/releases/tag/v2.6.0
On Packagist: https://packagist.org/packages/linkrobins/birdseye

Karl

LR Birdseye 2.7.0

Your forum loads faster: the Analytics window is now only downloaded when someone opens it.

Improvements

Lighter forum pages. The Analytics window, opened from the user menu by members allowed to see statistics, used to be part of the code every forum page downloads, even for visitors who never see it. It now loads the moment someone opens Analytics, so every other page downloads about 6 KB less (compressed), which helps most on phones. The dashboard and the admin page work exactly as before.

After updating

Run php flarum cache:clear so your forum serves the rebuilt files instead of the copies it already has cached.

Update

composer update linkrobins/birdseye

Release notes on GitHub: https://github.com/linkrobins/birdseye/releases/tag/v2.7.0
On Packagist: https://packagist.org/packages/linkrobins/birdseye