GitLab Metrics Collector

Wer mehrere GitLab-Projekte betreut, kennt das Problem: Man möchte auf einen Blick sehen, wie es um Pipeline-Laufzeiten, offene Issues oder Deployment-Häufigkeiten steht – am besten ohne sich jedes Mal durch die GitLab-Oberfläche klicken zu müssen. Exportiert man die Daten manuell, ist das zeitaufwendig und fehleranfällig. Dashboards in GitLab selbst sind nett, aber oft zu wenig flexibel, wenn man Metriken über mehrere Projekte hinweg aggregieren oder eigene KPIs definieren möchte.

Genau hier setzt der GitLab Metrics Collector an.

Die Idee

#

Die Grundidee ist denkbar einfach: Ein kleiner Go-Service läuft täglich als Kubernetes CronJob, spricht die GitLab-API an, sammelt die relevanten Rohdaten und berechnet daraus KPIs. Diese werden anschließend in einer PostgreSQL-Datenbank abgelegt, die wiederum als Datasource für Grafana dient. So entsteht ein vollständiges Monitoring-Setup, das sich nahtlos in bestehende Kubernetes- Infrastrukturen einfügt und keinerlei manuellen Aufwand erfordert.

Das Ergebnis: Ein Grafana-Dashboard, das täglich aktuell zeigt, wie es um Pipeline-Performance, Issue-Entwicklung, Deployment-Frequenz und weitere Metriken der eigenen GitLab-Projekte steht.

Gesagt, getan. Das hier vorgestellte Projekt ist genau das und bietet folgende Funktionen ✨:

• 📊 Automatisches Sammeln von GitLab-Metriken über die GitLab API
• 🗄️ Speicherung der Rohdaten und berechneten KPIs in einer PostgreSQL-Datenbank
• 📈 Nahtlose Integration mit Grafana als Visualisierungsschicht
• ⏰ Kubernetes-nativer Betrieb via CronJobs für tägliche Datenerfassung
• 🔔 Benachrichtigungen über Collection-Runs via Apprise
• 🐳 Multi-Stage Docker-Build für ein schlankes Container-Image
• ⚙️ Flexible Konfiguration via config.yaml
• 🧰 Lokale Entwicklungsumgebung mit docker-compose oder podman-compose
• 🤖 Task-Automatisierung via just

Architektur

#

Das Projekt folgt dem Ports-&-Adapters-Muster (auch bekannt als Hexagonale Architektur) und ist klar in drei Schichten unterteilt:

Domain

#

Der Kern des Projekts enthält die Datenmodelle und Interfaces – vollständig unabhängig von externen Bibliotheken oder Frameworks. Hier wird definiert, was eine Metrik ist und welche Operationen darauf möglich sind. Diese Schicht ändert sich nur, wenn sich die fachlichen Anforderungen ändern.

Application

#

Die Applikationsschicht orchestriert die Use Cases: Sie koordiniert das Abrufen der Rohdaten aus GitLab, die Berechnung der KPIs und das Speichern in der Datenbank. Sie kennt nur die Interfaces der Domain – nicht deren konkrete Implementierungen. Das macht sie vollständig testbar, ohne dass eine echte Datenbankverbindung oder ein echter GitLab-Zugang nötig ist.

Infrastructure

#

Hier leben die konkreten Implementierungen: der GitLab-API-Client, das PostgreSQL-Repository inklusive Migrations und der Apprise-Notification-Client. Diese Schicht kann ausgetauscht oder erweitert werden, ohne die Kern- oder Applikationslogik zu berühren. Neue Metriken lassen sich so einfach hinzufügen, indem man einen neuen Collector in der Infrastructure-Schicht implementiert.

Konfiguration

#

Die Konfiguration erfolgt über eine config.yaml-Datei. Hier werden die GitLab-Instanz-URL, der Personal Access Token sowie die zu überwachenden Projekte definiert. Für jeden CronJob-Run wird außerdem Apprise als Notification-Service angebunden, sodass man bei erfolgreicher oder fehlgeschlagener Datenerfassung direkt benachrichtigt wird – ob per E-Mail, Slack, Matrix oder einem der vielen anderen von Apprise unterstützten Dienste.

Beispielkonfigurationen für beide Dateien liegen im examples/-Verzeichnis und können als Ausgangspunkt genutzt werden.

Lokale Entwicklung

#

Für die lokale Entwicklung gibt es einen vollständigen docker-compose-Stack, der PostgreSQL, Apprise und den Collector gemeinsam startet. Wer just installiert hat, kann den gesamten Workflow – von der initialen Konfiguration bis zum Start des Stacks – mit wenigen Befehlen erledigen:

1
2
3

just bootstrap   # Konfigurationsdateien vorbereiten
just up          # Stack starten
just down        # Stack stoppen

Alternativ funktioniert natürlich auch der klassische Weg über podman-compose oder docker-compose direkt.

Deployment in Kubernetes

#

Der Collector ist von Grund auf für den Betrieb in Kubernetes konzipiert. Ein CronJob sorgt dafür, dass die Metriken einmal täglich automatisch gesammelt werden – ohne manuelle Eingriffe. Das Container-Image wird über einen schlanken Multi-Stage-Build erstellt: Kompiliert wird mit golang:alpine, das finale Image basiert auf einem minimalen alpine-Image und enthält nur das fertige Binary.

Visualisierung mit Grafana

#

Die gesammelten Daten lassen sich direkt als PostgreSQL-Datasource in Grafana einbinden. So entstehen Dashboards, die auf einen Blick zeigen, wie es um Pipeline-Performance, Issue-Entwicklung oder Deployment-Frequenz steht – vollständig anpassbar und ohne manuellen Exportaufwand. Gerade bei mehreren Projekten oder Teams entsteht so ein wertvolles Werkzeug für regelmäßige Reviews oder einfach für den täglichen Überblick.

Für mich hat sich das Tool bereits in mehreren Projekten bewährt und gibt mir täglich einen schnellen Überblick über den Zustand meiner GitLab-Projekte. Wer ähnliche Workflows hat, ist herzlich eingeladen, es auszuprobieren und gerne auch beizutragen – Issues und Merge Requests sind willkommen!