Middleware for tracking ASGI requests with Matomo
Project description
asgi-matomo
Tracking requests with Matomo from ASGI apps.
MatomoMiddleware
adds tracking of all requests to Matomo to ASGI applications (Starlette, FastAPI, Quart, etc.). The intended usage is for api tracking (backends).
Note If you serve HTML (directly or by templates), it is suggested to track those parts through Matomo's javascript tracking.
Installation
pip install asgi-matomo
What is tracked
Currently this middleware tracks:
url
ua
: user_agentgt_ms
: mesaured as the time before and after this middleware call next in the asgi stack.send_image=0
for performance issuescvar
with at leasthttp_status_code
andhttp_method
set.lang
ifaccept-lang
is setcip
client ip, requiresaccess_token
to be given.action_name
that defaults to path, but can be specified.
You can also pass variable to track by adding an asgi_matomo
dict in the state
dict of the ASGI scope
:
scope = {
"state": {
"asgi_matomo": {
"e_a": "Playing",
"cvar": {
"your": "custom",
"data": "here",
}
}
}
}
The keys of the asgi_matomo
dict is expected to be valid parameter for the Matomo HTTP Tracking API. cvar
is serialized with the standard json
lib.
You can also track time spent on different tasks with trackers.PerfMsTracker
.
import asyncio
from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.routing import Route
from starlette.middleware import Middleware
from asgi_matomo import MatomoMiddleware
from asgi_matomo.trackers import PerfMsTracker
async def homepage(request):
async with PerfMsTracker(scope=request.scope, key="pf_srv"):
# fetch/compute data
await asyncio.sleep(1)
data = {"data": "a"*4000}
return JSONResponse(data)
app = Starlette(
routes=[Route("/", homepage)],
middleware=[
Middleware(
MatomoMiddleware,
matomo_url="YOUR MATOMO TRACKING URL",
idsite=12345, # your service tracking id
)],
)
Examples
Starlette
from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.routing import Route
from starlette.middleware import Middleware
from asgi_matomo import MatomoMiddleware
async def homepage(request):
return JSONResponse({"data": "a" * 4000})
app = Starlette(
routes=[Route("/", homepage)],
middleware=[
Middleware(
MatomoMiddleware,
matomo_url="YOUR MATOMO TRACKING URL",
idsite=12345, # your service tracking id
)],
)
FastAPI
from fastapi import FastAPI
from asgi_matomo import MatomoMiddleware
app = FastAPI()
app.add_middleware(
MatomoMiddleware,
matomo_url="YOUR MATOMO TRACKING URL",
idsite=12345, # your service tracking id
)
@app.get("/")
def home() -> dict:
return {"data": "a" * 4000}
API Reference
Overview
app.add_middleware(
MatomoMiddleware,
matomo_url="YOUR MATOMO TRACKING URL",
idsite=12345, # your service tracking id
access_token="SECRETTOKEN",
assume_https=True,
exclude_paths=["/health"],
exclude_patterns=[".*/old.*"],
route_details={
"route": {
"action_name": "Name",
}
}
)
Parameters:
- (Required)
matomo_url
: The URL to make your tracking calls to. - (Required)
idsite
: The tracking id for your service. - (Optional)
access_token
: Access token for Matomo. If this is setcip
is also tracked. Required for tracking some data. - (Optional)
assume_https
: IfTrue
, set tracked url scheme tohttps
, useful when running behind a proxy. Defaults toTrue
. - (Optional)
exclude_paths
: A list of paths to exclude, only excludes path that is equal to a path in this list. These are tried beforeexclude_patterns
. Defaults toNone
. - (Optional)
exclude_patterns
: A list of regex patterns that are compiled, and then exclude a path from tracking if any pattern match. Defaults toNone
. These are tried afterexclude_paths
. - (Optional)
route_details
: A dict with custom route-specific tracking data. Defaults toNone
.
Notes:
- Currently only some parts Matomo Tracking HTTP API is supported.
Ideas for further work
- filtering tracked of urls
- custom extraction of tracked data
This project keeps a changelog.
Development
This project uses pdm
and pre-commit
.
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
File details
Details for the file asgi_matomo-0.6.0.tar.gz
.
File metadata
- Download URL: asgi_matomo-0.6.0.tar.gz
- Upload date:
- Size: 52.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/5.0.0 CPython/3.12.2
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 87b02007a30afcbd3149ed421a71f7623289948e951fa7493054559cdea623a7 |
|
MD5 | 3e46bfd91d34178e20ae496bbbaa12c9 |
|
BLAKE2b-256 | f601466cd858df819206ebb9ce811d6275264f165eb39c48a2da8d1403afb616 |
File details
Details for the file asgi_matomo-0.6.0-py3-none-any.whl
.
File metadata
- Download URL: asgi_matomo-0.6.0-py3-none-any.whl
- Upload date:
- Size: 8.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/5.0.0 CPython/3.12.2
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 38566e6f74392e067daf6d1b258605a7bd05b53325cfdac5b324eeb79d76f904 |
|
MD5 | 6d585e487410f2064e0da657cdf924b0 |
|
BLAKE2b-256 | 2cba8da84ce2581b9fe006ed601620299ea9ce85426dff69608d9ce0f0619dca |