asgi-matomo 0.3.0

Middleware for tracking ASGI reqeusts with Matomo

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_agent
• gt_ms: mesaured as the time before and after this middleware call next in the asgi stack.
• send_image=0 for performance issues
• cvar with at least http_status_code and http_method set.
• lang if accept-lang is set
• cip client ip, requires access_token to be given.

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.

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(
  BrotliMiddleware,
  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 set cip is also tracked. Required for tracking some data.
• (Optional) assume_https: If True, set tracked url scheme to https, useful when running behind a proxy. Defaults to True.
• (Optional) exclude_paths: A list of paths to exclude, only excludes path that is equal to a path in this list. These are tried before exclude_patterns. Defaults to None.
• (Optional) exclude_patterns: A list of regex patterns that are compiled, and then exclude a path from tracking if any pattern match. Defaults to None. These are tried after exclude_paths.
• (Optional) route_details: A dict with custom route-specific tracking data. Defaults to None.

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.

Releas Notes

Latest Changes

[0.3.0] - 2023-05-22

Added

• Allow setting route-details