Your advanced code editor is loading.

Please wait a moment.

#editor-loading { display: none; }

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. */

package main

import ( “bytes” “fmt” “os” “sort” “strings” “text/template” “time”

flag "github.com/spf13/pflag" "gopkg.in/yaml.v2"

"k8s.io/component-base/metrics"

)

var ( GOROOT string = os.Getenv(“GOROOT”) GOOS string = os.Getenv(“GOOS”) KUBE_ROOT string = os.Getenv(“KUBE_ROOT”) funcMap = template.FuncMap{ “ToLower”: strings.ToLower, } )

const ( templ = `— title: Kubernetes Metrics Reference content_type: reference auto_generated: true description: >-

Details of the metric data that Kubernetes components export.

Metrics (v{{.GeneratedVersion}})

This page details the metrics that different Kubernetes components export. You can query the metrics endpoint for these components using an HTTP scrape, and fetch the current metrics data in Prometheus format.

List of Stable Kubernetes Metrics

Stable metrics observe strict API contracts and no labels can be added or removed from stable metrics during their lifetime.

Stability Level:{{- $metric.StabilityLevel -}}
Type: {{- $metric.Type -}}
Labels:{{range $label := $metric.Labels}}{{- $label -}}{{- end -}}
Const Labels:{{range $key, $value := $metric.ConstLabels}}{{$key}}:{{$value}}{{- end -}}
Deprecated Versions:{{- $metric.DeprecatedVersion -}}

List of Beta Kubernetes Metrics

Beta metrics observe a looser API contract than its stable counterparts. No labels can be removed from beta metrics during their lifetime, however, labels can be added while the metric is in the beta stage. This offers the assurance that beta metrics will honor existing dashboards and alerts, while allowing for amendments in the future.

Stability Level:{{- $metric.StabilityLevel -}}
Type: {{- $metric.Type -}}
Labels:{{range $label := $metric.Labels}}{{- $label -}}{{- end -}}
Const Labels:{{range $key, $value := $metric.ConstLabels}}{{$key}}:{{$value}}{{- end -}}
Deprecated Versions:{{- $metric.DeprecatedVersion -}}

List of Alpha Kubernetes Metrics

Alpha metrics do not have any API guarantees. These metrics must be used at your own risk, subsequent versions of Kubernetes may remove these metrics altogether, or mutate the API in such a way that breaks existing dashboards and alerts.

Stability Level:{{- $metric.StabilityLevel -}}
Type: {{- $metric.Type -}}
Labels:{{range $label := $metric.Labels}}{{- $label -}}{{- end -}}
Const Labels:{{range $key, $value := $metric.ConstLabels}}{{$key}}:{{$value}}{{- end -}}
Deprecated Versions:{{- $metric.DeprecatedVersion -}}

` )

type templateData struct { AlphaMetrics []metric BetaMetrics []metric StableMetrics []metric GeneratedDate time.Time GeneratedVersion string }

func main() { var major string var minor string flag.StringVar(&major, “major”, “”, “k8s major version”) flag.StringVar(&minor, “minor”, “”, “k8s minor version”) flag.Parse() println(major, minor) dat, err := os.ReadFile(“test/instrumentation/documentation/documentation-list.yaml”) if err == nil { var parsedMetrics []metric err = yaml.Unmarshal(dat, &parsedMetrics) if err != nil { println(“err”, err) } sort.Sort(byFQName(parsedMetrics)) t := template.New(“t”).Funcs(funcMap) t, err := t.Parse(templ) if err != nil { println(“err”, err) } var tpl bytes.Buffer for i, m := range parsedMetrics { m.Help = strings.Join(strings.Split(m.Help, “\n”), “, “) _ = m.BuildFQName() // ignore golint error parsedMetrics[i] = m } sortedMetrics := byStabilityLevel(parsedMetrics) data := templateData{ AlphaMetrics: sortedMetrics[“ALPHA”], BetaMetrics: sortedMetrics[“BETA”], StableMetrics: sortedMetrics[“STABLE”], GeneratedDate: time.Now(), GeneratedVersion: fmt.Sprintf(“%v.%v”, major, parseMinor(minor)), } err = t.Execute(&tpl, data) if err != nil { println(“err”, err) } fmt.Print(tpl.String()) } else { fmt.Fprintf(os.Stderr, “%s\n”, err) }

}

type metric struct { Name string yaml:"name" json:"name" Subsystem string yaml:"subsystem,omitempty" json:"subsystem,omitempty" Namespace string yaml:"namespace,omitempty" json:"namespace,omitempty" Help string yaml:"help,omitempty" json:"help,omitempty" Type string yaml:"type,omitempty" json:"type,omitempty" DeprecatedVersion string yaml:"deprecatedVersion,omitempty" json:"deprecatedVersion,omitempty" StabilityLevel string yaml:"stabilityLevel,omitempty" json:"stabilityLevel,omitempty" Labels []string yaml:"labels,omitempty" json:"labels,omitempty" Buckets []float64 yaml:"buckets,omitempty" json:"buckets,omitempty" Objectives map[float64]float64 yaml:"objectives,omitempty" json:"objectives,omitempty" AgeBuckets uint32 yaml:"ageBuckets,omitempty" json:"ageBuckets,omitempty" BufCap uint32 yaml:"bufCap,omitempty" json:"bufCap,omitempty" MaxAge int64 yaml:"maxAge,omitempty" json:"maxAge,omitempty" ConstLabels map[string]string yaml:"constLabels,omitempty" json:"constLabels,omitempty" }

func (m metric) BuildFQName() string { return metrics.BuildFQName(m.Namespace, m.Subsystem, m.Name) }

type byFQName []metric

func (ms byFQName) Len() int { return len(ms) } func (ms byFQName) Less(i, j int) bool { if ms[i].StabilityLevel < ms[j].StabilityLevel { return true } else if ms[i].StabilityLevel > ms[j].StabilityLevel { return false } return ms[i].BuildFQName() < ms[j].BuildFQName() } func (ms byFQName) Swap(i, j int) { ms[i], ms[j] = ms[j], ms[i] }

func byStabilityLevel(ms []metric) map[string][]metric { res := map[string][]metric{} for _, m := range ms { if _, ok := res[m.StabilityLevel]; !ok { res[m.StabilityLevel] = []metric{} } res[m.StabilityLevel] = append(res[m.StabilityLevel], m) } return res }

func parseMinor(m string) string { return strings.Trim(m, +) }

Explanation

This code generates a metrics documentation page for Kubernetes. It reads a YAML file containing metrics definitions, parses them, and then uses Go templates to create a well-structured HTML document.

Here’s a breakdown of the key components and their functionalities:

1. Parsing Metrics from YAML:

documentation-list.yaml: This file contains definitions of all Kubernetes metrics.
yaml.Unmarshal: Parses the YAML data into a slice of metric structs.
sort.Sort: Sorts the parsed metrics based on their stability level and name (using the byFQName custom sort implementation).

2. Data Preparation:

byStabilityLevel: Organizes the sorted metrics into a map based on their stability level (“ALPHA”, “BETA”, “STABLE”).
templateData: A struct holding all the data needed for the template: sorted metrics, current date and time, and the Kubernetes version.
metric: A struct representing a single metric definition, containing fields like name, subsystem, namespace, help text, type, stability level, labels, and deprecated versions.
BuildFQName: Constructs the fully qualified name (FQN) of a metric from its namespace, subsystem, and name.

3. Generating HTML using Templates:

template.New and template.Parse: Creates and parses the Go template based on the templ string, which defines the HTML structure.
template.FuncMap: Defines functions available within the template, in this case, ToLower for converting strings to lowercase.
template.Execute: Executes the parsed template using the templateData to produce the final HTML output.

4. Output:

fmt.Print: Prints the generated HTML to the console.

Overall, this code demonstrates a common pattern in documentation generation:

Data extraction: Reading and parsing data from a source file.
Data manipulation: Sorting, filtering, and organizing data into a suitable structure for templating.
Templating: Generating structured output using a template language.

This specific implementation focuses on Kubernetes metrics documentation, but the general principles can be applied to generate various kinds of documentation from different data sources.

Your advanced code editor is loading.

Please wait a moment.

Explanation

Graph

Symbols

We couldn't identify any entrypoints. If you believe this to be incorrect then please contact support.