Building a Custom Analytics Dashboard With Grafana and Matomo

If you already run Matomo for privacy-respecting web analytics, you know it ships with a capable reporting interface. So why add Grafana to the mix? The answer comes down to flexibility, correlation, and team workflows. In this tutorial you will connect Grafana directly to Matomo’s database and build a dashboard that goes far beyond what Matomo offers out of the box.

Why Combine Grafana With Matomo?

Matomo’s built-in dashboard is designed for a single data source: its own tracking data. Grafana, on the other hand, is a general-purpose visualization platform that can pull from dozens of backends simultaneously. By pointing Grafana at Matomo’s underlying MySQL or MariaDB database you unlock several advantages. First, you can place web analytics panels alongside server metrics, uptime checks, and application logs on a single screen. Second, Grafana’s alerting engine lets you fire notifications the moment traffic drops or error rates spike. Third, you gain fine-grained, read-only sharing so that stakeholders can view dashboards without needing a Matomo account.

Prerequisites

Before you begin, make sure you have the following components in place:

• A working Matomo installation (version 4 or later) with data already being collected. Self-hosted is required because you need direct database access.
• Grafana 10 or newer installed on the same network or with secure tunnel access to the database server. Docker, native packages, or Grafana Cloud all work.
• MySQL or MariaDB credentials with read-only privileges on the Matomo database. Never use the root account; create a dedicated user with SELECT-only grants.

Connecting Grafana to Matomo’s Database

Open Grafana and navigate to Connections > Data Sources > Add data source. Choose MySQL from the list. Fill in the host, port (default 3306), database name (commonly matomo), and the read-only user credentials you created. Enable TLS if the database is on a remote host. Click Save & Test to confirm the connection.

Once the data source is saved, Grafana can query every table Matomo uses. The most useful tables include matomo_log_visit for raw visit data, matomo_log_action for page URLs and action types, and the various matomo_archive_* tables for pre-aggregated reports.

Building Your First Panel: Real-Time Visitors

Create a new dashboard and add a panel. Select the MySQL data source you just configured. Switch the query editor to Code mode and enter the following SQL:

SELECT
  visit_last_action_time AS time,
  COUNT(*) AS visitors
FROM matomo_log_visit
WHERE visit_last_action_time >= NOW() - INTERVAL 30 MINUTE
GROUP BY UNIX_TIMESTAMP(visit_last_action_time) DIV 60
ORDER BY time;

Set the visualization type to Time series. You should immediately see a line chart showing visitors per minute for the last half hour. Adjust the interval and time range to suit your traffic volume. For low-traffic sites, expanding to the last two hours avoids an empty chart.

Essential Dashboard Panels

With the first panel working, expand the dashboard with these additional views.

Traffic Over Time

Query matomo_log_visit grouped by day to display a bar chart of daily sessions. Use Grafana’s $__timeFilter macro so the panel respects the dashboard’s global time picker. This gives you a quick overview of trends without opening Matomo at all.

Top Pages

Join matomo_log_link_visit_action with matomo_log_action on the idaction_url field, then group by the name column. Display the result as a table sorted by hit count descending. Limit the result to the top 20 rows so the panel stays readable.

Referrers

The referer_name column in matomo_log_visit stores the referring domain. A pie chart grouped by this column instantly shows where your traffic originates. Filter out empty referrers to focus on external sources.

Device Breakdown

Matomo stores device type information in config_device_type. Map the integer values (0 = desktop, 1 = smartphone, 2 = tablet) to human-readable labels using a CASE statement in your SQL. A donut chart works well here for a quick proportional view.

Advanced: Combining Matomo Data With Other Sources

The real power of Grafana emerges when you layer multiple data sources. Add a Prometheus or InfluxDB data source that stores your server metrics and place CPU, memory, and response time panels next to the Matomo traffic charts. You can also ingest Nginx or Apache access logs via Loki and correlate specific HTTP 500 errors with traffic spikes. This cross-source view makes root-cause analysis dramatically faster because you do not need to switch between tools.

Another valuable combination is uptime monitoring. If you use a tool like Uptime Kuma or Grafana’s own synthetic monitoring, overlay downtime events on the traffic time series. When a dip in visitors aligns with a downtime window, you know the cause immediately.

Setting Up Alerts

Traffic Drop Alert

In Grafana, open Alerting > Alert rules > New alert rule. Use a query that counts visits in the last hour and compare it against the same hour one week ago. If the current count falls below 50 percent of the historical baseline, trigger a warning. Route the notification to Slack, email, or PagerDuty through a contact point.

Error Spike Alert

If you are ingesting server logs, create an alert rule that counts HTTP 5xx responses over a five-minute window. Set a threshold appropriate for your baseline. Pair this with the traffic panel so you can see at a glance whether errors correlate with increased load or an application bug.

Sharing Dashboards With Team Members

Grafana offers several ways to share dashboards without exposing edit access. The simplest method is to create an organization-level Viewer role and invite team members with that role. They can see every dashboard but cannot modify queries or panels. For external stakeholders, use public dashboards (available in Grafana 10+), which generate a unique URL that requires no login. You can also export snapshots that freeze the data at a point in time, which is useful for monthly reports.

Performance Tips and Caching

Querying raw Matomo tables can be expensive on high-traffic sites. Follow these guidelines to keep dashboards responsive:

• Use archive tables when possible. Matomo pre-aggregates data during its archiving cron job. Querying matomo_archive_numeric_* and matomo_archive_blob_* is far cheaper than scanning matomo_log_visit.
• Set appropriate time ranges. Default dashboards to the last 7 or 30 days instead of “All time” to limit the rows scanned.
• Enable query caching. In each panel’s query options set a minimum refresh interval of 60 seconds or more. Grafana will serve cached results between intervals.
• Add database indexes. If you notice slow queries on matomo_log_visit, ensure indexes exist on visit_last_action_time and idsite.
• Consider a read replica. For very high-traffic Matomo instances, point Grafana at a MySQL read replica to avoid any impact on Matomo’s tracking write path.

Conclusion

Grafana and Matomo complement each other well. Matomo handles privacy-respecting data collection and provides a solid default reporting UI, while Grafana adds limitless visualization, multi-source correlation, and robust alerting. By connecting Grafana to Matomo’s MySQL database you get the best of both tools without duplicating data or adding complex ETL pipelines. Start with the real-time visitors panel, expand to the essential panels described above, and then layer in server metrics and alerts. Within an afternoon you will have an analytics command center that serves your entire team.