Accurately counting Daily, Weekly & Monthly active users on JupyterHub

Being able to say ‘we served X unique users over the last month’ (the Monthly Active User metric) is very helpful when advocating for resources for a JupyterHub your organization is running. However, until now, figuring out that number accurately has been difficult, requiring keeping and analysing JupyterHub logs.

That changes with JupyterHub 3.1! This Pull Request adds daily, weekly, and monthly active user metrics to JupyterHub, accessible via the prometheus interface by hitting the /metrics URL on your JupyterHub. These metrics are calculated by JupyterHub itself, and are pretty accurate as it already keeps track of when a user was last active. This relies metric on each JupyterHub user matching an actual user, so if you are using your JupyterHub deployment purely as an API with ephemeral users (as binderhub does, for example) or delete inactive users, these will not be useful numbers.

Ideally, you should have a prometheus instance to scrape and store metrics from your JupyterHub over time, so you can track this metric over time. However, in a pinch, you can also go directly to https://<your-hub-url>/hub/api/metrics and see the current value of these metrics. They are in the prometheus exposition format, but you can look for something like:

# HELP jupyterhub_active_users number of users who were active in the given time period
# TYPE jupyterhub_active_users gauge
jupyterhub_active_users{period="24h"} 610.0
jupyterhub_active_users{period="7d"} 2800.0
jupyterhub_active_users{period="30d"} 4526.0

This denotes that this particular hub had 610 daily active users (active over the last 24 hours), 2800 weekly users (over last 7d) and 4526 monthly ones (over the last 30 days). Very helpful if you want to quickly add numbers to a report :)

Note that depending on your hub’s configuration, access to the /metrics endpoint might require authentication.

If you do have a prometheus installation for your JupyterHub, you may benefit from deploying the JupyterHub Grafana Dashboards. These are targeted at installations of zero-to-jupyterhub on kubernetes, and provide a lot of useful usage & diagnostic information.

Grafana Dashboard showing “Hub Usage Stats” for a JupyterHub deployment. Four panels, clockwise: Current Active Users, Daily Active Users, Weekly Active Users, Monthly Active Users.

Happy report writing!