Merge branch 'master' into add-query-frontend-parse

Author: mattmendick

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## unreleased / master
 
+* [FEATURE] Add `rules prepare` command. It allows you add a label to PromQL aggregations and lint your expressions in rule files.
+
 ## v0.1.4 / 2020-03-10
 
 * [CHANGE] Ensure 404 deletes do not trigger an error for `rules` and `alertmanager` commands #28

README.md

@@ -68,15 +68,37 @@ This command will load each rule group in the specified files and load them into
 
     cortextool rules load ./example_rules_one.yaml ./example_rules_two.yaml  ...
 
+#### Rules Lint
+
+This command lints a rules file. The linter's aim is not to verify correctness but just YAML and PromQL expression formatting within the rule file. This command always edits in place, you can use the dry run flag (`-n`) if you'd like to perform a trial run that does not make any changes.
+
+    cortextool rules lint -n ./example_rules_one.yaml ./example_rules_two.yaml ...
+
+#### Rules Prepare
+
+This command prepares a rules file for upload to Cortex. It lints all your PromQL expressions and adds an specific label to your PromQL query aggregations in the file. Unlike, the previous command this one does not interact with your Cortex cluster.
+
+    cortextool rules prepare -i ./example_rules_one.yaml ./example_rules_two.yaml ...
+
+There are two flags of note for this command:
+- `-i` which allows you to edit in place, otherwise a a new file with a `.output` extension is created with the results of the run.
+- `-l` which allows you specify the label you want you add for your aggregations, it is `cluster` by default.
+
+At the end of the run, the command tells you whenever the operation was a success in the form of
+
+    INFO[0000] SUCESS: 194 rules found, 0 modified expressions
+
+It is important to note that a modification can be a PromQL expression lint or a label add to your aggregation.
+
 ## chunktool
 
 This repo also contains the `chunktool`. A client meant to interact with chunks stored and indexed in cortex backends.
 
-#### Chunk Delete
+##### Chunk Delete
 
 The delete command currently cleans all index entries pointing to chunks in the specified index. Only bigtable and the v10 schema are currently fully supported. This will not delete the entire index entry, only the corresponding chunk entries within the index row.
 
-#### Chunk Migrate
+##### Chunk Migrate
 
 The migrate command helps with migrating chunks across cortex clusters. It also takes care of setting right index in the new cluster as per the specified schema config.
 

go.mod

@@ -20,8 +20,10 @@ require (
 	github.com/prometheus/common v0.7.0
 	github.com/prometheus/prometheus v1.8.2-0.20190918104050-8744afdd1ea0
 	github.com/sirupsen/logrus v1.4.2
+	github.com/stretchr/testify v1.4.0
 	google.golang.org/api v0.8.0
 	gopkg.in/alecthomas/kingpin.v2 v2.2.6
 	gopkg.in/yaml.v2 v2.2.2
+	gopkg.in/yaml.v3 v3.0.0-20200506231410-2ff61e1afc86
 	sigs.k8s.io/yaml v1.1.0
 )

go.sum

@@ -849,6 +849,8 @@ gopkg.in/yaml.v2 v2.0.0-20170812160011-eb3733d160e7/go.mod h1:JAlM8MvJe8wmxCU4Bl
 gopkg.in/yaml.v2 v2.2.1/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.2.2 h1:ZCJp+EgiOT7lHqUV2J862kp8Qj64Jo6az82+3Td9dZw=
 gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v3 v3.0.0-20200506231410-2ff61e1afc86 h1:OfFoIUYv/me30yv7XlMy4F9RJw8DEm8WQ6QG1Ph4bH0=
+gopkg.in/yaml.v3 v3.0.0-20200506231410-2ff61e1afc86/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 honnef.co/go/tools v0.0.0-20180728063816-88497007e858/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
 honnef.co/go/tools v0.0.0-20180920025451-e3ad64cb4ed3/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
 honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=

pkg/commands/rules.go

@@ -3,6 +3,7 @@ package commands
 import (
 	"context"
 	"fmt"
+	"io/ioutil"
 	"os"
 	"path/filepath"
 	"strings"
@@ -16,6 +17,11 @@ import (
 	"github.com/grafana/cortextool/pkg/rules"
 	log "github.com/sirupsen/logrus"
 	"gopkg.in/alecthomas/kingpin.v2"
+	yamlv3 "gopkg.in/yaml.v3"
+)
+
+const (
+	defaultPrepareAggregationLabel = "cluster"
 )
 
 var (
@@ -31,7 +37,7 @@ var (
 	})
 )
 
-// RuleCommand configures and executes rule related cortex api operations
+// RuleCommand configures and executes rule related cortex operations
 type RuleCommand struct {
 	ClientConfig client.Config
 
@@ -41,7 +47,7 @@ type RuleCommand struct {
 	Namespace string
 	RuleGroup string
 
-	// Load Rules Configs
+	// Load Rules Config
 	RuleFilesList []string
 	RuleFiles     string
 	RuleFilesPath string
@@ -50,38 +56,79 @@ type RuleCommand struct {
 	IgnoredNamespaces    string
 	ignoredNamespacesMap map[string]struct{}
 
+	// Prepare Rules Config
+	InPlaceEdit      bool
+	AggregationLabel string
+
+	// Lint Rules Config
+	LintDryRun bool
+
 	DisableColor bool
 }
 
 // Register rule related commands and flags with the kingpin application
 func (r *RuleCommand) Register(app *kingpin.Application) {
 	rulesCmd := app.Command("rules", "View & edit rules stored in cortex.").PreAction(r.setup)
-	rulesCmd.Flag("address", "Address of the cortex cluster, alternatively set CORTEX_ADDRESS.").Envar("CORTEX_ADDRESS").Required().StringVar(&r.ClientConfig.Address)
-	rulesCmd.Flag("id", "Cortex tenant id, alternatively set CORTEX_TENANT_ID.").Envar("CORTEX_TENANT_ID").Required().StringVar(&r.ClientConfig.ID)
 	rulesCmd.Flag("key", "Api key to use when contacting cortex, alternatively set $CORTEX_API_KEY.").Default("").Envar("CORTEX_API_KEY").StringVar(&r.ClientConfig.Key)
 
-	// List Rules Command
-	rulesCmd.Command("list", "List the rules currently in the cortex ruler.").Action(r.listRules)
+	// Register rule commands
+	listCmd := rulesCmd.
+		Command("list", "List the rules currently in the cortex ruler.").
+		Action(r.listRules)
+	printRulesCmd := rulesCmd.
+		Command("print", "Print the rules currently in the cortex ruler.").
+		Action(r.printRules)
+	getRuleGroupCmd := rulesCmd.
+		Command("get", "Retreive a rulegroup from the ruler.").
+		Action(r.getRuleGroup)
+	deleteRuleGroupCmd := rulesCmd.
+		Command("delete", "Delete a rulegroup from the ruler.").
+		Action(r.deleteRuleGroup)
+	loadRulesCmd := rulesCmd.
+		Command("load", "load a set of rules to a designated cortex endpoint").
+		Action(r.loadRules)
+	diffRulesCmd := rulesCmd.
+		Command("diff", "diff a set of rules to a designated cortex endpoint").
+		Action(r.diffRules)
+	syncRulesCmd := rulesCmd.
+		Command("sync", "sync a set of rules to a designated cortex endpoint").
+		Action(r.syncRules)
+	prepareCmd := rulesCmd.
+		Command("prepare", "modifies a set of rules by including an specific label in aggregations.").
+		Action(r.prepare)
+	lintCmd := rulesCmd.
+		Command("lint", "formats a set of rule files. It reorders keys alphabetically, uses 4 spaces as indentantion, and formats PromQL expressions to a single line.").
+		Action(r.lint)
+
+	// Require Cortex cluster address and tentant ID on all these commands
+	for _, c := range []*kingpin.CmdClause{listCmd, printRulesCmd, getRuleGroupCmd, deleteRuleGroupCmd, loadRulesCmd, diffRulesCmd, syncRulesCmd} {
+		c.Flag("address", "Address of the cortex cluster, alternatively set CORTEX_ADDRESS.").
+			Envar("CORTEX_ADDRESS").
+			Required().
+			StringVar(&r.ClientConfig.Address)
+
+		c.Flag("id", "Cortex tenant id, alternatively set CORTEX_TENANT_ID.").
+			Envar("CORTEX_TENANT_ID").
+			Required().
+			StringVar(&r.ClientConfig.ID)
+	}
 
 	// Print Rules Command
-	printRulesCmd := rulesCmd.Command("print", "Print the rules currently in the cortex ruler.").Action(r.printRules)
 	printRulesCmd.Flag("disable-color", "disable colored output").BoolVar(&r.DisableColor)
 
 	// Get RuleGroup Command
-	getRuleGroupCmd := rulesCmd.Command("get", "Retreive a rulegroup from the ruler.").Action(r.getRuleGroup)
 	getRuleGroupCmd.Arg("namespace", "Namespace of the rulegroup to retrieve.").Required().StringVar(&r.Namespace)
 	getRuleGroupCmd.Arg("group", "Name of the rulegroup ot retrieve.").Required().StringVar(&r.RuleGroup)
 	getRuleGroupCmd.Flag("disable-color", "disable colored output").BoolVar(&r.DisableColor)
 
 	// Delete RuleGroup Command
-	deleteRuleGroupCmd := rulesCmd.Command("delete", "Delete a rulegroup from the ruler.").Action(r.deleteRuleGroup)
 	deleteRuleGroupCmd.Arg("namespace", "Namespace of the rulegroup to delete.").Required().StringVar(&r.Namespace)
 	deleteRuleGroupCmd.Arg("group", "Name of the rulegroup ot delete.").Required().StringVar(&r.RuleGroup)
 
-	loadRulesCmd := rulesCmd.Command("load", "load a set of rules to a designated cortex endpoint").Action(r.loadRules)
+	// Load Rules Command
 	loadRulesCmd.Arg("rule-files", "The rule files to check.").Required().ExistingFilesVar(&r.RuleFilesList)
 
-	diffRulesCmd := rulesCmd.Command("diff", "diff a set of rules to a designated cortex endpoint").Action(r.diffRules)
+	// Diff Command
 	diffRulesCmd.Flag("ignored-namespaces", "comma-separated list of namespaces to ignore during a diff.").StringVar(&r.IgnoredNamespaces)
 	diffRulesCmd.Flag("rule-files", "The rule files to check. Flag can be reused to load multiple files.").StringVar(&r.RuleFiles)
 	diffRulesCmd.Flag(
@@ -90,13 +137,35 @@ func (r *RuleCommand) Register(app *kingpin.Application) {
 	).StringVar(&r.RuleFilesPath)
 	diffRulesCmd.Flag("disable-color", "disable colored output").BoolVar(&r.DisableColor)
 
-	syncRulesCmd := rulesCmd.Command("sync", "sync a set of rules to a designated cortex endpoint").Action(r.syncRules)
+	// Sync Command
 	syncRulesCmd.Flag("ignored-namespaces", "comma-separated list of namespaces to ignore during a sync.").StringVar(&r.IgnoredNamespaces)
 	syncRulesCmd.Flag("rule-files", "The rule files to check. Flag can be reused to load multiple files.").StringVar(&r.RuleFiles)
 	syncRulesCmd.Flag(
 		"rule-dirs",
 		"Comma seperated list of paths to directories containing rules yaml files. Each file in a directory with a .yml or .yaml suffix will be parsed.",
 	).StringVar(&r.RuleFilesPath)
+
+	// Prepare Command
+	prepareCmd.Arg("rule-files", "The rule files to check.").Required().ExistingFilesVar(&r.RuleFilesList)
+	prepareCmd.Flag("rule-files", "The rule files to check. Flag can be reused to load multiple files.").StringVar(&r.RuleFiles)
+	prepareCmd.Flag(
+		"rule-dirs",
+		"Comma seperated list of paths to directories containing rules yaml files. Each file in a directory with a .yml or .yaml suffix will be parsed.",
+	).StringVar(&r.RuleFilesPath)
+	prepareCmd.Flag(
+		"in-place",
+		"edits the rule file in place",
+	).Short('i').BoolVar(&r.InPlaceEdit)
+	prepareCmd.Flag("label", "label to include as part of the aggregations.").Default(defaultPrepareAggregationLabel).Short('l').StringVar(&r.AggregationLabel)
+
+	// Lint Command
+	lintCmd.Arg("rule-files", "The rule files to check.").Required().ExistingFilesVar(&r.RuleFilesList)
+	lintCmd.Flag("rule-files", "The rule files to check. Flag can be reused to load multiple files.").StringVar(&r.RuleFiles)
+	lintCmd.Flag(
+		"rule-dirs",
+		"Comma seperated list of paths to directories containing rules yaml files. Each file in a directory with a .yml or .yaml suffix will be parsed.",
+	).StringVar(&r.RuleFilesPath)
+	lintCmd.Flag("dry-run", "Performs a trial run that doesn't make any changes and (mostly) produces the same outpupt as a real run.").Short('n').BoolVar(&r.LintDryRun)
 }
 
 func (r *RuleCommand) setup(k *kingpin.ParseContext) error {
@@ -420,3 +489,91 @@ func (r *RuleCommand) executeChanges(ctx context.Context, changes []rules.Namesp
 	fmt.Printf("Sync Summary: %v Groups Created, %v Groups Updated, %v Groups Deleted\n", created, updated, deleted)
 	return nil
 }
+
+func (r *RuleCommand) prepare(k *kingpin.ParseContext) error {
+	err := r.setupFiles()
+	if err != nil {
+		return errors.Wrap(err, "prepare operation unsuccessful, unable to load rules files")
+	}
+
+	namespaces, err := rules.ParseFiles(r.RuleFilesList)
+	if err != nil {
+		return errors.Wrap(err, "prepare operation unsuccessful, unable to parse rules files")
+	}
+
+	var count, mod int
+	for _, ruleNamespace := range namespaces {
+		c, m, err := ruleNamespace.AggregateBy(r.AggregationLabel)
+		if err != nil {
+			return err
+		}
+
+		count += c
+		mod += m
+	}
+
+	// now, save all the files
+	if err := save(namespaces, r.InPlaceEdit); err != nil {
+		return err
+	}
+
+	log.Infof("SUCCESS: %d rules found, %d modified expressions", count, mod)
+
+	return nil
+}
+
+func (r *RuleCommand) lint(k *kingpin.ParseContext) error {
+	err := r.setupFiles()
+	if err != nil {
+		return errors.Wrap(err, "prepare operation unsuccessful, unable to load rules files")
+	}
+
+	namespaces, err := rules.ParseFiles(r.RuleFilesList)
+	if err != nil {
+		return errors.Wrap(err, "prepare operation unsuccessful, unable to parse rules files")
+	}
+
+	var count, mod int
+	for _, ruleNamespace := range namespaces {
+		c, m, err := ruleNamespace.LintPromQLExpressions()
+		if err != nil {
+			return err
+		}
+
+		count += c
+		mod += m
+	}
+
+	if !r.LintDryRun {
+		// linting will always in-place edit unless is a dry-run.
+		if err := save(namespaces, true); err != nil {
+			return err
+		}
+	}
+
+	log.Infof("SUCCESS: %d rules found, %d linted expressions", count, mod)
+
+	return nil
+}
+
+// save saves a set of rule files to to disk. You can specify whenever you want the
+// file(s) to be edited in-place.
+func save(nss map[string]rules.RuleNamespace, i bool) error {
+	for _, ns := range nss {
+		payload, err := yamlv3.Marshal(ns)
+		if err != nil {
+			return err
+		}
+
+		filepath := ns.Filepath
+		if !i {
+			filepath = filepath + ".result"
+		}
+
+		if err := ioutil.WriteFile(filepath, payload, 0644); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}

pkg/rules/parser.go

@@ -30,6 +30,8 @@ func ParseFiles(files []string) (map[string]RuleNamespace, error) {
 			return nil, errFileReadError
 		}
 
+		ns.Filepath = f
+
 		// Determine if the namespace is explicitly set. If not
 		// the file name without the extension is used.
 		namespace := ns.Namespace