/matomo.php always returns 200 OK #18851

Expected Behavior

When databas is down /matomo.php should return 503, since service is not operational.

Current Behavior

FAQ says, to monitor the "HTTP Tracker API: request to /matomo.php should return http status code 200"
It does.... all the time. Even when database is down, and not able to handle incoming data.

Ref:https://matomo.org/faq/how-to/faq_20278/

Steps to Reproduce (for Bugs)

1. $ curl -i https://matomo.example.com/matomo.php -k
   HTTP/1.1 200 OK
2. Shut down database
3. $ curl -i https://matomo.example.com/matomo.php -k
   HTTP/1.1 200 OK

Context

When using loadbalancer/ssl-offloader/proxys, monitoring endpoints is crucial. Using /matomo.php is not reliable for the Tracker API as stated in FAQ.
When DB is down, clients will get a 400 error. But since matomo.php still reply with HTTP 200, loadbalancer will still send traffic to that broken endpoint.

Your Environment

• Matomo Version:4.6.2
• PHP Version:7.4
• Server Operating System: Ubuntu 20.04 LTS

HI @MrIsak
Thanks for creating the issue. I guess this might actually be on purpose, that the tracking doesn't return a error response code. Otherwise the failing request might be shown as error to website visitors.

Hi @sgiehl,
If that is the case, the documentation is misleading. Since /matomo.php never will result in anything else than HTTP 200-OK, it's quite useless to monitor it :P

I (from a IT-admin POV), rather get a notification from our surveillance system that something is wrong, than hiding an error in the visitors browser console; which they probably won't notice.

As I see it, there is two alternative:

1. Database problem, matomo can't connect for whatever reason. /matomo.php still delivers 200-OK to client, no alert from surveillance. Takes X hours for administrators to notice. Results in X hours of loss of statistics.

2. Database problem, matomo can't connect for whatever reason. /matomo.php delivers 503- Service is not available. Surveillance is configured as described in FAQ, sends alerts to administrator, whom can fix the problem. Yes, in the clients browser, the 503 will be visible, if they open network inspection tool. But on the other hand the problem will shortly be dealt with.

If you still think alternativ 1. is the way to go, how do you recommend we monitor the HTTP-tracking API?

@MrIsak Which documentation are you referring to?
From a Monitoring point of view it would indeed make sense to send another response code in that case.
But currently the code is catching all exceptions and outputs the error. See https://github.com/matomo-org/matomo/blob/4.x-dev/piwik.php#L71-L82
Maybe an option would be to look for the word Error: in the response 🤔

@tsteur what do you think of this?

@sgiehl https://matomo.org/faq/how-to/faq_20278/
"HOW DO I MONITOR THAT MATOMO SERVICE IS UP AND RUNNING?"
"HTTP Tracker API: request to /matomo.php should return http status code 200"

Looking for a specifik string in the response is one way to go. Even though I personally prefer a correct statuscode, since the possibility of string match/not match varies between different loadbalancers.

The FAQ would need to be updated. The matomo.php checking if Matomo is the web servers are up and running etc but doesn't test if the DB connection is working. I believe the first check /index.php?module=API&method=API.getMatomoVersion&token_auth=YOUR_TOKEN_AUTH_HERE would check this though.

In case you are wanting to use this for health checks for a load balancer, then you could

• either use the first URL (where it requests the Matomo Version)
• or create a new site in Matomo and change the matomo.php request to like matomo.php?rec=1&action_name=test&idsite={ID SITE OF THE NEWLY CREATED SITE}. This would then return an HTTP 400 or 500 (not sure). But not an HTTP 503.

In case you are a bit familiar with PHP, another way could be to create a simple plugin that provides an endpoint and checks the DB connection and if it fails then it would return eg an HTTP 503. The endpoint could also check if there's disk space available.

We could rename the issue to have a feature to provide an endpoint for health checks? Although I would assume that the URL mentioned to request the Matomo version could already work for this purpose.