From 6e831e187ed76dd6318a3fd23378a2dd91ab6c01 Mon Sep 17 00:00:00 2001 From: Augustin Husson Date: Mon, 28 Oct 2024 08:50:30 +0100 Subject: [PATCH] complete documentation about how to configure the metrics_usage Signed-off-by: Augustin Husson --- README.md | 16 +++++ config/collector.go | 29 ++++++--- docs/configuration.md | 136 ++++++++++++++++++++++++++++++++++++++++ source/metric/metric.go | 2 +- source/rules/rules.go | 4 +- 5 files changed, 176 insertions(+), 11 deletions(-) create mode 100644 docs/configuration.md diff --git a/README.md b/README.md index f9ae714..6981b23 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,10 @@ This collector gets the list of metrics for a defined period of time. This list #### Configuration +See the doc for the complete configuration [here](./docs/configuration.md#metric_collector-config) + +Example: + ```yaml metric_collector: enable: true @@ -87,6 +91,10 @@ This collector gets the Prometheus Rules Group using the HTTP API. Then it extra #### Configuration +See the doc for the complete configuration [here](./docs/configuration.md#rules_collector-config) + +Example: + ```yaml rules_collector: enable: true @@ -100,6 +108,10 @@ This collector gets the list of dashboards using the HTTP API of Perses. Then it #### Configuration +See the doc for the complete configuration [here](./docs/configuration.md#perses_collector-config) + +Example: + ```yaml perses_collector: enable: true @@ -114,6 +126,10 @@ Extraction from variable still needs to be done. #### Configuration +See the doc for the complete configuration [here](./docs/configuration.md#grafana_collector-config) + +Example: + ```yaml grafana_collector: enable: true diff --git a/config/collector.go b/config/collector.go index 1ec52c8..38ed236 100644 --- a/config/collector.go +++ b/config/collector.go @@ -51,9 +51,9 @@ func NewHTTPClient(cfg HTTPClient) (*http.Client, error) { } type MetricCollector struct { - Enable bool `yaml:"enable"` - Period model.Duration `yaml:"period,omitempty"` - PrometheusClient HTTPClient `yaml:"http_client"` + Enable bool `yaml:"enable"` + Period model.Duration `yaml:"period,omitempty"` + HTTPClient HTTPClient `yaml:"http_client"` } func (c *MetricCollector) Verify() error { @@ -63,16 +63,16 @@ func (c *MetricCollector) Verify() error { if c.Period <= 0 { c.Period = model.Duration(defaultMetricCollectorPeriodDuration) } - if c.PrometheusClient.URL == nil { + if c.HTTPClient.URL == nil { return fmt.Errorf("missing Prometheus URL for the metric collector") } return nil } type RulesCollector struct { - Enable bool `yaml:"enable"` - Period model.Duration `yaml:"period,omitempty"` - PrometheusClient HTTPClient `yaml:"http_client"` + Enable bool `yaml:"enable"` + Period model.Duration `yaml:"period,omitempty"` + HTTPClient HTTPClient `yaml:"http_client"` } func (c *RulesCollector) Verify() error { @@ -82,7 +82,7 @@ func (c *RulesCollector) Verify() error { if c.Period <= 0 { c.Period = model.Duration(defaultMetricCollectorPeriodDuration) } - if c.PrometheusClient.URL == nil { + if c.HTTPClient.URL == nil { return fmt.Errorf("missing Prometheus URL for the rules collector") } return nil @@ -112,3 +112,16 @@ type GrafanaCollector struct { Period model.Duration `yaml:"period,omitempty"` HTTPClient HTTPClient `yaml:"http_client"` } + +func (c *GrafanaCollector) Verify() error { + if !c.Enable { + return nil + } + if c.Period <= 0 { + c.Period = model.Duration(defaultMetricCollectorPeriodDuration) + } + if c.HTTPClient.URL == nil { + return fmt.Errorf("missing Rest URL for the perses collector") + } + return nil +} diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..92183a9 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,136 @@ +Configuration +============= + +Metrics-usage is configured via command-line flags and a configuration file + +## Flags available + +```bash + -config string + Path to the yaml configuration file for the api. Configuration can be overridden when using the environment variable + -log.level string + log level. Possible value: panic, fatal, error, warning, info, debug, trace (default "info") + -log.method-trace + include the calling method as a field in the log. Can be useful to see immediately where the log comes from + -pprof + Enable pprof + -web.hide-port + If true, it won t be print on stdout the port listened to receive the HTTP request + -web.listen-address string + The address to listen on for HTTP requests, web interface and telemetry. (default ":8080") + -web.telemetry-path string + Path under which to expose metrics. (default "/metrics") +``` + +Example: + +```bash +metrics-usage --config=./config.yaml --log.method-trace +``` + +## Configuration File + +### Definition + +The file is written in YAML format, defined by the scheme described below. Brackets indicate that a parameter is optional. + +Generic placeholders are defined as follows: + +* ``: a boolean that can take the values `true` or `false` +* ``: a duration matching the regular expression `((([0-9]+)y)?(([0-9]+)w)?(([0-9]+)d)?(([0-9]+)h)?(([0-9]+)m)?(([0-9]+)s)?(([0-9]+)ms)?|0)`, e.g. `1d`, `1h30m`, `5m`, `10s` +* ``: a valid path in the current working directory +* ``: a valid URL path +* ``: an integer value +* ``: a regular string that is a secret, such as a password +* ``: a regular string + +```yaml +[ metric_collector: ] +[ rules_collector: ] +[ perses_collector: ] +[ grafana_collector: ] +``` + +### Metric_Collector Config + +```yaml +[ enable: | default=false ] +[ period: | default="12h" ] +http_client: +``` + +### Rules_Collector Config + +```yaml +[ enable: | default=false ] +[ period: | default="12h" ] +http_client: +``` + +### Perses_Collector Config + +```yaml +[ enable: | default=false ] +[ period: | default="12h" ] +http_client: + url: + [ tls_config: ] + auth: + basic_auth: + username: + [ password: ] + [ password_file: ] + [ oauth: < Oauth Config> ] +``` + +### Grafana_Collector Config + +```yaml +[ enable: | default=false ] +[ period: | default="12h" ] +http_client: < HTTPClient config> +``` + +### TLS Config + +```yaml +# CA certificate to validate API server certificate with. At most one of ca and ca_file is allowed. +[ ca: ] +[ caFile: ] + +# Certificate and key for client cert authentication to the server. +# At most one of cert and cert_file is allowed. +# At most one of key and key_file is allowed. +[ cert: ] +[ certFile: ] +[ key: ] +[ keyFile: ] + +# ServerName extension to indicate the name of the server. +# https://tools.ietf.org/html/rfc4366#section-3.1 +[ serverName: ] + +# Disable validation of the server certificate. +[ insecureSkipVerify: | default = false ] +``` + +### HTTPClient Config + +```yaml +url: +[ oauth: < Oauth Config> ] +[ tls_config: < TLS Config> ] +``` + +### Oauth Config + +```yaml +# ClientID is the application's ID. +client_id: + +# ClientSecret is the application's secret. +client_secret: + +# TokenURL is the resource server's token endpoint URL. This is a constant specific to each server. +token_url: +``` diff --git a/source/metric/metric.go b/source/metric/metric.go index 66a84ba..4c1df77 100644 --- a/source/metric/metric.go +++ b/source/metric/metric.go @@ -14,7 +14,7 @@ import ( ) func NewCollector(db database.Database, cfg config.MetricCollector) (async.SimpleTask, error) { - promClient, err := prometheus.NewClient(cfg.PrometheusClient) + promClient, err := prometheus.NewClient(cfg.HTTPClient) if err != nil { return nil, err } diff --git a/source/rules/rules.go b/source/rules/rules.go index b3665db..282040b 100644 --- a/source/rules/rules.go +++ b/source/rules/rules.go @@ -14,14 +14,14 @@ import ( ) func NewCollector(db database.Database, cfg config.RulesCollector) (async.SimpleTask, error) { - promClient, err := prometheus.NewClient(cfg.PrometheusClient) + promClient, err := prometheus.NewClient(cfg.HTTPClient) if err != nil { return nil, err } return &rulesCollector{ client: promClient, db: db, - promURL: cfg.PrometheusClient.URL.String(), + promURL: cfg.HTTPClient.URL.String(), }, nil }