Track requests to your Flask server with Matomo
Project description
flask-matomo2
flask-matomo2 is a library which lets you track the requests of your Flask website using Matomo (Piwik).
Forked from LucasHild/flask-matomo.
Installation
pip install flask-matomo2
Using flask-matomo2 in your project
Simply add flask-matomo2
to your dependencies:
# pyproject.toml
dependencies = [
"flask-matomo2",
]
Using Poetry
poetry add flask-matomo2
Using PDM
pdm add flask-matomo2
Usage
from flask import Flask, jsonify
from flask_matomo2 import Matomo
app = Flask(__name__)
matomo = Matomo(
app,
matomo_url="https://matomo.mydomain.com",
id_site=5, token_auth="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
@app.route("/")
def index():
return jsonify({"page": "index"})
if __name__ == "__main__":
app.run()
In the code above:
- The Matomo object is created by passing in the Flask application and arguments to configure Matomo.
- The matomo_url parameter is the url to your Matomo installation.
- The id_site parameter is the id of your site. This is used if you track several websites with one Matomo installation. It can be found if you open your Matomo dashboard, change to site you want to track and look for &idSite= in the url.
- The token_auth parameter can be found in the area API in the settings of Matomo. It is required for tracking the ip address.
Adding details to route
You can provide details to a route in 2 ways, first by using the matomo.details
decorator:
from flask import Flask, jsonify
from flask_matomo2 import Matomo
matomo = Matomo(
matomo_url="https://matomo.mydomain.com",
id_site=5, token_auth="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
app = Flask(__name__)
matomo.init_app(app)
@app.route("/foo")
@matomo.details(action_name="Foo")
def foo():
return jsonify({"page": "foo"})
if __name__ == "__main__":
app.run()
Here the Matomo
object is created before the Flask
object and then calling init_app
.
Or by giving details to the Matomo constructor:
from flask import Flask, jsonify
from flask_matomo2 import Matomo
app = Flask(__name__)
matomo = Matomo(
app,
matomo_url="https://matomo.mydomain.com",
id_site=5,
token_auth="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
routes_details={
"/foo": {
"action_name": "Foo"
}
}
)
@app.route("/foo")
def foo():
return jsonify({"page": "foo"})
if __name__ == "__main__":
app.run()
Adjusting the tracked url
If your app is behind a proxy and you don't adjust the url in any other way, you can adjust the tracked url by setting base_url
without trailing /
in either the constructor:
from flask import Flask, jsonify
from flask_matomo2 import Matomo
matomo = Matomo(
matomo_url="https://matomo.mydomain.com",
id_site=5,
base_url="https://mydomain.com/apps")
app = Flask(__name__)
matomo.init_app(app)
@app.route("/foo")
@matomo.details(action_name="Foo")
def foo():
return jsonify({"page": "foo"})
if __name__ == "__main__":
app.run()
Or a call to activate
:
from flask import Flask, jsonify
from flask_matomo2 import Matomo
matomo = Matomo.activate_later()
matomo.activate(
matomo_url="https://matomo.mydomain.com",
id_site=5,
base_url="https://mydomain.com/apps"
)
app = Flask(__name__)
matomo.init_app(app)
@app.route("/foo")
@matomo.details(action_name="Foo")
def foo():
return jsonify({"page": "foo"})
if __name__ == "__main__":
app.run()
The result is that a request to /foo
will be tracked as https://mydomain.com/apps/foo
.
Using a custom client
By default, Matomo uses httpx.Client
to make the tracking call. You can override this by setting client
as long as the client uses the same api as httpx
:s Client
.
Ignoring a route
You can ignore tracking a route by decorating the route with @matomo.ignore()
:
from flask import Flask, jsonify
from flask_matomo2 import Matomo
matomo = Matomo(
matomo_url="https://matomo.mydomain.com",
id_site=5,
)
app = Flask(__name__)
matomo.init_app(app)
@app.route("/foo")
@matomo.ignore()
def foo():
return jsonify({"page": "foo"})
if __name__ == "__main__":
app.run()
Or ignore the route in the matomo constructor:
from flask import Flask, jsonify
from flask_matomo2 import Matomo
matomo = Matomo(
matomo_url="https://matomo.mydomain.com",
id_site=5,
ignored_routes=["/foo"]
)
app = Flask(__name__)
matomo.init_app(app)
@app.route("/foo")
def foo():
return jsonify({"page": "foo"})
if __name__ == "__main__":
app.run()
Ignore routes by patterns
You can also ignore routes by giving a list of regexes to the constructor:
from flask import Flask, jsonify
from flask_matomo2 import Matomo
matomo = Matomo(
matomo_url="https://matomo.mydomain.com",
id_site=5,
ignored_patterns=["/fo.*"]
)
app = Flask(__name__)
matomo.init_app(app)
@app.route("/foo")
def foo():
return jsonify({"page": "foo"})
if __name__ == "__main__":
app.run()
Ignore requests by User-Agent patterns
You can supply regex patterns to ignore request based on User-Agent:
from flask import Flask, jsonify
from flask_matomo2 import Matomo
matomo = Matomo(
matomo_url="https://matomo.mydomain.com",
id_site=5,
ignored_ua_patterns=[".*bot.*"]
)
app = Flask(__name__)
matomo.init_app(app)
@app.route("/foo")
def foo():
return jsonify({"page": "foo"})
if __name__ == "__main__":
app.run()
Meta
Spraakbanken 2023-2024 - https://spraakbanken.gu.se
Lucas Hild (original project Flask-Matomo
)- https://lucas-hild.de
This project is licensed under the MIT License - see the LICENSE file for details
Release Notes
Latest Changes
0.5.0 - 2024-08-14
Added
- track urlref. PR #58 by @kod-kristoff.
0.4.4 - 2024-08-14
Documentation
-
add metadata about python versions.
-
sort out documentation of params . PR #56 by @kod-kristoff.
0.4.1 - 2024-08-14
Changed
0.4.0 - 2024-03-04
Changed
- Use post request when tracking. PR #51 by @kod-kristoff.
- Enable late activation. PR #50 by @kod-kristoff.
- fix: allow for dont tracking based on user-agent. PR #34 by @kod-kristoff.
0.3.0 - 2023-05-25
Added
- Add PerfMsTracker. PR #33 by @kod-kristoff.
0.2.0 - 2023-05-22
Changed
- Track original IP address if request was forwarded by proxy. Tanikai/flask-matomo by @Tanakai.
- Change ignored routes to compare against rules instead of endpoint. MSU-Libraries/flask-matomo by @meganschanz.
- Add ignored UserAgent prefix; set action to be url_rule. MSU-Libraries/flask-matomo by @natecollins.
- Fix matomo.ignore decorator.
- Handle request even if tracking fails. PR #30 by @kod-kristoff.
- Ignore routes by regex. PR #29 by @kod-kristoff.
- Make token_auth optional. PR #28 by @kod-kristoff.
- Track dynamic request data. PR #27 by @kod-kristoff.
- Also track request time. PR #26 by @kod-kristoff.
- Extend tracked variables. PR #25 by @kod-kristoff.
- fix matomo.details decorator. PR #19 by @kod-kristoff.
0.1.0
- Forked from LucasHild/flask-matomo.
- Renamed to
flask-matomo2
. - Add test suite.
- Setup CI with Github Actions.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for flask_matomo2-0.5.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fa0592d4c7dd2f348f6438eb84c82411003378103c63ed7d07a97477c1c842ee |
|
MD5 | 671371b0443eb8531911187850408548 |
|
BLAKE2b-256 | 102b57b25bd8d1efcbc5f206bce38b4c98399fb254637104f77f58c4aa32e796 |