metrics

Documentation

Overview

Package metrics provides centralized metric names and registration functions for shell-operator. All metric names use constants to ensure consistency and prevent typos. The {PREFIX} placeholder is replaced by the metrics storage with the appropriate prefix.

Index

• Variables
• func InitMetrics(prefix string)
• func RegisterCommonMetrics(metricStorage metricsstorage.Storage) error
• func RegisterHookMetrics(metricStorage metricsstorage.Storage) error
• func RegisterKubeEventsManagerMetrics(metricStorage metricsstorage.Storage, labels []string) error
• func RegisterOperatorMetrics(metricStorage metricsstorage.Storage, kubeEventManagerLabels []string) error
• func RegisterTaskQueueMetrics(metricStorage metricsstorage.Storage) error
• func ReplacePrefix(metricName, prefix string) string
• type Names
  • func NewNames(prefix string) *Names

Variables

var (
	// ============================================================================
	// Common Metrics
	// ============================================================================
	// LiveTicks is a counter that increases every 10 seconds to indicate shell-operator is alive
	LiveTicks = "{PREFIX}live_ticks"

	// ============================================================================
	// Task Queue Metrics
	// ============================================================================
	// TasksQueueActionDurationSeconds measures task queue operation durations
	TasksQueueActionDurationSeconds = "{PREFIX}tasks_queue_action_duration_seconds"
	// TasksQueueLength shows the current length of the task queue
	TasksQueueLength = "{PREFIX}tasks_queue_length"
	// TasksQueueCompactionOperationsTotal counts compaction operations per hook
	TasksQueueCompactionOperationsTotal = "d8_telemetry_{PREFIX}tasks_queue_compaction_operations_total"
	// TasksQueueCompactionTasksByHook shows the number of tasks in queue for each hook when count exceeds 20. Updated every 10 seconds.
	TasksQueueCompactionTasksByHook = "d8_telemetry_{PREFIX}tasks_queue_compaction_tasks_by_hook"

	// ============================================================================
	// Hook Execution Metrics
	// ============================================================================
	// Kubernetes Bindings
	HookEnableKubernetesBindingsSeconds     = "{PREFIX}hook_enable_kubernetes_bindings_seconds"
	HookEnableKubernetesBindingsErrorsTotal = "{PREFIX}hook_enable_kubernetes_bindings_errors_total"
	HookEnableKubernetesBindingsSuccess     = "{PREFIX}hook_enable_kubernetes_bindings_success"

	// Hook Runtime Metrics
	HookRunSeconds        = "{PREFIX}hook_run_seconds"
	HookRunUserCPUSeconds = "{PREFIX}hook_run_user_cpu_seconds"
	HookRunSysCPUSeconds  = "{PREFIX}hook_run_sys_cpu_seconds"
	HookRunMaxRSSBytes    = "{PREFIX}hook_run_max_rss_bytes"

	// Hook Execution Results
	HookRunErrorsTotal        = "{PREFIX}hook_run_errors_total"
	HookRunAllowedErrorsTotal = "{PREFIX}hook_run_allowed_errors_total"
	HookRunSuccessTotal       = "{PREFIX}hook_run_success_total"

	// Task Queue Wait Time
	TaskWaitInQueueSecondsTotal = "{PREFIX}task_wait_in_queue_seconds_total"

	// ============================================================================
	// Kubernetes Events Manager Metrics
	// ============================================================================
	// KubeSnapshotObjects counts cached objects for particular bindings
	KubeSnapshotObjects = "{PREFIX}kube_snapshot_objects"
	// KubeJqFilterDurationSeconds measures jq filter execution time
	KubeJqFilterDurationSeconds = "{PREFIX}kube_jq_filter_duration_seconds"
	// KubeEventDurationSeconds measures Kubernetes event handling time
	KubeEventDurationSeconds = "{PREFIX}kube_event_duration_seconds"
	// KubernetesClientWatchErrorsTotal counts Kubernetes client watch errors
	KubernetesClientWatchErrorsTotal = "{PREFIX}kubernetes_client_watch_errors_total"
)

Metric name variables organized by functional area. Each variable represents a unique metric name used throughout shell-operator. These variables are initialized with prefix replacement at startup via InitMetrics. InitMetrics is idempotent for the same prefix because the substitution removes the {PREFIX} placeholder on the first call.

Library callers that need a per-instance snapshot of the resolved names should use NewNames(prefix) and pass the returned *Names around explicitly, avoiding the package-level globals altogether.

Functions

func InitMetrics

func InitMetrics(prefix string)

InitMetrics initializes all metric name variables by replacing {PREFIX} placeholders with the provided prefix. This function should be called once at startup before registering any metrics.

func RegisterCommonMetrics

func RegisterCommonMetrics(metricStorage metricsstorage.Storage) error

RegisterCommonMetrics registers base metrics used across shell-operator and addon-operator. These are fundamental metrics that indicate the health and activity of the operator.

func RegisterHookMetrics

func RegisterHookMetrics(metricStorage metricsstorage.Storage) error

RegisterHookMetrics registers all hook-related metrics with the provided storage. This includes metrics for hook execution, Kubernetes bindings, and resource usage. Used specifically by shell-operator's HookManager.

func RegisterKubeEventsManagerMetrics

func RegisterKubeEventsManagerMetrics(metricStorage metricsstorage.Storage, labels []string) error

RegisterKubeEventsManagerMetrics registers metrics for Kubernetes events manager. These metrics monitor Kubernetes API interactions, object caching, and event processing. Used by both shell-operator and addon-operator.

func RegisterOperatorMetrics

func RegisterOperatorMetrics(metricStorage metricsstorage.Storage, kubeEventManagerLabels []string) error

func RegisterTaskQueueMetrics

func RegisterTaskQueueMetrics(metricStorage metricsstorage.Storage) error

RegisterTaskQueueMetrics registers metrics related to task queue operations and performance. Used by both shell-operator and addon-operator to monitor queue health and performance.

func ReplacePrefix

func ReplacePrefix(metricName, prefix string) string

ReplacePrefix replaces the {PREFIX} placeholder in a metric name with the provided prefix. This function is useful for testing or when you need to manually construct metric names with a specific prefix instead of relying on the metrics storage's automatic replacement.

Types

type Names

type Names struct {
	LiveTicks                               string
	TasksQueueActionDurationSeconds         string
	TasksQueueLength                        string
	TasksQueueCompactionOperationsTotal     string
	TasksQueueCompactionTasksByHook         string
	HookEnableKubernetesBindingsSeconds     string
	HookEnableKubernetesBindingsErrorsTotal string
	HookEnableKubernetesBindingsSuccess     string
	HookRunSeconds                          string
	HookRunUserCPUSeconds                   string
	HookRunSysCPUSeconds                    string
	HookRunMaxRSSBytes                      string
	HookRunErrorsTotal                      string
	HookRunAllowedErrorsTotal               string
	HookRunSuccessTotal                     string
	TaskWaitInQueueSecondsTotal             string
	KubeSnapshotObjects                     string
	KubeJqFilterDurationSeconds             string
	KubeEventDurationSeconds                string
	KubernetesClientWatchErrorsTotal        string
}

Names is a per-instance snapshot of every metric name shell-operator emits, with the {PREFIX} placeholder already substituted. Library consumers that embed shell-operator may build one with NewNames(prefix) and reference its fields instead of the package-level variables, which avoids any reliance on the global InitMetrics call having run with a compatible prefix.

func NewNames

func NewNames(prefix string) *Names

NewNames builds a *Names with prefix substituted into every metric template. Calling NewNames does not mutate any package-level state, so multiple instances with different prefixes can coexist when needed.