-
Notifications
You must be signed in to change notification settings - Fork 2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
b143fdf
commit 57c5811
Showing
1 changed file
with
85 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,85 @@ | ||
# Kube-State-Metrics - Validate stable metrics Proposal | ||
|
||
--- | ||
|
||
Author: CatherineF-dev@ | ||
|
||
Date: 1. Jan 2024 | ||
|
||
--- | ||
|
||
## Glossary | ||
|
||
* STABLE metrics: it's same to kubernetes/kubernetes BETA metrics. It does | ||
not allow breaking changes which break metrics queries. For example, changing | ||
label name is not allowed. | ||
|
||
* Experimental metrics: it's same to kubernetes/kubernetes ALPHA metrics. It | ||
allows breaking changes. For example, it allows changing label name. | ||
|
||
## Problem Statement | ||
|
||
Broken stable metrics bring overhead for down-stream users to migrate metrics | ||
queries. | ||
|
||
## Goal | ||
|
||
The goal of this proposal is guaranteeing these for stable metrics: | ||
|
||
1. metric name not changed | ||
|
||
2. metric type not changed | ||
|
||
3. old metric labels is a subset of new metric labels | ||
|
||
## Status Quo | ||
|
||
Kubernetes/kubernetes has implemented stable metrics framework. It can not be | ||
used in KSM repo directly, because kubernetes/kubernetes metrics are defined | ||
using prometheus libraries while KSM metrics are defined using custom functions. | ||
|
||
## Proposal - validate stable metrics using static analysis | ||
|
||
1. Add a new funciton NewFamilyGeneratorWithStabilityV2 which has labels in its | ||
parameter. It's easier for static analysis in step 2. | ||
|
||
2. Adapt stable metrics framework <https://github.com/kubernetes/kubernetes/tree/master/test/instrumentation> | ||
into kube-state-metrics repo. | ||
|
||
2.1 Find stable metrics definitions. It finds all function calls with name NewFamilyGeneratorWithStabilityV2 where fourth paraemeter (StabilityLevel) is stable | ||
|
||
2.2 Extract metric name, labels, help, stability level from 2.1 | ||
|
||
``` | ||
func createPodInitContainerStatusRestartsTotalFamilyGenerator() generator.FamilyGenerator { | ||
return *generator.NewFamilyGeneratorWithStabilityV2( | ||
"kube_pod_init_container_status_restarts_total", | ||
"The number of restarts for the init container.", | ||
metric.Counter, basemetrics.STABLE, | ||
"", | ||
[]string{"container"}, # labels | ||
... | ||
} | ||
``` | ||
|
||
2.3 Export all stable metrics, with format | ||
|
||
``` | ||
- name: kube_pod_init_container_status_restarts_total | ||
help: The number of restarts for the init container. | ||
type: Counter | ||
stabilityLevel: STABLE | ||
labels: | ||
- container | ||
``` | ||
|
||
2.4 Compare output in 2.3 with expected results tests/stablemetrics/testdata/test-stable-metrics-list.yaml | ||
|
||
## Alternatives | ||
|
||
### Validate exposed metrics in runtime | ||
|
||
Generated metrics are not complete. Some metrics are exposed when certain conditions | ||
are met. | ||
|
||
## FAQ / Follow up improvements |