Skip to content

docs: sync configuration guide with codebase #201

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Nachiket-Roy wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: sync configuration guide with codebase #201

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fe66931
docs: sync configuration guide with codebase
Nachiket-Roy Jul 12, 2026
8b294e1
docs: update default monitor staleness to 500ms and fix markdownlint
Nachiket-Roy Jul 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 106 additions & 10 deletions docs/kepler/usage/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,14 @@ You can configure Kepler by passing flags when starting the service. The followi
| `--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

Expand Down Expand Up @@ -84,14 +92,20 @@ log:

monitor:
interval: 5s # Monitor refresh interval (default: 5s)
staleness: 1000ms # Duration after which data is considered stale (default: 1000ms)
staleness: 500ms # Duration after which data is considered stale (default: 500ms)
Comment thread
sunya-ch marked this conversation as resolved.
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

Expand All @@ -101,8 +115,7 @@ exporter:
prometheus: # prometheus exporter related config
enabled: true
debugCollectors:
- go
- process
- go # default is only ["go"]
metricsLevel:
- node
- process
Expand All @@ -112,7 +125,7 @@ exporter:

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

web:
configFile: "" # Path to TLS server config file
Expand All @@ -123,12 +136,33 @@ 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
zones: [] # Zones to be enabled, empty enables all default zones
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
Expand Down Expand Up @@ -156,14 +190,14 @@ log:
```yaml
monitor:
interval: 5s
staleness: 1000ms
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.
- **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.

Expand All @@ -179,6 +213,18 @@ host:

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

### 💻 CPU Configuration

```yaml
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

```yaml
Expand Down Expand Up @@ -269,6 +315,9 @@ 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)
Expand All @@ -284,21 +333,68 @@ kube:
- 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

```yaml
dev:
fake-cpu-meter:
enabled: false
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
- `enabled`: Set to `true` to enable fake CPU meter (deprecated)
- `zones`: Specific zones to enable, empty enables all

### 🧪 Experimental Configuration

```yaml
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`
Expand Down
4 changes: 2 additions & 2 deletions docs/kepler/usage/configuration.zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ log:

monitor:
interval: 5s # 监控刷新间隔 (默认: 5s)
staleness: 1000ms # 数据被认为过时的持续时间 (默认: 1000ms)
staleness: 500ms # 数据被认为过时的持续时间 (默认: 500ms)
maxTerminated: 500 # 在内存中保存已终止工作负载的最大数量 (默认: 500)
minTerminatedEnergyThreshold: 10 # 已终止工作负载的最低能量阈值 (默认: 10)

Expand Down Expand Up @@ -159,7 +159,7 @@ log:
```yaml
monitor:
interval: 5s
staleness: 1000ms
staleness: 500ms
maxTerminated: 500
minTerminatedEnergyThreshold: 10
```
Expand Down
Loading