From b3b669fd9a00d980cb853efa1b8a4912ddeba3bf Mon Sep 17 00:00:00 2001
From: Julien Pivotto <roidelapluie@o11y.eu>
Date: Wed, 12 Jul 2023 22:30:20 +0200
Subject: [PATCH] Add experimental flag and docs

Signed-off-by: Julien Pivotto <roidelapluie@o11y.eu>
---
 cmd/promtool/main.go          | 14 ++++++-
 docs/command-line/promtool.md | 71 +++++++++++++++++++++++++++++++++++
 2 files changed, 84 insertions(+), 1 deletion(-)

diff --git a/cmd/promtool/main.go b/cmd/promtool/main.go
index 2b5ee9aee..da4b8dc79 100644
--- a/cmd/promtool/main.go
+++ b/cmd/promtool/main.go
@@ -92,6 +92,8 @@ func main() {
 
 	checkCmd := app.Command("check", "Check the resources for validity.")
 
+	experimental := app.Flag("experimental", "Enable experimental commands.").Bool()
+
 	sdCheckCmd := checkCmd.Command("service-discovery", "Perform service discovery for the given job name and report the results, including relabeling.")
 	sdConfigFile := sdCheckCmd.Arg("config-file", "The prometheus config file.").Required().ExistingFile()
 	sdJobName := sdCheckCmd.Arg("job", "The job to run service discovery for.").Required().String()
@@ -246,7 +248,7 @@ func main() {
 		"A list of one or more files containing recording rules to be backfilled. All recording rules listed in the files will be backfilled. Alerting rules are not evaluated.",
 	).Required().ExistingFiles()
 
-	promQLCmd := app.Command("promql", "PromQL formatting and editing.")
+	promQLCmd := app.Command("promql", "PromQL formatting and editing. Requires the --experimental flag.")
 
 	promQLFormatCmd := promQLCmd.Command("format", "Format PromQL query to pretty printed form.")
 	promQLFormatQuery := promQLFormatCmd.Arg("query", "PromQL query.").Required().String()
@@ -386,16 +388,26 @@ func main() {
 		os.Exit(checkErr(documentcli.GenerateMarkdown(app.Model(), os.Stdout)))
 
 	case promQLFormatCmd.FullCommand():
+		checkExperimental(*experimental)
 		os.Exit(checkErr(formatPromQL(*promQLFormatQuery)))
 
 	case promQLLabelsSetCmd.FullCommand():
+		checkExperimental(*experimental)
 		os.Exit(checkErr(labelsSetPromQL(*promQLLabelsSetQuery, *promQLLabelsSetType, *promQLLabelsSetName, *promQLLabelsSetValue)))
 
 	case promQLLabelsDeleteCmd.FullCommand():
+		checkExperimental(*experimental)
 		os.Exit(checkErr(labelsDeletePromQL(*promQLLabelsDeleteQuery, *promQLLabelsDeleteName)))
 	}
 }
 
+func checkExperimental(f bool) {
+	if !f {
+		fmt.Fprintln(os.Stderr, "This command is experimental and requires the --experimental flag to be set.")
+		os.Exit(1)
+	}
+}
+
 // nolint:revive
 var lintError = fmt.Errorf("lint error")
 
diff --git a/docs/command-line/promtool.md b/docs/command-line/promtool.md
index 673e8c048..587286e10 100644
--- a/docs/command-line/promtool.md
+++ b/docs/command-line/promtool.md
@@ -14,6 +14,7 @@ Tooling for the Prometheus monitoring system.
 | --- | --- |
 | <code class="text-nowrap">-h</code>, <code class="text-nowrap">--help</code> | Show context-sensitive help (also try --help-long and --help-man). |
 | <code class="text-nowrap">--version</code> | Show application version. |
+| <code class="text-nowrap">--experimental</code> | Enable experimental commands. |
 | <code class="text-nowrap">--enable-feature</code> | Comma separated feature names to enable (only PromQL related and no-default-scrape-port). See https://prometheus.io/docs/prometheus/latest/feature_flags/ for the options and more details. |
 
 
@@ -30,6 +31,7 @@ Tooling for the Prometheus monitoring system.
 | push | Push to a Prometheus server. |
 | test | Unit testing. |
 | tsdb | Run tsdb commands. |
+| promql | PromQL formatting and editing. Requires the --experimental flag. |
 
 
 
@@ -609,3 +611,72 @@ Create blocks of data for new recording rules.
 | rule-files | A list of one or more files containing recording rules to be backfilled. All recording rules listed in the files will be backfilled. Alerting rules are not evaluated. | Yes |
 
 
+
+
+### `promtool promql`
+
+PromQL formatting and editing. Requires the --experimental flag.
+
+
+
+##### `promtool promql format`
+
+Format PromQL query to pretty printed form.
+
+
+
+###### Arguments
+
+| Argument | Description | Required |
+| --- | --- | --- |
+| query | PromQL query. | Yes |
+
+
+
+
+##### `promtool promql label-matchers`
+
+Edit label matchers contained within an existing PromQL query.
+
+
+
+##### `promtool promql label-matchers set`
+
+Set a label matcher in the query.
+
+
+
+###### Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| <code class="text-nowrap">-t</code>, <code class="text-nowrap">--type</code> | Type of the label matcher to set. | `=` |
+
+
+
+
+###### Arguments
+
+| Argument | Description | Required |
+| --- | --- | --- |
+| query | PromQL query. | Yes |
+| name | Name of the label matcher to set. | Yes |
+| value | Value of the label matcher to set. | Yes |
+
+
+
+
+##### `promtool promql label-matchers delete`
+
+Delete a label from the query.
+
+
+
+###### Arguments
+
+| Argument | Description | Required |
+| --- | --- | --- |
+| query | PromQL query. | Yes |
+| name | Name of the label to delete. | Yes |
+
+