Feature/runner list (#69)

* Start adding Runner structs and garbage collector functions

* Add runners and new schemas

* Fix Redis methods to manipulate runner data

* Fix missing returned error name

* Update documentation

* Set gathering runner information to true by default

* Update store and fix duplicates entries for runners

* Update store and fix duplicates entries for runners

* Update add new runners as metrics

Author: Tosta-Mista

.gitignore

@@ -38,7 +38,9 @@ coverage
 gitlab-ci-pipelines-exporter
 
 !cmd/gitlab-ci-exporter
-!examples/**/gitlab-ci-exporter
+
+#!examples/**/gitlab-ci-exporter
+examples/*
 
 # IDE and OS stuff
 .idea

docs/metrics.md

@@ -13,6 +13,7 @@
 | `gcpe_metrics_count` | Number of GitLab pipelines metrics being exported || *available by default* |
 | `gcpe_projects_count` | Number of GitLab projects being exported || *available by default* |
 | `gcpe_refs_count` | Number of GitLab refs being exported || *available by default* |
+| `gcpe_runners_count` | Number of Runners being exported || *available by default* |
 | `gitlab_ci_environment_behind_commits_count` | Number of commits the environment is behind given its last deployment | [project], [environment] | `project_defaults.pull.environments.enabled` |
 | `gitlab_ci_environment_behind_duration_seconds` | Duration in seconds the environment is behind the most recent commit given its last deployment | [project], [environment] | `project_defaults.pull.environments.enabled` |
 | `gitlab_ci_environment_deployment_count` |Number of deployments for an environment | [project], [environment] | `project_defaults.pull.environments.enabled` |

pkg/config/config.go

@@ -129,6 +129,13 @@ type Pull struct {
 		IntervalSeconds int  `default:"1800" validate:"gte=1" yaml:"interval_seconds"` // IntervalSeconds defines the interval in seconds between scheduled fetches.
 	} `yaml:"environments_from_projects"`
 
+	// RunnersFromProjects TODO
+	RunnersFromProjects struct {
+		OnInit          bool `default:"true" yaml:"on_init"`
+		Scheduled       bool `default:"true" yaml:"scheduled"`
+		IntervalSeconds int  `default:"1800" validate:"gte=1" yaml:"interval_seconds"`
+	} `yaml:"runners_from_projects"`
+
 	// RefsFromProjects configures the fetching of refs (branches, tags, MRs) for projects.
 	RefsFromProjects struct {
 		OnInit          bool `default:"true" yaml:"on_init"`                          // OnInit determines whether refs should be fetched once at startup.
@@ -160,6 +167,13 @@ type GarbageCollect struct {
 		IntervalSeconds int  `default:"14400" validate:"gte=1" yaml:"interval_seconds"` // 4 hours
 	} `yaml:"environments"`
 
+	// Runners TODO
+	Runners struct {
+		OnInit          bool `default:"false" yaml:"on_init"`
+		Scheduled       bool `default:"true" yaml:"scheduled"`
+		IntervalSeconds int  `default:"14400" validate:"gte=1" yaml:"interval_seconds"`
+	} `yaml:"runners"`
+
 	// Refs configures cleanup behavior related to Git references (branches, tags, etc).
 	Refs struct {
 		OnInit          bool `default:"false" yaml:"on_init"`

pkg/config/project.go

@@ -21,6 +21,7 @@ type ProjectParameters struct {
 // such as environments, refs (branches, tags, MRs), and pipelines.
 type ProjectPull struct {
 	Environments ProjectPullEnvironments `yaml:"environments"`
+	Runners      ProjectPullRunners      `yaml:"runners"`
 	Refs         ProjectPullRefs         `yaml:"refs"`
 	Pipeline     ProjectPullPipeline     `yaml:"pipeline"`
 }
@@ -40,6 +41,13 @@ type ProjectPullEnvironments struct {
 	ExcludeStopped bool `default:"true" yaml:"exclude_stopped"`
 }
 
+// ProjectPullRunners configures if and how runners are pulled for a project.
+type ProjectPullRunners struct {
+	Enabled        bool   `default:"true" yaml:"enabled"`
+	Regexp         string `default:".*" yaml:"regexp"`
+	ExcludeStopped bool   `default:"false" yaml:"exclude_stopped"`
+}
+
 // ProjectPullRefs contains configuration for pulling refs: branches, tags, and merge requests.
 type ProjectPullRefs struct {
 	Branches      ProjectPullRefsBranches      `yaml:"branches"`

pkg/controller/collectors.go

@@ -1,6 +1,8 @@
 package controller
 
-import "github.com/prometheus/client_golang/prometheus"
+import (
+	"github.com/prometheus/client_golang/prometheus"
+)
 
 // Commonly used label sets for Prometheus metrics in this application.
 // These labels help categorize and filter metrics for better observability.
@@ -39,6 +41,12 @@ var (
 		"created", "waiting_for_resource", "preparing", "pending", "running",
 		"success", "failed", "canceled", "skipped", "manual", "scheduled", "error", "success_with_warnings",
 	}
+
+	// runnerLabels defines labels for metrics related to runner deploy.
+	runnerLabels = []string{
+		"project", "runner_description", "runner_name", "runner_id", "is_shared", "runner_type", "runner_projects",
+		"online", "tag_list", "active", "status", "runner_groups",
+	}
 )
 
 // NewInternalCollectorCurrentlyQueuedTasksCount creates and returns a new Prometheus GaugeVec metric collector
@@ -71,6 +79,21 @@ func NewInternalCollectorEnvironmentsCount() prometheus.Collector {
 	)
 }
 
+// NewInternalCollectorRunnersCount returns a new Prometheus gauge collector
+// for the metric "gcpe_runners_count" which tracks the total number of GitLab runners
+// currently being exported by the application.
+//
+// This metric has no labels, representing a simple numeric gauge.
+func NewInternalCollectorRunnersCount() prometheus.Collector {
+	return prometheus.NewGaugeVec(
+		prometheus.GaugeOpts{
+			Name: "gcpe_runners_count",
+			Help: "Number of GitLab runners being exported",
+		},
+		[]string{}, // no labels for this metric
+	)
+}
+
 // NewInternalCollectorExecutedTasksCount returns a new Prometheus gauge collector
 // for the metric "gcpe_executed_tasks_count" which tracks the total number of tasks
 // that have been executed by the system.
@@ -534,6 +557,21 @@ func NewCollectorRunCount() prometheus.Collector {
 	)
 }
 
+// NewCollectorRunners returns a new Prometheus gauge collector for the
+// metric "gitlab_ci_runners". This metric reports information about your runners.
+//
+// The labels include the default set of labels plus an additional "runnerLabels" label
+// and "runnnerInformationLabels" that describes the runners state.
+func NewCollectorRunners() prometheus.Collector {
+	return prometheus.NewGaugeVec(
+		prometheus.GaugeOpts{
+			Name: "gitlab_ci_runners",
+			Help: "Status of your runners",
+		},
+		runnerLabels,
+	)
+}
+
 // NewCollectorTestReportTotalTime returns a new Prometheus gauge collector for the
 // metric "gitlab_ci_pipeline_test_report_total_time". This metric tracks the total
 // duration, in seconds, of all tests executed in the most recently finished pipeline.

pkg/controller/controller.go

@@ -94,6 +94,7 @@ func (c *Controller) registerTasks() {
 		schemas.TaskTypeGarbageCollectMetrics:        c.TaskHandlerGarbageCollectMetrics,
 		schemas.TaskTypeGarbageCollectProjects:       c.TaskHandlerGarbageCollectProjects,
 		schemas.TaskTypeGarbageCollectRefs:           c.TaskHandlerGarbageCollectRefs,
+		schemas.TaskTypeGarbageCollectRunners:        c.TaskHandlerGarbageCollectRunners,
 		schemas.TaskTypePullEnvironmentMetrics:       c.TaskHandlerPullEnvironmentMetrics,
 		schemas.TaskTypePullEnvironmentsFromProject:  c.TaskHandlerPullEnvironmentsFromProject,
 		schemas.TaskTypePullEnvironmentsFromProjects: c.TaskHandlerPullEnvironmentsFromProjects,
@@ -104,6 +105,9 @@ func (c *Controller) registerTasks() {
 		schemas.TaskTypePullRefMetrics:               c.TaskHandlerPullRefMetrics,
 		schemas.TaskTypePullRefsFromProject:          c.TaskHandlerPullRefsFromProject,
 		schemas.TaskTypePullRefsFromProjects:         c.TaskHandlerPullRefsFromProjects,
+		schemas.TaskTypePullRunnersMetrics:           c.TaskHandlerPullRunnerMetrics,
+		schemas.TaskTypePullRunnersFromProject:       c.TaskHandlerPullRunnersFromProject,
+		schemas.TaskTypePullRunnersFromProjects:      c.TaskHandlerPullRunnersFromProjects,
 	} {
 		_, _ = c.TaskController.TaskMap.Register(string(n), &taskq.TaskConfig{
 			Handler:    h,

pkg/controller/garbage_collector.go

@@ -2,6 +2,7 @@ package controller
 
 import (
 	"context"
+	"fmt"
 	"reflect"
 	"regexp"
 
@@ -279,6 +280,115 @@ func (c *Controller) GarbageCollectRefs(ctx context.Context) error {
 	return nil
 }
 
+// GarbageCollectRunners cleans up stored runners that are no longer valid or configured.
+func (c *Controller) GarbageCollectRunners(ctx context.Context) error {
+	// Log the start and end of the garbage collection process
+	log.Info("starting 'runners' garbage collection")
+	defer log.Info("ending 'runners' garbage collection")
+
+	// Retrieve all Runners currently stored
+	storedRunners, err := c.Store.Runners(ctx)
+	if err != nil {
+		return err
+	}
+
+	// Map to keep track of projects which have runners that need refreshing
+	runnerProjects := make(map[schemas.Project]bool)
+
+	// Iterate over each stored runner
+	for _, runner := range storedRunners {
+		// Create a Project object from the runner's project name
+		p := schemas.NewProject(runner.ProjectName)
+
+		// Check if the associated project still exists in the store
+		projectExists, err := c.Store.ProjectExists(ctx, p.Key())
+		if err != nil {
+			return err
+		}
+
+		// If the project no longer exists, delete the runner and continue to next
+		if !projectExists {
+			if err = deleteRunner(ctx, c.Store, runner, "non-existent-project"); err != nil {
+				return err
+			}
+			continue
+		}
+
+		// Retrieve the latest project data from the store
+		if err = c.Store.GetProject(ctx, &p); err != nil {
+			return err
+		}
+
+		// If runner pulling is disabled for this project, delete the runner
+		if !p.Pull.Runners.Enabled {
+			if err = deleteRunner(ctx, c.Store, runner, "project-pull-runners-disabled"); err != nil {
+				return err
+			}
+			continue
+		}
+
+		// Mark this project to refresh its runners from the GitLab API later
+		runnerProjects[p] = true
+
+		// Use the project's configured regex to check if this runner should be kept
+		re := regexp.MustCompile(p.Pull.Runners.Regexp)
+		if !re.MatchString(runner.Description) {
+			if err = deleteRunner(ctx, c.Store, runner, "runner-not-in-regexp"); err != nil {
+				return err
+			}
+			continue
+		}
+
+		// If the environment's OutputSparseStatusMetrics setting differs from the project's,
+		// update the environment and save it back to the store
+		if runner.OutputSparseStatusMetrics != p.OutputSparseStatusMetrics {
+			runner.OutputSparseStatusMetrics = p.OutputSparseStatusMetrics
+
+			if err = c.Store.SetRunner(ctx, runner); err != nil {
+				return err
+			}
+
+			log.WithFields(log.Fields{
+				"project-name": runner.ProjectName,
+				"runner-name":  runner.Name,
+			}).Info("updated runner configuration to match associated project")
+		}
+	}
+
+	// Prepare a map to hold runners refreshed from the GitLab API
+	existingRunners := make(schemas.Runners)
+
+	// For each project with tracked runners, fetch runners from GitLab API
+	for p := range runnerProjects {
+		projectRunners, err := c.Gitlab.GetProjectRunners(ctx, p)
+		if err != nil {
+			return err
+		}
+
+		// Merge fetched runners into the existingRunners map
+		if err = mergo.Merge(&existingRunners, projectRunners); err != nil {
+			return err
+		}
+	}
+
+	// Reload the stored runners after possible updates
+	storedRunners, err = c.Store.Runners(ctx)
+	if err != nil {
+		return err
+	}
+
+	// Delete runners from the store that do not exist anymore in the API data
+	for k, runner := range storedRunners {
+		if _, exists := existingRunners[k]; !exists {
+			if err = deleteRunner(ctx, c.Store, runner, "non-existent-runner"); err != nil {
+				return err
+			}
+		}
+	}
+
+	return nil
+}
+
 // GarbageCollectMetrics performs cleanup of obsolete or invalid metrics in the store.
 // It ensures metrics linked to non-existent projects, refs, or environments are removed,
 // and also respects project-level settings that may disable certain metrics.
@@ -304,6 +414,13 @@ func (c *Controller) GarbageCollectMetrics(ctx context.Context) error {
 		return err
 	}
 
+	// TODO: This function must be checked (Runner metrics implementation)
+	storedRunners, err := c.Store.Runners(ctx)
+	if err != nil {
+		return err
+	}
+	fmt.Println("Stored Runners Metrics:", storedRunners)
+
 	storedRefs, err := c.Store.Refs(ctx)
 	if err != nil {
 		return err
@@ -404,6 +521,12 @@ func (c *Controller) GarbageCollectMetrics(ctx context.Context) error {
 				// no action for other kinds here
 			}
 		}
+		// TODO: Handle metrics related to Runner
+		/**
+		switch m.Kind {
+				case schemas.MetricKindRunner
+		}
+		*/
 
 		// Handle metrics related to an Environment.
 		if metricLabelEnvironmentExists {
@@ -469,6 +592,23 @@ func deleteEnv(ctx context.Context, s store.Store, env schemas.Environment, reas
 	return
 }
 
+// deleteRunner removes the specified runner from the store and logs the deletion reason.
+// It takes a context, the store interface, the runner to delete, and a reason string.
+// If deletion fails, it returns the error to the caller.
+func deleteRunner(ctx context.Context, s store.Store, runner schemas.Runner, reason string) (err error) {
+	if err = s.DelRunner(ctx, runner.Key()); err != nil {
+		return
+	}
+
+	log.WithFields(log.Fields{
+		"project-name": runner.ProjectName,
+		"runner-name":  runner.Name,
+		"reason":       reason,
+	}).Info("deleted runner from the store")
+
+	return
+}
+
 // deleteRef removes the specified ref from the store and logs the deletion reason.
 // It takes a context, the store interface, the ref to delete, and a reason string.
 // If deletion fails, it returns the error to the caller.

pkg/controller/metrics.go

@@ -28,6 +28,7 @@ type Registry struct {
 		MetricsCount               prometheus.Collector // Number of exported metrics.
 		ProjectsCount              prometheus.Collector // Total number of GitLab projects tracked.
 		RefsCount                  prometheus.Collector // Total number of Git refs (branches, tags, MRs).
+		RunnersCount               prometheus.Collector // Total number of Runners exported.
 	}
 
 	// Collectors maps each MetricKind to its Prometheus collector.
@@ -80,6 +81,7 @@ func NewRegistry(ctx context.Context) *Registry {
 			schemas.MetricKindTestSuiteErrorCount:                  NewCollectorTestSuiteErrorCount(),
 			schemas.MetricKindTestCaseExecutionTime:                NewCollectorTestCaseExecutionTime(),
 			schemas.MetricKindTestCaseStatus:                       NewCollectorTestCaseStatus(),
+			schemas.MetricKindRunner:                               NewCollectorRunners(),
 		},
 	}
 
@@ -109,6 +111,7 @@ func (r *Registry) RegisterInternalCollectors() {
 	r.InternalCollectors.MetricsCount = NewInternalCollectorMetricsCount()                             // Number of metrics exported
 	r.InternalCollectors.ProjectsCount = NewInternalCollectorProjectsCount()                           // Number of tracked projects
 	r.InternalCollectors.RefsCount = NewInternalCollectorRefsCount()                                   // Number of Git refs (branches, tags, etc.)
+	r.InternalCollectors.RunnersCount = NewInternalCollectorRunnersCount()                             // Number of Runners exported
 
 	// Register all initialized internal collectors with the Prometheus registry.
 	// The underscore `_` ignores any error returned by Register (e.g., if already registered).
@@ -121,6 +124,7 @@ func (r *Registry) RegisterInternalCollectors() {
 	_ = r.Register(r.InternalCollectors.MetricsCount)
 	_ = r.Register(r.InternalCollectors.ProjectsCount)
 	_ = r.Register(r.InternalCollectors.RefsCount)
+	_ = r.Register(r.InternalCollectors.RunnersCount)
 }
 
 // ExportInternalMetrics gathers internal statistics from the store and GitLab client,
@@ -133,6 +137,7 @@ func (r *Registry) ExportInternalMetrics(ctx context.Context, g *gitlab.Client,
 		metricsCount         int64  // Number of stored/exported metrics
 		projectsCount        int64  // Number of projects tracked
 		refsCount            int64  // Number of Git references (branches/tags)
+		runnersCount         int64  // Number of Runners exported
 	)
 
 	// Retrieve the number of currently queued tasks from the store
@@ -171,6 +176,11 @@ func (r *Registry) ExportInternalMetrics(ctx context.Context, g *gitlab.Client,
 		return
 	}
 
+	runnersCount, err = s.RunnersCount(ctx)
+	if err != nil {
+		return
+	}
+
 	// Set Prometheus gauge values for each internal metric.
 	// All collectors are asserted as GaugeVec and updated with empty labels.
 	r.InternalCollectors.CurrentlyQueuedTasksCount.(*prometheus.GaugeVec).With(prometheus.Labels{}).Set(float64(currentlyQueuedTasks))
@@ -182,6 +192,7 @@ func (r *Registry) ExportInternalMetrics(ctx context.Context, g *gitlab.Client,
 	r.InternalCollectors.MetricsCount.(*prometheus.GaugeVec).With(prometheus.Labels{}).Set(float64(metricsCount))
 	r.InternalCollectors.ProjectsCount.(*prometheus.GaugeVec).With(prometheus.Labels{}).Set(float64(projectsCount))
 	r.InternalCollectors.RefsCount.(*prometheus.GaugeVec).With(prometheus.Labels{}).Set(float64(refsCount))
+	r.InternalCollectors.RunnersCount.(*prometheus.GaugeVec).With(prometheus.Labels{}).Set(float64(runnersCount))
 
 	return
 }