Matomo Analytics: Privacy Is a Configuration, Not a Feature

Most people install Matomo for one reason: they want web analytics without handing their visitors to Google. That reason is good, and it is also where the thinking usually stops. The tracking code goes on the site, the dashboard fills up, and a year later nobody has enabled the one setting that would have made the installation lawful in the first place, nobody has set up the cron job that keeps the reports from crawling, and the raw data everyone was so keen to own is quietly being deleted at ninety days by a default nobody read.

2. Where the Name Comes From

The product has had two names, and both stories are short and worth knowing, because the second one explains the project's whole position.

It began as Piwik. Its founder, Matthieu Aubry, wanted a name that was unique, easy to remember, easy to pronounce, with as few letters as possible, and with a free domain. He was inspired by the word "kiwi" and made up "Piwik" from it. The name means nothing at all. That was the point: it was available.

On 9 January 2018, after roughly ten years and more than a million websites, Piwik became Matomo. The project's own explanation for the change was that it wanted a name nobody else was using, to remove any possible confusion or affiliation, and one that suited what it had become rather than what it was in 2007.

The chosen word is Japanese. Matomo's announcement puts it plainly: "Matomo means decent in Japanese. Which aligns with one of our key values - transparency."

Piwik    2007    invented from "kiwi", no meaning, domain was free
Matomo   2018    Japanese for "decent"; chosen for what it says

That is the difference between the two names in one line. The first was picked because it was available. The second was picked because it was an argument. A product that competes on privacy chose a word meaning "decent" and then spent the following years being measured against it, which is a harder promise to keep than a made-up name ever asks for.

The old name has not entirely gone. You will still meet piwik in the wild: in the _pk_ prefix on every cookie the tracker sets, in the _paq JavaScript queue variable, in old documentation URLs, and in older integrations that still post to piwik.php. Matomo kept those aliases working deliberately, because renaming them would have broken a million installations at once.

4. Simple Use Cases

4.1 The Simplest Useful Question: Is Anything Arriving?

Before any report means anything, confirm that tracking requests reach the server at all. Matomo has a report for exactly this, and it is the first place to look when a dashboard is empty: Visitors → Visits Log. It shows individual visits as they arrive, within seconds.

If the Visits Log is empty while you are browsing your own site in another tab, the problem is never the reports. It is one of four things, in this order of likelihood:

1. the tracking code is not on the page       → view source, search for "_paq"
2. the tracker URL is wrong or blocked        → browser devtools, Network tab,
                                                 look for matomo.php and its status
3. you are excluding yourself                 → Administration > Websites > Settings,
                                                 excluded IPs; or an opt-out cookie
4. a content blocker is stopping the request  → test in a clean browser profile

Point 3 catches experienced people constantly. You set an IP exclusion months ago, your address changed, and now you are excluding someone else while merrily tracking yourself.

4.2 The Tracking Code

Matomo's JavaScript tracker is a small asynchronous snippet. It queues instructions in an array called _paq and then loads matomo.js, so the browser never waits for it before rendering the page.

<script>
  var _paq = window._paq = window._paq || [];
  _paq.push(['trackPageView']);
  _paq.push(['enableLinkTracking']);
  (function() {
    var u = "https://analytics.example.com/";
    _paq.push(['setTrackerUrl', u + 'matomo.php']);
    _paq.push(['setSiteId', '1']);
    var d = document, g = d.createElement('script'),
        s = d.getElementsByTagName('script')[0];
    g.async = true; g.src = u + 'matomo.js';
    s.parentNode.insertBefore(g, s);
  })();
</script>

Two lines do the actual work. trackPageView records the pageview. enableLinkTracking turns on automatic tracking of downloads and outbound links, which is why Matomo can report those without you tagging anything.

The queue design is worth understanding, because it explains a whole class of "my custom tracking does not work" problems. _paq is a plain array that exists before matomo.js loads. Anything you push into it is replayed in order once the tracker is ready. So order matters: configuration calls such as setUserId or setCustomDimension must be pushed before trackPageView, or they will not be attached to that pageview.

_paq.push(['setCustomDimension', 1, 'member']);   // correct: set first
_paq.push(['trackPageView']);

_paq.push(['trackPageView']);
_paq.push(['setCustomDimension', 1, 'member']);   // wrong: pageview already sent

4.3 The Visits Log, and Why It Does Not Exist Elsewhere

Most analytics tools show you aggregates: 1,240 visits, 3.2 pages each. Matomo shows you those too, and it also lets you open a single visit and read it action by action, with timestamps, referrer, device, and the exact path the person took through the site.

Two reports do this. Visits Log lists visits one by one. Visitor Profile takes one visitor identifier and shows every visit that identifier has ever made.

This is genuinely useful. When a form stops converting, an aggregate tells you conversions fell; the Visits Log shows you eleven people reaching step three and leaving, which turns a statistic into a bug report.

It is also the feature with the largest privacy cost in the product, and the two facts are the same fact. A per-visitor history is exactly what makes the data useful for diagnosis, and exactly what makes it personal data. This is why the CNIL exemption in section 7.4 requires you to switch both reports off. They are the first thing a regulator looks at and the first thing you will miss.

4.4 What Counts as a Visit

Every number in the dashboard rests on a definition, and this is the one to know. By default, Matomo starts a new visit when a visitor performs an action more than 30 minutes after their last tracked interaction.

The setting lives in the tracker configuration, in seconds:

[Tracker]
visit_standard_length = 1800     ; 30 minutes, the default

Change it and every derived metric changes with it. A longer window produces fewer visits, a lower bounce rate, and longer average visit durations. Nothing about your visitors changed. You can defend a longer window for a documentation site people read slowly, but you can no longer compare your numbers to anyone else's, or to your own from before the change.

4.5 Goals

An analytics tool that only counts pageviews tells you about traffic, not about outcomes. A goal is a definition of something worth happening: a form submitted, a file downloaded, a thank-you page reached, a click on a mail link.

You define goals under Goals > Manage Goals, and each one can be triggered by a URL pattern, a page title, an event, or an explicit call in your own code:

_paq.push(['trackGoal', 3]);              // goal 3 converted
_paq.push(['trackGoal', 3, 49.95]);       // ... with a revenue value

Once a goal exists, every other report gains a column. You stop asking which channel sends the most visitors and start asking which one sends visitors who do the thing. Those are usually different answers, and only the second one is worth acting on.

One warning for later: goals are the point where analytics stops being audience measurement and starts being something a regulator treats differently. Section 7.4 returns to it.

4.6 Beyond Pageviews: Events, Site Search, and Custom Dimensions

A pageview is recorded when a page loads. Modern sites are full of things that matter and load no page: an accordion opening, an AJAX form submitting, a video playing, a call-to-action being clicked. Matomo records those as events.

_paq.push(['trackEvent', 'Contact', 'Submit', 'Quote form']);
                          category  action    name (optional)

_paq.push(['trackEvent', 'Video', 'Play', 'Intro', 42]);
                                                    value (optional)

Site searches get their own call, because a search is worth more than a pageview: it is a visitor telling you in their own words what they could not find.

_paq.push(['trackSiteSearch', 'opening hours', 'Support', 0]);
                              keyword          category   results
                              (required)       (optional) (optional)

A result count of 0 is the most valuable number in analytics. It is a list of things people asked your site for and did not get.

Custom dimensions attach your own field to a hit, and they come in two scopes that behave differently:

• Visit scope describes the whole session: logged in or not, plan type, customer segment. Set it once and it applies to the visit.
• Action scope describes one pageview or event: article author, product category, form step. Action-scope dimensions can also be extracted automatically from the page URL, the page title, or a URL query parameter, so you often do not need to set them in code at all.

_paq.push(['setCustomDimension', 1, 'member']);   // before trackPageView

# an installation ships with 5 slots per scope; add more from the CLI
$ ./console customdimensions:add-custom-dimension --scope=visit --count=10

Now the part that matters more than any of the syntax. Do not track something because you can. Every event you invent is a name you have to keep meaning the same thing for years, across redesigns and across whoever maintains the site after you.

The practical version of that rule is to name events after what happened in the business, not after what was clicked:

fragile   trackEvent('Buttons', 'Click', '.green-button')
          → a redesign renames the class and the report dies silently

durable   trackEvent('Contact', 'Submit', 'Quote form')
          → survives any redesign, because it describes the outcome

The second one keeps working when the button turns blue, moves to another page, or becomes a link. The first one keeps reporting until somebody changes a stylesheet, and then reports nothing while looking exactly as healthy as before. Analytics that breaks loudly is a nuisance; analytics that breaks silently costs you a year of comparisons.

4.7 Single-Page Applications

The standard tracking code records one pageview when the document loads. A single-page application then changes the URL and the entire contents of the screen without ever loading another document, so Matomo hears nothing more. Everything after the first screen is invisible.

The fix is to tell the tracker that a virtual pageview happened, and the order of the calls is the whole trick:

// on every route change in your application
_paq.push(['setCustomUrl', window.location.href]);
_paq.push(['setDocumentTitle', document.title]);
_paq.push(['trackPageView']);

The two set calls must come first. trackPageView reports whatever the tracker currently believes the URL and title to be, so setting them afterwards labels the next pageview instead of this one. This is section 4.2's queue rule again, and single-page applications are where it does the most damage: every pageview is attributed to the previous screen, the reports look populated, and the numbers are quietly wrong rather than obviously missing.

Matomo's fuller example also carries the referrer and clears page-scoped custom variables, which matters when one screen's context must not leak into the next:

_paq.push(['setReferrerUrl', previousUrl]);
_paq.push(['setCustomUrl', currentUrl]);
_paq.push(['setDocumentTitle', 'My New Title']);
_paq.push(['deleteCustomVariables', 'page']);
_paq.push(['trackPageView']);

Two traps specific to this pattern. Double counting: frameworks that fire a route event on the initial load will track the first screen twice, once from the standard snippet and once from your handler, so skip the first route event. And timing: if you track before the framework has updated document.title, every virtual pageview carries the previous screen's title. Track after the render, not during the transition.

If you would rather not maintain this in application code, Matomo Tag Manager can drive it from history-change triggers instead, which is section 5.3.

6. Advanced Use Cases

6.1 Archiving: The One Thing That Decides Whether Matomo Is Fast

If you run Matomo On-Premise and read only one section of this article, read this one. More self-hosted Matomo installations are ruined by this than by every other cause combined.

Reports come from the archive tables, and something has to build them. Out of the box, that something is the browser: when you open a report Matomo has not archived yet, it archives it there and then, while you wait.

On a small site this is invisible. On a busy site it is a spiral. The report takes twenty seconds, the user reloads, that starts a second archiving run, the database slows further, and every additional click makes it worse.

The fix is to move archiving to a scheduled job and forbid the browser from doing it:

# crontab, running as the same user as your web server
5 * * * * www-data /usr/bin/php /path/to/matomo/console core:archive \
          --url=https://analytics.example.com/ > /var/log/matomo-archive.log

That console is worth knowing beyond this one command. It is Matomo's command-line interface, built on Symfony Console, and it handles archiving, cache clearing, diagnostics, plugin activation, scheduled tasks, updates and database maintenance. Plugins can add their own commands to it, and core:archive is treated as a stable public interface whose name and parameters do not change between versions, which is what makes it safe to put in a crontab and forget.

Then, in Administration > System > General settings:

Archive reports when viewed from the browser  : No
Archive reports at most every X seconds       : 3600

And in config/config.ini.php, the setting that closes the remaining gap:

[General]
browser_archiving_disabled_enforce = 1

That last line matters more than it looks. Turning off browser archiving in the interface still lets segments be archived in real time on demand, and segments are the most expensive archiving there is. This setting stops that too.

It also has a consequence you must know before you set it, because otherwise you will file a bug against yourself: with enforcement on, any segment configured to process in real time will never show data outside the live reports. Matomo therefore creates new segments as pre-processed when the setting is enabled. Existing segments created before you turned it on are the ones to check, and they are the usual cause of "my segment reports went empty after I fixed the performance problem".

A self-hosted Matomo that feels slow is almost never short of CPU. It is being asked to calculate reports at the moment somebody looks at them, which is the one moment it should be doing nothing but reading.

6.2 The Reporting API

Every report you can see is also an API call, and the API is not an add-on: the interface is built on it. That means anything on screen can be fetched, scheduled, or joined to other data.

Requests go to your Matomo root with module=API:

$ curl -s "https://analytics.example.com/index.php" \
    -d "module=API" \
    -d "method=VisitsSummary.get" \
    -d "idSite=1" \
    -d "period=month" \
    -d "date=2026-08-01" \
    -d "format=json" \
    -d "token_auth=YOUR_TOKEN"

{"nb_uniq_visitors":4821,"nb_visits":6390,"nb_actions":18244,
 "nb_visits_converted":143,"bounce_count":2871,"sum_visit_length":902144,
 "max_actions":57,"bounce_rate":"45%","nb_actions_per_visit":2.9,
 "avg_time_on_site":141}

Send the token in the POST body, as above, not in the query string. A token in a URL ends up in your access logs, in proxy logs, and in browser history, and a Matomo token is not a read-only key by default.

The standard parameters:

That default of 100 rows is the most common cause of a wrong number in a Matomo-based dashboard. Somebody fetches page URLs, sums the visits column, compares it to the total on the dashboard, and finds it short. The API answered exactly what was asked: the top hundred rows. Set filter_limit deliberately in every script you write.

One more habit worth having: method=API.getReportMetadata returns the list of every report available on your installation, including the ones added by plugins. It saves guessing at method names.

6.3 The Tracking HTTP API

JavaScript is one way to send data to Matomo, not the only one. Underneath, tracking is a plain HTTP request to matomo.php, and anything that can make an HTTP request can track.

https://analytics.example.com/matomo.php
    ?idsite=1          # required: which site
    &rec=1             # required: literally "record this"
    &url=https://example.com/order/complete
    &action_name=Order%20complete
    &_id=af344a398df83874     # visitor id, 16 hex chars
    &send_image=0      # reply 204 instead of a 1x1 GIF

By default the endpoint answers with a 1x1 transparent GIF, which is what makes image-only tracking possible in a plain HTML email or a page with no JavaScript. Adding send_image=0 returns an HTTP 204 instead, which is faster and is what you want from server-side code.

The same endpoint accepts bulk tracking: one POST carrying many hits as a JSON body, which is what you want when a backend job has a thousand actions to record and you do not want a thousand HTTP requests.

$ curl -i -X POST --data '{
    "requests": [
      "?idsite=1&rec=1&url=https://example.com/a&action_name=Page A",
      "?idsite=1&rec=1&url=https://example.com/b&action_name=Page B"
    ],
    "token_auth": "YOUR_TOKEN"
  }' https://analytics.example.com/matomo.php

Each array entry is exactly the query string you would otherwise have sent on its own, and every value inside it must be URL-encoded. The token_auth is needed for the cases that require authentication, such as setting a custom timestamp on historical data.

Server-side tracking is the honest answer to blocked scripts. It also moves a responsibility onto you: the browser is no longer supplying the address, the user agent, or the referrer, so your code must send them, and consent must be checked before your code decides to track rather than in the browser after the fact.

6.4 Log Analytics: Analytics Without a Tracker

This is Matomo's most underused capability. It can build its reports from your web server's access logs instead of from JavaScript, using an importer script shipped with it.

$ python3 /path/to/matomo/misc/log-analytics/import_logs.py \
      --url=https://analytics.example.com \
      --idsite=1 \
      --recorders=4 \
      --enable-static \
      --enable-bots \
      --enable-http-errors \
      --enable-http-redirects \
      /var/log/apache2/access.log

The importer recognises the default formats of Apache, Nginx, IIS and Tomcat, plus NCSA Common, Extended and W3C Extended logs, Nginx JSON, and the log formats of several cloud services including AWS CloudFront, S3 and ELB. Formats it cannot detect, such as OVH, are selected explicitly with --log-format-name.

Four things follow from tracking this way, and each one is a real trade:

• No script, no cookie, nothing on the page. Ad blockers and JavaScript-disabled browsers become invisible as a category, because there is nothing for them to block.
• Bots become visible. With --enable-bots you see crawler traffic that JavaScript tracking never sees, because crawlers do not run your tracker.
• It works backwards in time. Logs you already have can be imported today. This is the only way to get analytics for a period before you installed the tool.
• Less detail per visit. A log line has no screen size, no viewport, no click events, and no page timings, because the server never learned them.

The two methods are not exclusive. Running the tracker for behaviour and importing logs for crawler traffic and for the pre-installation past is a perfectly reasonable setup, as long as you keep them in separate site IDs so the visit counts do not double.

6.5 The Database

Because the data is yours, SQL is available, and some questions are far easier there than through any report. The tables carry your configured prefix, matomo_ by default.

The log_action design is worth a moment, because it explains why Matomo's tables are smaller than you expect. URLs and titles are not repeated on every row. Each distinct string is stored once in log_action and referenced by an integer everywhere else. A million pageviews of the same page store that URL once.

Two rules for querying directly. Read, never write. Matomo has no idea you changed anything, and the archives will not agree with the logs afterwards. And be careful with counting on log tables: an unindexed COUNT(*) across log_link_visit_action on a busy site will happily block the tracker that is trying to insert into it.

The disciplined way to make a hand-written report available in the interface is a custom plugin that adds an API method and its own archiver, so the result is cached like every other report rather than recalculated on every page load.

6.6 Many Client Sites: One Installation or Several?

If you report to clients, this is the architecture decision you make once and live with. Matomo tracks an unlimited number of sites per On-Premise installation, and up to 30 per Matomo Cloud instance, so the technical ceiling is rarely what decides it.

Start with where the load actually falls, because the intuition is wrong. Site count barely affects tracking and dominates archiving.

That table answers your two performance questions. Registering many sites costs you almost nothing at tracking time. Opening one client's dashboard is fast no matter how many clients you have, because archives are per site. The page that degrades is the cross-site overview, and it degrades in proportion to how many sites you added.

When the archiving run stops finishing between crons, split it rather than buying a bigger server:

core:archive --max-websites-to-process=5
core:archive --max-archives-to-process=100

Whatever is not processed in one run is picked up by the next, so several small runs replace one long one and peak memory drops accordingly.

Now the real question, which is not really about performance:

Two rows there deserve more weight than the maintenance argument that usually wins these decisions.

The privacy settings are installation-wide. IP anonymisation, retention, and the compliance configuration in section 7.4 apply to the whole installation, not per site. One client who needs 180-day retention imposes it on every other client, and one client who wants two years prevents you giving anyone else a shorter policy. If your clients have genuinely different obligations, that single fact can decide the question on its own.

One database holds every client's visitor data. That is a concentration of personal data you are now the controller of, and a breach is not one client's incident, it is all of them simultaneously. It is also why the per-client login you set up so carefully is not isolation: Matomo's user permissions control the interface, not the database underneath.

For most agencies, one installation with per-site user permissions is the right answer, and the maintenance saving is real. Split a client out when they are large enough to distort archiving for everyone else, or when their contract or regulator asks for something the shared installation cannot give them. Those are the two conditions worth watching for; everything else is a preference.

6.7 Serving Matomo Under Each Client's Own Domain

A single Matomo can answer to several hostnames, so stats.example.com and stats.petermartin.nl both reach the same instance. Each client's page then loads its tracker from a subdomain of its own site. This is a good idea, and it is worth being precise about which of its benefits are real.

On-Premise, point a DNS CNAME (or an A record) at the server, serve a certificate covering the name, and then add the hostname to Matomo's configuration, which is the step people forget:

[General]
trusted_hosts[] = "stats.example.com"
trusted_hosts[] = "stats.petermartin.nl"

Matomo rejects requests arriving on a hostname it does not know, so without this the new domain returns an error rather than tracking. On Matomo Cloud the equivalent is a custom domain, which requires an Enterprise plan: you create the CNAME to your *.matomo.cloud address and Matomo Support completes the setup with a Let's Encrypt certificate. If your plan is not Enterprise, this option does not exist, which is worth knowing before you promise it to a client.

What you actually gain:

• The request is same-site. A call from example.com to stats.example.com is first-party. Browser policies that restrict cross-site requests do not apply to it, and that distinction is getting stronger with every browser release, not weaker.
• It is not on a blocklist. Blockers ship lists of known analytics hostnames. A subdomain of the client's own site is not on any list, so requests that would have been dropped now arrive, and the reports get closer to reality.
• It looks like the client's own infrastructure, because it is. For a client who dislikes third-party services in their page source, this is a legitimate and accurate answer.

What you do not gain, and should not claim:

• It does not make the cookies first-party. They already were. Matomo's cookies are written by JavaScript through document.cookie on the tracked page itself, so they belong to the tracked domain no matter which host the tracker is loaded from. This is the benefit most often claimed for the setup and it is not one.
• It does not permanently defeat blockers. A custom hostname beats hostname matching. It does not beat a rule that matches the path /matomo.php, the filename matomo.js, or the shape of the request. Renaming those buys a little more, and now you are maintaining a disguise rather than an analytics setup.
• It does not change your obligations. The same data reaches the same database. Making the collection less visible in the page source does not make it less collection, and it never affects what a privacy policy has to say.

The PHP tracker proxy is a heavier variant of the same idea: files placed on the client's own server (matomo.php, piwik.php, proxy.php and matomo-proxy.php) that receive the hit and forward it to your Matomo server-side. It works where DNS is not yours to change, and it costs more than it looks: the client's web server must be able to make outbound HTTPS requests to your instance, every tracked hit now consumes PHP on their server, and you maintain a set of proxy files on every site you manage. Matomo says plainly that it "may not be suitable if your hosting environment restricts outbound HTTPS requests". Prefer the DNS approach; keep the proxy for the cases that force it.

Serving the tracker from the client's own domain is defensible because it makes measurement more accurate, not because it makes measurement harder to notice. Those two motives produce the same DNS record and very different follow-up decisions, and it is worth knowing which one you are acting on.

8. Best Practices

• Set up the archiving cron before you need it. Add the cron job, set browser archiving to No, and set browser_archiving_disabled_enforce = 1. This is the single highest-value action on a self-hosted Matomo, and it is much easier to do on a quiet site than on a struggling one.
• Configure retention on day one. Delete old raw data, keep aggregated reports. Three to six months of raw data is Matomo's own recommendation.
• Decide about yearly unique visitors before you set retention, not after. The two settings contradict each other, and only one order lets you have both.
• Turn on IP anonymisation immediately. It masks before writing, so it protects nothing retroactively. Every day it is off produces rows you cannot fix later.
• Run the Compliance assessment and read the results, even outside France. Treat it as the most concrete available specification of what consent-free analytics costs, then decide deliberately which items you are not going to accept.
• Name events after outcomes, not after elements. trackEvent('Contact', 'Submit', 'Quote form') survives a redesign; an event named after a CSS class dies silently the day somebody edits a stylesheet.
• Keep personal data out of URLs and page titles before you configure anything else. IP anonymisation does nothing about a customer's name in a path, and the automatic pattern-matching cannot recognise one.
• In a single-page application, set the URL and title before trackPageView, and skip the framework's initial route event. Getting this wrong produces populated reports with every pageview attributed to the previous screen.
• Use the self-contained opt-out code, not the tracker-based form. The tracker-based one loads from your Matomo host, so a content blocker hides the privacy control from precisely the visitor who came looking for it.
• Decide one installation or several on the privacy settings, not the maintenance effort. Anonymisation and retention are installation-wide, so clients with different obligations cannot share one instance however convenient that would be.
• Add every hostname to trusted_hosts[] before pointing a client's subdomain at your Matomo. Matomo rejects hostnames it does not know, and the failure looks like broken tracking rather than a configuration error.
• Budget premium plugins as subscriptions. The free core is genuinely complete analytics; heatmaps, funnels, A/B testing and SAML are not in it, and their annual price is a business number.
• Never put a token in a URL. Send token_auth in the POST body. Tokens in query strings end up in access logs and browser history.
• Set filter_limit in every API call. The default of 100 rows will silently give you a wrong total the first time you sum a column.
• Use Preview / Debug before publishing a tag manager version, and remember you can roll back a container version when a release breaks tracking.
• Push configuration calls before trackPageView, not after. Order in the _paq queue is the cause of most custom tracking that "does not work".
• Keep log import and JavaScript tracking in separate site IDs so the same visit is never counted twice.
• Query the database read-only. Writing to log tables desynchronises them from the archives, and heavy counts on log_link_visit_action can block the tracker.
• Go to the source. User documentation is at matomo.org/guide, the FAQ at matomo.org/faq, and developer documentation at developer.matomo.org. There is a live installation to explore at demo.matomo.org. Settings and defaults change between versions; this article was checked against those sources in August 2026, against Matomo 5.13.0.

10. Summary

• Matomo is open source web analytics you operate yourself, on your own server or on Matomo Cloud. Every strength and every failure mode follows from where the data physically sits.
• It began as Piwik in 2007, a name invented from "kiwi" that meant nothing. It became Matomo in January 2018, a Japanese word meaning "decent", chosen because it was an argument rather than a label.
• Matomo stores your analytics twice: raw log data and pre-calculated archives. Almost every confusing behaviour becomes obvious once you know which of the two you are looking at.
• Archiving is the whole performance story on a self-hosted install. Move it to cron, set browser archiving to No, and set browser_archiving_disabled_enforce = 1.
• The Visits Log is the feature no hosted competitor matches, and it is also the first thing any privacy configuration switches off. Those are the same fact.
• A segment is not a filter over existing totals. It builds a complete new set of archives from raw data, which is why it is slow and why it needs the raw data to still exist.
• Privacy-friendly is a configuration, not a property. The CNIL exemption is a list of things to disable, including the Visits Log, User ID, heatmaps, session recordings and A/B testing. Since Matomo 5.9.0 the checklist is a screen in the product.
• Self-hosting moves the legal responsibility onto you, in full. There is no second party doing the patching, the retention, or the erasure requests.
• Pageviews are the floor, not the ceiling: events, site search and custom dimensions record what people did rather than only where they went. A search with zero results is the most actionable number in the product.
• A single-page application tracks nothing after its first screen unless you send virtual pageviews, and setCustomUrl plus setDocumentTitle must come before trackPageView or every screen is filed under the previous one.
• Your own URLs and page titles are stored verbatim. Privacy starts in the measurement design, not in the settings screen, because deciding not to collect something is the only protection a future misconfiguration cannot undo.
• A hosted tool's privacy features are commitments about behaviour you cannot observe; a self-hosted tool's are states you can inspect. Anonymised IP addresses sit in log_visit.location_ip with the masked bytes at zero, and one query settles it.
• config_id is a fingerprint that has been deliberately broken: rotated every 24 hours, scoped per site, seeded with a random value discarded daily and unrecoverable afterwards.
• Unique visitors are not processed for year or custom ranges by default, because the count needs raw data for the whole period. On Cloud you cannot enable it, because there is no configuration file to edit.
• Site count barely affects tracking and dominates archiving. One client's dashboard is fast regardless of how many other clients exist; the All Websites overview is the page that slows down. Split a long archiving run with --max-websites-to-process rather than buying a bigger server.
• In a shared installation the privacy and retention settings are installation-wide, so every client gets one policy, and one database holds every client's visitor data. Those two facts, not maintenance effort, are what decide one instance or several.
• Serving the tracker from stats.clientdomain.com makes requests same-site and unlisted by blockers, which improves accuracy. It does not make the cookies first-party, because they already were.
• The opt-out is a cookie, which is the paradox: remembering that somebody does not want to be tracked means storing something on their device. Clear cookies and the opt-out is gone. An opt-out is also not consent - Matomo has a separate requireConsent API for that.
• The log importer reads your web server's access logs, which means analytics for a period before Matomo was installed, and visibility of bots that never run JavaScript.
• Deleting raw data is nearly always right, and it silently disables the Visits Log, new segments, heatmaps and session recordings for those dates. Existing reports are untouched.

THE TWO KINDS OF DATA  (name which one you mean, first)
log data     log_visit, log_link_visit_action, log_action,
             log_conversion, log_conversion_item
             raw, large, powers Visits Log + NEW segments + heatmaps
archive data archive_numeric_YYYY_MM, archive_blob_YYYY_MM
             aggregated, small, powers every dashboard number

FIX A SLOW SELF-HOSTED MATOMO  (in this order)
crontab      5 * * * * www-data /usr/bin/php /path/to/matomo/console \
                       core:archive --url=https://analytics.example.com/
UI           Administration > System > General settings
             Archive reports when viewed from the browser : No
             Archive reports at most every X seconds      : 3600
config.ini   [General]
             browser_archiving_disabled_enforce = 1
then         check EXISTING segments: real-time ones go empty

TRACKING CODE  (order in the queue matters)
_paq.push(['setCustomDimension', 1, 'member']);   config FIRST
_paq.push(['trackPageView']);                     then the pageview
_paq.push(['enableLinkTracking']);                downloads + outlinks

BEYOND PAGEVIEWS
trackEvent        category, action, name (opt), value (opt)
trackSiteSearch   keyword (required), category, resultCount
                  resultCount 0 = what people asked for and did not get
setCustomDimension  id, value   -- push BEFORE the pageview/event
  scope visit     describes the whole session
  scope action    describes one pageview/event; can be EXTRACTED
                  automatically from URL, title or query parameter
  5 slots/scope   ./console customdimensions:add-custom-dimension
                           --scope=visit --count=10
naming            name events after the OUTCOME, never the element
                  'Contact','Submit','Quote form'   survives a redesign
                  'Buttons','Click','.green-button' dies silently

SINGLE-PAGE APPLICATIONS  (order is the whole trick)
_paq.push(['setCustomUrl', currentUrl]);       these two
_paq.push(['setDocumentTitle', title]);        FIRST
_paq.push(['trackPageView']);                  then this
fuller form also: setReferrerUrl, deleteCustomVariables 'page'
trap 1   skip the framework's INITIAL route event, or entry
         pages are counted twice
trap 2   track after the render, or every screen carries the
         previous screen's title

KEEP PERSONAL DATA OUT OF THE URL  (no setting fixes this)
risk        /account/peter-martin/orders, "Invoice for J. de Vries",
            ?email=... after a form post -- all stored verbatim
fixes       1. do not put it in the URL at all
            2. exclude those query parameters per site
            3. setCustomUrl / setDocumentTitle to send a generic value
            4. data-matomo-mask attribute to mask it in the interface
automatic   card numbers, phone numbers, emails, passwords and SSNs
            are always anonymised -- a safety net, not a strategy

REPORTING API
POST to /index.php   module=API&method=VisitsSummary.get
                     idSite=1&period=month&date=2026-08-01&format=json
token_auth           in the POST BODY, never in the URL
filter_limit         DEFAULT 100  → use -1 for all rows
format               json xml csv tsv html rss original
period               day week month year range
segment              countryCode==de;deviceType==smartphone
                     ; = AND   , = OR   =@ contains   =^ starts with
API.getReportMetadata  lists every report this install has

TRACKING HTTP API
/matomo.php?idsite=1&rec=1&url=...&action_name=...
required     idsite, rec=1
send_image=0 reply 204 instead of a 1x1 GIF  (use server-side)
bulk         POST {"requests":["?idsite=1&rec=1&url=...", ...],
                   "token_auth":"..."}  to /matomo.php
             each entry is a normal query string, URL-encoded

LOG IMPORT  (analytics for the past, and for bots)
python3 misc/log-analytics/import_logs.py --url=... --idsite=1 \
        --recorders=4 --enable-static --enable-bots \
        --enable-http-errors --enable-http-redirects  access.log
formats      Apache, Nginx, IIS, Tomcat defaults; NCSA Common;
             Extended; W3C Extended; Nginx JSON; AWS CloudFront/S3/ELB
undetected   --log-format-name=ovh, incapsula_w3c

MANY CLIENT SITES  (what actually scales)
tracking a hit       scales with HITS, not with site count
one site dashboard   unaffected by how many sites exist
All Websites page    scales with SITE COUNT: slows down first
archiving cron       sites x periods x segments: the real cost
  split it           core:archive --max-websites-to-process=5
                     core:archive --max-archives-to-process=100
limits               On-Premise unlimited sites; Cloud up to 30
shared install       privacy + retention settings are INSTALLATION-WIDE
                     one database = every client's data at once

TRACKER ON THE CLIENT'S OWN DOMAIN
On-Premise    CNAME + certificate + [General]
              trusted_hosts[] = "stats.example.com"
              (without it Matomo REJECTS the hostname)
Cloud         custom domain = ENTERPRISE plan only
you gain      same-site requests, not on any blocklist, accuracy
you do NOT    first-party cookies (already were, set via
  gain        document.cookie on the tracked page), nor immunity
              from path-based blocking of /matomo.php + matomo.js

OPT-OUT vs CONSENT  (opposite defaults, different APIs)
opt-out    tracking is ON, visitor can switch it off
           optUserOut / forgetUserOptOut / isUserOptedOut
           stored in mtm_consent_removed, 30 years, PER DOMAIN
           clear cookies → opt-out gone; block cookies → cannot opt out
consent    nothing tracked until the visitor agrees
           requireConsent  (push BEFORE trackPageView)
           setConsentGiven      = this session only
           rememberConsentGiven = stored in a cookie
cookies    requireCookieConsent / setCookieConsentGiven
           disableCookies = no first-party cookies at all
form       use the SELF-CONTAINED opt-out code: the tracker-based
           form loads from your Matomo host, so a blocker hides it
           from exactly the visitor who wanted it

PREMIUM PLUGINS  (the "free" caveat)
free core     unlimited sites, unlimited hits, no sampling
paid plugins  A/B Testing, Heatmaps, Session Recording, Funnels,
              Form Analytics, Cohorts, Crash Analytics, Roll-Up,
              SAML/LDAP - annual, priced by user tier
budget note   one plugin's yearly price commonly exceeds the yearly
              cost of the server running the whole installation

PRIVACY SETTINGS THAT MATTER   Administration > Privacy
anonymise IP          2 bytes; masked IN MEMORY before writing
                      84.105.72.19 → 84.105.0.0   (1 byte: .72.0,
                      3 bytes: 84.0.0.0); the bytes are never written,
                      so nobody can recover them afterwards
VERIFY it yourself    SELECT INET6_NTOA(location_ip) FROM matomo_log_visit
                      ORDER BY idvisit DESC LIMIT 5;
masked IP for geo     yes: coarser country data, no stored address
pseudonymise User ID  whenever a User ID is set at all
anonymise Order ID    it usually maps to a named customer
delete old RAW data   Matomo recommends keeping 3-6 months
delete old REPORT data  almost never what you want
Do Not Track          DEPRECATED: W3C group closed, Safari dropped it

CNIL CONSENT EXEMPTION   Administration > Privacy > Compliance (5.9.0+)
enforced   IP masked to 2 bytes, first-party cookies only,
           campaign parameters stripped, segmented data rounded to 10,
           retention 180 days
disabled   Visits Log, Visitor Profiles, User ID, heatmaps,
           session recordings, A/B testing, cross-domain tracking
manual     the opt-out mechanism, custom event categories,
           anything graded Unknown
note       ecommerce tracking usually takes you back OUT of the
           exemption; this is French law, not EU-wide

DEFAULTS WORTH MEMORISING
visit           30 minutes of inactivity   [Tracker] visit_standard_length=1800
_pk_id          13 months     visitor ID cookie
_pk_ses         30 minutes    session cookie
_pk_ref         6 months      attribution cookie
config_id       24 hours max, per site, seed destroyed daily
filter_limit    100 rows      (API)
unique visitors day/week/month YES, year/range NO
                enable_processing_unique_visitors_year = 1
                (On-Premise only; needs raw data to still exist)

Verified August 2026 against matomo.org, developer.matomo.org
and Matomo 5.13.0 (released 16 August 2026)

Read this way, Matomo stops being a privacy badge you install and becomes a database you are responsible for. And when a site owner tells you their analytics is finally private because they host it themselves, the useful question is not where the server is: it is whether anyone has opened the retention settings since the day it was installed, because a tool that quietly keeps every visitor's full path through the site for three years is not made private by the address of the machine it runs on.