Package: asgi-matomo
asgi-matomoTracking requests with Matomo from ASGI apps.MatomoMiddlewareadds tracking of all requests to Matomo to ASGI applications (Starlette, FastAPI, Quart, etc.). The intended usage is for api tracking (backends).NoteIf you serve HTML (directly or by templates), it is suggested to track those parts through Matomo's javascript tracking.Installationpipinstallasgi-matomoWhat is trackedCurrently this middleware tracks:urlua: user_agentgt_ms: mesaured as the time before and after this middleware call next in the asgi stack.send_image=0for performance issuescvarwith at leasthttp_status_codeandhttp_methodset.langifaccept-langis setcipclient ip,requiresaccess_tokento be given.action_namethat defaults to path, but can be specified.You can also pass variable to track by adding anasgi_matomodict in thestatedict of the ASGIscope:scope={"state":{"asgi_matomo":{"e_a":"Playing","cvar":{"your":"custom","data":"here",}}}}The keys of theasgi_matomodict is expected to be valid parameter for theMatomo HTTP Tracking API.cvaris serialized with the standardjsonlib.You can also track time spent on different tasks withtrackers.PerfMsTracker.importasynciofromstarlette.applicationsimportStarlettefromstarlette.responsesimportJSONResponsefromstarlette.routingimportRoutefromstarlette.middlewareimportMiddlewarefromasgi_matomoimportMatomoMiddlewarefromasgi_matomo.trackersimportPerfMsTrackerasyncdefhomepage(request):asyncwithPerfMsTracker(scope=request.scope,key="pf_srv"):# fetch/compute dataawaitasyncio.sleep(1)data={"data":"a"*4000}returnJSONResponse(data)app=Starlette(routes=[Route("/",homepage)],middleware=[Middleware(MatomoMiddleware,matomo_url="YOUR MATOMO TRACKING URL",idsite=12345,# your service tracking id)],)ExamplesStarlettefromstarlette.applicationsimportStarlettefromstarlette.responsesimportJSONResponsefromstarlette.routingimportRoutefromstarlette.middlewareimportMiddlewarefromasgi_matomoimportMatomoMiddlewareasyncdefhomepage(request):returnJSONResponse({"data":"a"*4000})app=Starlette(routes=[Route("/",homepage)],middleware=[Middleware(MatomoMiddleware,matomo_url="YOUR MATOMO TRACKING URL",idsite=12345,# your service tracking id)],)FastAPIfromfastapiimportFastAPIfromasgi_matomoimportMatomoMiddlewareapp=FastAPI()app.add_middleware(MatomoMiddleware,matomo_url="YOUR MATOMO TRACKING URL",idsite=12345,# your service tracking id)@app.get("/")defhome()->dict:return{"data":"a"*4000}API ReferenceOverviewapp.add_middleware(MatomoMiddleware,matomo_url="YOUR MATOMO TRACKING URL",idsite=12345,# your service tracking idaccess_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 setcipis 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 partsMatomo Tracking HTTP APIis supported.Ideas for further work:filtering tracked of urlscustom extraction of tracked dataThis project keeps achangelog.Releas NotesLatest Changes[0.4.1] - 2023-05-29Addedtrack urlref. PR#21by@kod-kristoff.Changedrespect x-forwarded-for. PR#18by@kod-kristoff.[0.4.0] - 2023-05-25Handle lifespan correctly. PR#13by@kod-kristoff.add docs. PR#11by@kod-kristoff.[0.3.2] - 2023-05-23feat: add PerfMsTracker. PR#10by@kod-kristoff.[0.3.0] - 2023-05-22AddedAllow setting route-details