Watching Gmail labels with Prometheus+Grafana

This article briefly explains a python based script, which when run as a service, check gmail very 5 minutes for new messages against a list of labels (Inbox, High Importance, etc). The script gets the number unread and read emails with labels that you specify. Those numbers of messages are exposed as prometheus metrics, which can be rendered into pretty charts by Grafana.

Here is a close-up view of that same chart.

In-case the captions are too small, GREEN = Triage (backlog/todo), ORANGE = Inbox

Already know Prometheus, and just want the exporter? prometheus-gmail-exporter on GitHub.

I wanted a way to monitor incoming work (email)

I have a job that is email based. Very, very email based. So much so that as much as 90% of my incoming work, and tasks all comes via email. I wanted a way to easily, historically track what is coming in over the course of a week, especially to help notice why I am getting overloaded.

This article assumes you know roughly what Prometheus and Grafana are.

The Python script

Naturally, as anything that’s a quick script starts in Python first. I started hacking away in Python. Import the libs for Google’s API Client, OAuth, Prometheus. The code is Open Source and on GitHub, available here;

• prometheus-gmail-exporter on GitHub.

To run this yourself, you’ll need to get a client-secret.json file. See the README on GitHub for instructions on where to find this. Save it to your home directory, in .prometheus-gmail-exporter/client_secret.json.

Run the exporter like this;

./gmail-exporter --promPort 1234 INBOX Label_33

Where INBOX and Label_33 are IDs of Labels in Gmail. The label, the message counts and descriptions are exposed as a Prometheus endpoint.

The Prometheus endpoint

If you brows in your webbrowser to http://yourserver:1234 you’ll see an endpoint that looks something like this;

# HELP gmail_Label_33_total Triage Total
# TYPE gmail_Label_33_total gauge
gmail_Label_33_total 159.0
# HELP gmail_Label_33_unread Triage Unread
# TYPE gmail_Label_33_unread gauge
gmail_Label_33_unread 0.0

Note that the script exposes the total and unread counts of messages, as well as the friendly name of the label in the help text.

Add a Prometheus target for the endpoint

Now just add the target to your prometheus yaml file;

  - targets: ['myserver:1234']
    labels:
      type: gmail

The Grafana view

In Grafana, charting this was super simple. As I have a single endpoint, I don’t need to filter much, I just used the Guage names directly — gmail_Label_33_total .

Note; Slightly outdated screenshot, the metrics don’t have the gmail_ prefix. You’ll need those.

If you’re going to run this script to monitor several inboxes with one Prometheus server, then you’re going to need to specify additional labels here.

The result

You should end up with a pretty chart like this. Wow that’s a lot of incoming email.

The end result.