Configuring tracked details

Sometimes we want to change something that is tracked, it can either be about a route or about a specific request.

Configuring a route

We can configure a route by giving the middleware a dict with details.

from asgi_matomo import MatomoMiddleware
from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette.responses import JSONResponse
from starlette.routing import Route


async def foo(request):
    return JSONResponse({"name": "foo"})


app = Starlette(
    routes=[Route("/foo", foo)],
    middleware=[
        Middleware(
            MatomoMiddleware,
            matomo_url="YOUR MATOMO TRACKING URL",
            idsite=12345,  # your service tracking id
            route_details={
                "/foo": {"action_name": "Foo/foo", "e_c": "Foo", "e_a": "Playing"}
            },
        )
    ],
)

In this example, we are changing the details about the route /foo in the following ways:

1. We override the action_name with Foo/foo.
2. We add an event category e_c and an event e_a to this roure.

Configuring a request

We can also configure what is tracked during a request by adding a dictionary with values as asgi_matomo in the request state.

from asgi_matomo import MatomoMiddleware
from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette.requests import Request
from starlette.responses import JSONResponse
from starlette.routing import Route


async def foo(request: Request):
    if "state" not in request.scope:
        request.scope["state"] = {}
    request.scope["state"]["asgi_matomo"] = {
        "action_name": "Foo/foo",
        "e_c": "Foo",
        "e_a": "Playing",
        "cvar": {"anything": "goes"},
    }
    return JSONResponse({"name": "foo"})


app = Starlette(
    routes=[Route("/foo", foo)],
    middleware=[
        Middleware(
            MatomoMiddleware,
            matomo_url="YOUR MATOMO TRACKING URL",
            idsite=12345,  # your service tracking id
        )
    ],
)

Here, in this example, we

1. override the action_name
2. add an event category e_c and an event e_a
3. We also add cvar, where custom variables can be tracked.

Note

Notice that cvar can only be set during a request.

Tracking time for different steps of a request

To help you track time spent on different tasks, you can use PerfMsTracker.

import asyncio

from asgi_matomo import MatomoMiddleware
from asgi_matomo.trackers import PerfMsTracker
from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette.responses import JSONResponse
from starlette.routing import Route


async def fetch_data():
    await asyncio.sleep(0.2)
    return {"data": 4000}


async def homepage(request):
    with PerfMsTracker(scope=request.scope, key="pf_srv"):
        # fetch/compute data
        data = await fetch_data()
    return JSONResponse(data)


app = Starlette(
    routes=[Route("/", homepage)],
    middleware=[
        Middleware(
            MatomoMiddleware,
            matomo_url="YOUR MATOMO TRACKING URL",
            idsite=12345,  # your service tracking id
        )
    ],
)

In this example the function fetch_data simulates fetching some data from somewhere else, and we want to track the time it takes to fetch the data in the variable pf_srv.

So we use PerfMsTracker as a context manager and the time is recorded between entering and exiting the context. The elapsed time (in milliseconds) is then stored in the request state under asgi_matomo with the given key (here = pf_srv).

Note

PerfMsTracker can also be used as an async context manager if that is needed.