github-rate-limits-exporter

Prometheus exporter to monitor the Github API rate-limits.

Introduction

If you have ever tried using Github's API, you have probably already run into Github's rate limiting errors.
Without authorization, Github only allows 60 requests per hour (!!), and after creating and using your
own personal access token, you are upgraded to 5000 requests per hour.

That rate limit can be easily reached in just a few minutes by calling the API to list basic information from a medium
sized repository and you would have to wait 50+ minutes for the rate limit to reset in order to continue or try again.
You can up the rate limit to 15,000 with an enterprise account but the problem remains the same:

If your service/program needs to make consistent and/or sustained requests to Github's APIs,
you will have to work around and make the most of Github's rate limits.

So, the Prometheus Github rate-limits exporter was introduced to expose the remaining, used, limit
(quotas) and reset (rate-limit window resets in UTC seconds) information per Github API as metrics in order
to create alerting events and (Grafana) monitoring dashboards.

For the exporter to fetch and expose the Github API rate-limits, you need to supply:

• a GitHub Personal Access Token (PAT)
• or GitHub App (APP) credentials.

As standalone Python command line tool (pypi)

Install the tool through pypi:

pip3 install github-rate-limits-exporter
./github-rate-limits-exporter --help

Tox (wrapper)

Clone the repository and install tox:

pip install --user tox

Run as PAT Github authentication type

tox -e run-exporter -- \
  --github-auth-type pat \
  --github-account my_account_name \
  --github-token my_token

Run as APP (Github App) Github authentication type

tox -e run-exporter -- \
  --github-auth-type app \
  --github-account my_account_name \
  --github-app-id my_app_id \
  --github-app-installation-id my_installation_id \
  --github-app-private-key-path /path/to/private_key.pem

Docker

Clone the repositroy and build the docker container image:

docker build -t prometheus-gh-rate-limit-exporter:latest .

or pull directly from Docker Hub:

docker pull theodore86/prometheus-gh-rate-limit-exporter:latest

Run as PAT Github authentication type

docker run -p 10050:10050 -d \
  --name gh-rl-exporter \
  --restart on-failure \
  -e GITHUB_ACCOUNT=my_account_name \
  -e GITHUB_AUTH_TYPE=pat \
  -e GITHUB_TOKEN=my_token \
  -e EXPORTER_LOG_LEVEL=4 \
  prometheus-gh-rate-limit-exporter:latest

Run as APP (Github App) Github authentication type

docker run -p 10050:10050 -d \
  --name gh-rl-exporter \
  --restart on-failure \
  -e GITHUB_AUTH_TYPE=app \
  -e GITHUB_ACCOUNT=my_account_name \
  -e GITHUB_APP_ID=111111 \
  -e GITHUB_APP_INSTALLATION_ID=22222222 \
  -e GITHUB_APP_PRIVATE_KEY_PATH=/app/key.pem \
  -e EXPORTER_LOG_LEVEL=4 \
  --mount type=bind,source=/ws/key.pem,target=/app/key.pem,readonly \
  prometheus-gh-rate-limit-exporter:latest

Docker-Compose

Another way to test and observe the exporter is through the Prometheus/Grafana/AlertManager
stack on top of the docker-compose:

Clone the repository and install tox tool:

pip install --user tox

Run as PAT Github authentication type

export GITHUB_AUTH_TYPE=pat
export GITHUB_TOKEN=your_token
export GITHUB_ACCOUNT=your_account
export EXPORTER_LOG_LEVEL=4
export GF_SECURITY_ADMIN_USER=username
export GF_SECURITY_PASSWORD=password
tox -e dc-run

Run as APP (Github App) authentication type

export GITHUB_ACCOUNT=your_account
export GITHUB_AUTH_TYPE=app
export GITHUB_APP_ID=12345
export GITHUB_APP_INSTALLATION_ID=123456
export GITHUB_APP_SRC_PRIVATE_KEY_PATH=/ws/private_key.pem
export GITHUB_APP_PRIVATE_KEY_PATH=/tmp/private_key.pem
export EXPORTER_LOG_LEVEL=4
export GF_SECURITY_ADMIN_USER=username
export GF_SECURITY_PASSWORD=password
tox -e dc-run

Connect to Portainer management UI

• Portainer (credentials: admin/adminpassword)

Connect to Prometheus, Grafana and AlertManager

• Prometheus
• Grafana
• AlertManager

See also the existing examples:

• Grafana dashboards
• Alertmanager rules

Cleanup/teardown the composed services

tox -e dc-clean

Kubernetes - Helm chart

This helm chart helps to install and configure github-rate-limits exporter on Kubernetes clusters.

In order to try out (locally) the charts

• Install the tools:

  • KIND binary
  • Helmfile binary

sudo bash kubernetes/prerequisites.sh

• Create the KIND cluster:

kind create cluster --name monitor --config kubernetes/kind.yml

• Bring up the github-rate-limits exporter and the Kubernetes Prometheus stack:

export GITHUB_ACCOUNT=your_account
export GITHUB_AUTH_TYPE=app
export GITHUB_APP_ID=12345
export GITHUB_APP_INSTALLATION_ID=123456
export GITHUB_APP_SRC_PRIVATE_KEY_PATH=/ws/private_key.pem
helmfile -f kubernetes/helmfile.yml sync

Cleanup/teardown the workloads

helmfile -f kubernetes/helmfile.yml destroy

Other Projects

• Github Rate Limits Exporter - written in GO

References

• creating-a-personal-access-token
• creating-a-github-app
• installing-github-apps-in-your-organization
• installing-github-apps-in-your-repository
• how-to-get-most-out-of-github-api-rate-limits