README
¶
This directory contains the regression test for controlling the list of stable metrics
If you add or remove a stable metric, this test will fail and you will need
to update the golden list of tests stored in testdata/. Changes to that file
require review by sig-instrumentation.
To update the list, run
./hack/update-generated-stable-metrics.sh
Add the changed file to your PR, then send for review.
If you want to test the stability framework, you can add metrics to the file in
test/instrumentation/testdata/pkg/kubelet/metrics/metrics.go and run test
verification via:
./test/instrumentation/test-verify.sh
To update the golden test list, you can run:
./test/instrumentation/test-update.sh
To update the list of documented metrics, please run:
./test/instrumentation/update-documentation-metrics.sh
To update the documented list of metrics for k8s/website, please run:
./test/instrumentation/update-documentation.sh
Then you need to copy the output to the appropriate website directory. Please define the directory in which the website repo lives in an env variable like so:
export WEBSITE_ROOT=<path to website root>
And then from the root of the k8s/k8s repository, please run this command:
cp ./test/instrumentation/documentation/documentation.md $WEBSITE_ROOT/content/en/docs/reference/instrumentation/metrics.md
Documentation
¶
Overview ¶
This stand-alone package is utilized for dynamically generating/maintaining a list of metrics; this list is determined by the stability class of the metric. We statically analyze all files in the Kubernetes code base to:
- Determine whether the metric falls into a stability class with stability guarantees.
- Determine the metric's metadata, i.e. the name, labels, type of metric.
- Output (based on the above) the metrics which meet our criteria into a yaml file.
Due to the dynamic nature of how metrics can be written, we only support the subset of metrics which can actually be parsed. If a metric cannot be parsed, it must be delegated to the stability class `Internal`, which will exempt the metric from static analysis.
The entrypoint to this package is defined in a shell script (i.e. stability-utils.sh) which has the logic for feeding file names as arguments into the program. The logic of this program is as follows:
- parse all files fed in, keeping track of:
- the function and struct pointers which correspond to prometheus metric definitions.
- consts/variable we encounter, so that we can use these to resolve values in metric definitions
- then, iterate over the function and struct pointers, resolving attributes to concrete metric values
- then, using our collected and resolved metric definitions, output (depending on the mode):
- a yaml file corresponding to all stable metrics
- a documentation file corresponding to all parseable metrics in the Kubernetes codebase
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
This stand-alone package is utilized for dynamically generating/maintaining documentation on all parseable metrics in the Kubernetes code base.
|
This stand-alone package is utilized for dynamically generating/maintaining documentation on all parseable metrics in the Kubernetes code base. |