Skip to content

⚙️ Kepler Configuration Guide

Kepler supports configuration through both command-line flags and a configuration file. This guide outlines all available configuration options for configuring Kepler.

🛠️ Configuration Methods

Kepler supports two primary methods for configuration:

  1. Command-line flags: For quick adjustments and one-time settings
  2. Configuration file: For persistent and comprehensive configuration

⚡ Tip: Command-line flags take precedence over configuration file settings when both are specified.

🖥️ Command-line Flags

You can configure Kepler by passing flags when starting the service. The following flags are available:

Flag Description Default Values
--config.file Path to YAML configuration file Any valid file path
--log.level Logging level info debug, info, warn, error
--log.format Output format for logs text text, json
--host.sysfs Path to sysfs filesystem /sys Any valid directory path
--host.procfs Path to procfs filesystem /proc Any valid directory path
--monitor.interval Monitor refresh interval 5s Any valid duration
--monitor.max-terminated Maximum number of terminated workloads to keep in memory until exported 500 Negative number indicates unlimited and 0 disables the feature
--web.config-file Path to TLS server config file "" Any valid file path
--web.listen-address Web server listen addresses (can be specified multiple times) :28282 Any valid host:port or :port format
--debug.pprof Enable pprof debugging endpoints false true, false
--exporter.stdout Enable stdout exporter false true, false
--exporter.prometheus Enable Prometheus exporter true true, false
--metrics Metrics levels to export (can be specified multiple times) node,process,container,vm,pod node, process, container, vm, pod
--kube.enable Monitor kubernetes false true, false
--kube.config Path to a kubeconfig file "" Any valid file path
--kube.node-name Name of kubernetes node on which kepler is running "" Any valid node name
--experimental.platform.redfish.enabled Enable experimental Redfish BMC power monitoring false true, false
--experimental.platform.redfish.node-name Node name for experimental Redfish platform power monitoring "" Any valid node name
--experimental.platform.redfish.config-file Path to experimental Redfish BMC configuration file "" Any valid file path
--experimental.hwmon.force-enabled Force hwmon as the power meter, skipping RAPL auto-detection false true, false
--experimental.hwmon.zones Hwmon zone filter (power labels to monitor) (can be specified multiple times) Any valid hwmon zone list
--experimental.gpu.enabled Enable experimental GPU power monitoring false true, false
--experimental.gpu.idle-power GPU idle power in Watts 0 Any positive number
--experimental.gpu.dcgm-endpoint dcgm-exporter metrics endpoint URL for MIG power attribution "" Any valid URL

💡 Examples

# Run with debug logging
kepler --log.level=debug

# Use a different procfs path and JSON logging
kepler --host.procfs=/custom/proc --log.format=json

# Load configuration from file
kepler --config.file=/path/to/config.yaml

# Use custom listen addresses
kepler --web.listen-address=:8080 --web.listen-address=localhost:9090

# Enable stdout exporter and disable Prometheus exporter
kepler --exporter.stdout=true --exporter.prometheus=false

# Enable Kubernetes monitoring with specific kubeconfig and node name
kepler --kube.enable=true --kube.config=/path/to/kubeconfig --kube.node-name=my-node

# Export only node and container level metrics
kepler --metrics=node --metrics=container

# Export only process level metrics
kepler --metrics=process

# Set maximum terminated workloads to 1000
kepler --monitor.max-terminated=1000

# Disable terminated workload tracking
kepler --monitor.max-terminated=0

# Unlimited terminated workload tracking
kepler --monitor.max-terminated=-1

🗂️ Configuration File

Kepler can load configuration from a YAML file. The configuration file offers more extensive options than command-line flags.

🧾 Sample Configuration File

log:
  level: debug  # debug, info, warn, error (default: info)
  format: text  # text or json (default: text)

monitor:
  interval: 5s        # Monitor refresh interval (default: 5s)
  staleness: 500ms    # Duration after which data is considered stale (default: 500ms)
  maxTerminated: 500  # Maximum number of terminated workloads to keep in memory (default: 500)
  minTerminatedEnergyThreshold: 10  # Minimum energy threshold for terminated workloads (default: 10)

host:
  sysfs: /sys   # Path to sysfs filesystem (default: /sys)
  procfs: /proc # Path to procfs filesystem (default: /proc)

cpu:
  # Ordered preference list of CPU power-meter backends. The first backend
  # that initializes successfully and reports zones is used.
  # Built-in backends: rapl, hwmon, fake
  preferredMeters: [rapl, hwmon]

rapl:
  zones: []     # RAPL zones to be enabled, empty enables all default zones

exporter:
  stdout:       # stdout exporter related config
    enabled: false # disabled by default
  prometheus:   # prometheus exporter related config
    enabled: true
    debugCollectors:
      - go      # default is only ["go"]
    metricsLevel:
      - node
      - process
      - container
      - vm
      - pod

debug:          # debug related config
  pprof:        # pprof related config
    enabled: false # disabled by default

web:
  configFile: "" # Path to TLS server config file
  listenAddresses: # Web server listen addresses
    - ":28282"

kube:           # kubernetes related config
  enabled: false    # Enable kubernetes monitoring (default: false)
  config: ""        # Path to kubeconfig file (optional if running in-cluster)
  nodeName: ""      # Name of the kubernetes node (required when enabled)
  podInformer:
    mode: kubelet   # "kubelet" (default) or "apiserver"
    pollInterval: 15s # Poll interval for kubelet mode

# WARN: DO NOT ENABLE THIS IN PRODUCTION - for development/testing only
dev:
  fake-cpu-meter:
    enabled: false # DEPRECATED: set cpu.preferredMeters: ["fake"] instead
    zones: []      # Zones to be enabled, empty enables all default zones

# EXPERIMENTAL FEATURES - These features are experimental and may be unstable
# and are disabled by default
experimental:
  platform:
    redfish:
      enabled: false  # Enable experimental Redfish BMC power monitoring
      configFile: hack/redfish.yaml # Path to Redfish BMC configuration file
      nodeName: ""    # Node name to use (overrides Kubernetes node name and hostname fallback)
      httpTimeout: 5s # HTTP client timeout for BMC requests
  hwmon:
    forceEnabled: false # DEPRECATED: set cpu.preferredMeters: ["hwmon"] instead
    zones: []           # List of zones to enable (default enable all)
    chipRules: []       # User-defined chip pairing rules
  gpu:
    enabled: false      # Enable experimental GPU power monitoring
    idlePower: 0        # GPU idle power in Watts (0 = auto-detect)
    dcgmEndpoint: ""    # dcgm-exporter metrics URL for MIG (auto-discovered if empty)

🧩 Configuration Options in Detail

📝 Logging Configuration

log:
  level: info   # Logging level
  format: text  # Output format
  • level: Controls the verbosity of logging
  • debug: Very verbose, includes detailed operational information
  • info: Standard operational information
  • warn: Only warnings and errors

  • error: Only errors

  • format: Controls the output format of logs

  • text: Human-readable format
  • json: JSON format, suitable for log processing systems

📊 Monitor Configuration

monitor:
  interval: 5s
  staleness: 500ms
  maxTerminated: 500
  minTerminatedEnergyThreshold: 10

  • interval: The monitor's refresh interval. All processes with a lifetime less than this interval will be ignored. Setting to 0s disables monitor refreshes.

  • staleness: Duration after which data computed by the monitor is considered stale and recomputed when requested again. Especially useful when multiple Prometheus instances are scraping Kepler, ensuring they receive the same data within the staleness window. Should be shorter than the monitor interval. Default is 500ms.

  • maxTerminated: Maximum number of terminated workloads (processes, containers, VMs, pods) to keep in memory until the data is exported. This prevents unbounded memory growth in high-churn environments. Set 0 to disable. When the limit is reached, the least power consuming terminated workloads are removed first.

  • minTerminatedEnergyThreshold: Minimum energy consumption threshold (in joules) for terminated workloads to be tracked. Only terminated workloads with energy consumption above this threshold will be included in the tracking. This helps filter out short-lived processes that consume minimal energy. Default is 10 joules.

🗄️ Host Configuration

host:
  sysfs: /sys    # Path to sysfs
  procfs: /proc  # Path to procfs

These settings specify where Kepler should look for system information. In containerized environments, you might need to adjust these paths.

💻 CPU Configuration

cpu:
  preferredMeters: [rapl, hwmon]
  • preferredMeters: An ordered list of backends to probe for monitoring CPU power. Kepler will use the first backend in this list that initializes successfully. Supported backends include:
  • rapl: Running Average Power Limiting (default for Intel/AMD CPUs)
  • hwmon: Hardware monitoring drivers (typically for server board sensors)
  • fake: A fake CPU meter (useful for development/testing when hardware sensors are unavailable)

🔋 RAPL Zones Configuration

rapl:
  zones: []  # RAPL zones to be enabled

Running Average Power Limiting (RAPL) is Intel's power capping mechanism. By default, Kepler enables all available zones. You can restrict to specific zones by listing them.

Example with specific zones:

rapl:
  zones: ["package", "core", "uncore"]

📦 Exporter Configuration

exporter:
  stdout:       # stdout exporter related config
    enabled: false # disabled by default
  prometheus:   # prometheus exporter related config
    enabled: true
    debugCollectors:
      - go
      - process
    metricsLevel:
      - node
      - process
      - container
      - vm
      - pod
  • stdout: Configuration for the stdout exporter

  • enabled: Enable or disable the stdout exporter (default: false)

  • prometheus: Configuration for the Prometheus exporter

  • enabled: Enable or disable the Prometheus exporter (default: true)
  • debugCollectors: List of debug collectors to enable (available: "go", "process")
  • metricsLevel: List of metric levels to expose. Controls the granularity of metrics exported:
    • node: Node-level metrics (system-wide power consumption)
    • process: Process-level metrics (per-process power consumption)
    • container: Container-level metrics (per-container power consumption)
    • vm: Virtual machine-level metrics (per-VM power consumption)
    • pod: Pod-level metrics (per-pod power consumption in Kubernetes)

🐞 Debug Configuration

debug:
  pprof:
    enabled: true
  • pprof: Configuration for pprof debugging
  • enabled: When enabled, this exposes pprof debug endpoints that can be used for profiling Kepler (default: true)

🌐 Web Configuration

web:
  configFile: ""  # Path to TLS server config file
  listenAddresses: # Web server listen addresses
    - ":28282"
  • configFile: Path to a TLS server configuration file for securing Kepler's web endpoints
  • listenAddresses: List of addresses where the web server should listen (default: [":28282"])
  • Supports both host:port format (e.g., "localhost:8080", "0.0.0.0:9090") and port-only format (e.g., ":8080")
  • Multiple addresses can be specified for listening on different interfaces or ports
  • IPv6 addresses are supported using bracket notation (e.g., "[::1]:8080")

Example TLS server configuration file content:

# TLS server configuration
tls_server_config:
  cert_file: /path/to/cert.pem  # Path to the certificate file
  key_file: /path/to/key.pem    # Path to the key file

🐳 Kubernetes Configuration

kube:
  enabled: false    # Enable kubernetes monitoring
  config: ""        # Path to kubeconfig file
  nodeName: ""      # Name of the kubernetes node
  podInformer:
    mode: kubelet   # "kubelet" (default) or "apiserver"
    pollInterval: 15s # Poll interval for kubelet mode
  • enabled: Enable or disable Kubernetes monitoring (default: false)

  • When enabled, Kepler will monitor Kubernetes resources and expose pod level information

  • config: Path to a kubeconfig file (optional)

  • Required when running Kepler outside of a Kubernetes cluster
  • When running inside a cluster, Kepler can use the in-cluster configuration

  • Must be a valid and readable kubeconfig file

  • nodeName: Name of the Kubernetes node on which Kepler is running (required when enabled)

  • This helps Kepler identify which node it's monitoring
  • Must match the actual node name in the Kubernetes cluster

  • Required when enabled is set to true

  • podInformer: Configuration for pod discovery mechanism:

  • mode: The pod informer mode.
    • kubelet (default): Queries local Kubelet endpoints. More lightweight and scale-friendly.
    • apiserver: Queries the Kubernetes API Server directly.
  • pollInterval: Poll interval when using Kubelet mode (default: 15s).

🧑‍🔬 Development Configuration

dev:
  fake-cpu-meter:
    enabled: false # DEPRECATED
    zones: []

⚠️ WARNING: This section is for development and testing only. Do not enable in production.

[!WARNING] dev.fake-cpu-meter.enabled is deprecated. Use cpu.preferredMeters: ["fake"] instead.

  • fake-cpu-meter: When enabled, uses a fake CPU meter instead of real hardware metrics
  • enabled: Set to true to enable fake CPU meter (deprecated)
  • zones: Specific zones to enable, empty enables all

🧪 Experimental Configuration

experimental:
  platform:
    redfish:
      enabled: false
      configFile: hack/redfish.yaml
      nodeName: ""
      httpTimeout: 5s
  hwmon:
    forceEnabled: false # DEPRECATED
    zones: []
    chipRules: []
  gpu:
    enabled: false
    idlePower: 0
    dcgmEndpoint: ""

⚠️ WARNING: Experimental features are subject to change and should not be used in stable production deployments.

  • platform.redfish: Configuration for Redfish BMC platform power metrics
  • enabled: Enable platform power monitoring via Redfish BMC (default: false)
  • configFile: Path to a Redfish configuration file containing BMC credentials
  • nodeName: Node name override for mapping BMC readings to a specific node

  • httpTimeout: HTTP request timeout for BMC queries (default: 5s)

  • hwmon: Configuration for hardware monitor (hwmon) sensor reading

  • forceEnabled: Force hwmon as the active CPU power meter (deprecated, set cpu.preferredMeters: ["hwmon"] instead)
  • zones: Filter specific hwmon zones/power labels to monitor

  • chipRules: Custom rules defining sensor index pairings for voltage/current chips (e.g. mapping in{N} to curr{N})

  • gpu: Configuration for GPU energy monitoring

  • enabled: Enable experimental GPU power exporter (default: false)
  • idlePower: Manual GPU idle power setting in Watts (set positive value if auto-detect fails)
  • dcgmEndpoint: Optional endpoint of a running dcgm-exporter to attribute MIG power

📖 Further Reading

For more details see the config file example in the main Kepler repository at hack/config.yaml

Happy configuring! 🎉

Copyright Contributors to the Kepler's project.

The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see Trademark Usage.