Skip to main content

Middleware for tracking ASGI requests with Matomo

Project description

asgi-matomo

Packaging status CI codecov

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.
  • 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 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:

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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

asgi_matomo-0.6.0.tar.gz (52.1 kB view details)

Uploaded Source

Built Distribution

asgi_matomo-0.6.0-py3-none-any.whl (8.5 kB view details)

Uploaded Python 3

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

Hashes for asgi_matomo-0.6.0.tar.gz
Algorithm Hash digest
SHA256 87b02007a30afcbd3149ed421a71f7623289948e951fa7493054559cdea623a7
MD5 3e46bfd91d34178e20ae496bbbaa12c9
BLAKE2b-256 f601466cd858df819206ebb9ce811d6275264f165eb39c48a2da8d1403afb616

See more details on using hashes here.

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

Hashes for asgi_matomo-0.6.0-py3-none-any.whl
Algorithm Hash digest
SHA256 38566e6f74392e067daf6d1b258605a7bd05b53325cfdac5b324eeb79d76f904
MD5 6d585e487410f2064e0da657cdf924b0
BLAKE2b-256 2cba8da84ce2581b9fe006ed601620299ea9ce85426dff69608d9ce0f0619dca

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page