jiralert: Improved docs and config. by bwplotka · Pull Request #32 · prometheus-community/jiralert

bwplotka · 2019-04-12T20:29:28Z

Changes:

Template file is not needed anymore if you don't define anything. (Remove need to template file #11)
Clean up of not used structs & vars
Improved comments on doc which makes example not needed (if we can use goDocs)

Thoughts @free ? (:

Signed-off-by: Bartek Plotka bwplotka@gmail.com

Signed-off-by: Bartek Plotka <bwplotka@gmail.com>

free

Lots of nitpicking (apologies for that) and a more general comment: I (and I'm sure lots of others) find it really useful to have a sample configuration file as a starting point. If I was a Java-only (or Python-only or whatever) developer I'd find it really inconvenient to parse Golang documentation in order to extract a working example for a basic configuration.

This is even worse regarding the removal of the template file: we are now asking people who may not even be coders to figure out Golang's template language plus Alertmanager's data structures in order to write a bunch of templates, unless they are fine with all their tickets being named "Alert" and having an empty description.

At the very least, the sample configuration and template file contents should be included verbatim into the documentation. (Even though, as you noticed, said documentation can disappear without trace for weeks at a time from GoDoc.)

free · 2019-05-10T13:38:08Z

pkg/config/config.go

+	// Summary specifies Golang template invocation for generating the issue summary.
 	Summary     string `yaml:"summary" json:"summary"`
+	// ReopenState specifies the state to transition into when reopening a closed issue.
+	// This state has to exists for the chosen project.


Suggested change

// This state has to exists for the chosen project.

// This state must exist for the chosen project and should ideally be reachable from all other states.

free · 2019-05-31T09:19:18Z

README.md

+You can find more docs in [the configuration itself](/pkg/config/config.go)
+
+Each receiver must have:
+* a unique name (matching the Alertmanager receiver name)


Suggested change

* a unique name (matching the Alertmanager receiver name)

* a unique name (matching the Alertmanager receiver name),

free · 2019-05-31T09:19:31Z

README.md

+Each receiver must have:
+* a unique name (matching the Alertmanager receiver name)
+* JIRA API access fields (URL, username and password),
+* handful of required issue fields (such as the JIRA project and issue summary), 


Suggested change

* handful of required issue fields (such as the JIRA project and issue summary),

* required issue fields (such as the JIRA project and issue summary),

free · 2019-05-31T09:20:08Z

README.md

+* a unique name (matching the Alertmanager receiver name)
+* JIRA API access fields (URL, username and password),
+* handful of required issue fields (such as the JIRA project and issue summary), 
+* some optional issue fields (e.g. priority) and a `fields` map for other (standard or custom) JIRA fields. 


Suggested change

* some optional issue fields (e.g. priority) and a `fields` map for other (standard or custom) JIRA fields.

* optional issue fields (e.g. priority), including a `fields` map for other (standard or custom) JIRA fields.

free · 2019-05-31T09:26:03Z

pkg/config/config.go

 type ReceiverConfig struct {
+	// Name represents unique name for a receiver.
+	// If Iiralert is used with Alertmanager, name it as Alertmanager receiver that sends alert via webhook to Jiralert for
+	// desired propagation.


I'd replace all this with

// Name is a unique receiver name. It must match an Alertmanager receiver name. Required.

free · 2019-05-31T10:51:20Z

pkg/config/config.go

-	// Optional issue fields
+	// Priority represents issue priority.
 	Priority          string                 `yaml:"priority" json:"priority"`
+	// Description specifies Golang template invocation for generating the issue description.


Suggested change

// Description specifies Golang template invocation for generating the issue description.

// Description is a plain string; or Golang template invocation to generate the issue description.

free · 2019-05-31T10:55:16Z

pkg/config/config.go

 	Description       string                 `yaml:"description" json:"description"`
+	// WontFixResolution specifies to not reopen issues with this resolution. Useful for silencing alerts.
 	WontFixResolution string                 `yaml:"wont_fix_resolution" json:"wont_fix_resolution"`
+	// Fields specifies standard or custom field values to set on created issue.


Suggested change

// Fields specifies standard or custom field values to set on created issue.

// Fields specifies standard or custom field values to set on created issue. E.g.

// * TextField: "Random text"

// * SelectList: { "value": "red" }

// * MultiSelect: [{"value": "red" }, {"value": "blue" }, {"value": "green" }]

free · 2019-05-31T10:56:13Z

pkg/config/config.go


 // Config is the top-level configuration for JIRAlert's config file.
 type Config struct {
+	// Default specifies default values to be used in place of any ReceiverConfig' empty field.


Suggested change

// Default specifies default values to be used in place of any ReceiverConfig' empty field.

// Default specifies default values to be used in place of any ReceiverConfig empty field.

free · 2019-05-31T10:57:43Z

pkg/template/template.go

 	}
-	return &Template{tmpl: tmpl}, nil
+
+	level.Info(logger).Log("msg", "no template was passed.")


Suggested change

level.Info(logger).Log("msg", "no template was passed.")

level.Info(logger).Log("msg", "no template file provided")

free · 2019-05-31T11:00:00Z

pkg/config/config.go

+	// Receivers contains configuration per each receiver.
 	Receivers []*ReceiverConfig `yaml:"receivers,omitempty" json:"receivers,omitempty"`
+
+	// Template specifies an optional file with template definitions.


I have an issue with defaulting to no template file: with no templating, JIRAlert will always create identical JIRA tickets (except the label, but that's not even intended for human consumption). Why would anyone want that at all? Much less as default behavior?

(I know about the deployment issue someone brought up, but I have a hard time believing there exists a widely used deployment tool that trips up on Golang templates and provides no workaround for that. What if the binary contains Golang templates as strings?)

bwplotka · 2021-03-05T12:51:22Z

Let me get back to this, rebase and improve 🤗

bwplotka requested a review from free April 12, 2019 20:29

jiralert: Improved docs and config.

c9b4966

Signed-off-by: Bartek Plotka <bwplotka@gmail.com>

bwplotka force-pushed the config-impr branch from e04fc79 to c9b4966 Compare May 10, 2019 10:27

free reviewed May 31, 2019

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

jiralert: Improved docs and config.#32

jiralert: Improved docs and config.#32
bwplotka wants to merge 1 commit intomasterfrom
config-impr

bwplotka commented Apr 12, 2019 •

edited

Loading

Uh oh!

free left a comment

Uh oh!

free May 10, 2019

Uh oh!

free May 31, 2019

Uh oh!

free May 31, 2019

Uh oh!

free May 31, 2019

Uh oh!

free May 31, 2019

Uh oh!

free May 31, 2019

Uh oh!

free May 31, 2019

Uh oh!

free May 31, 2019

Uh oh!

free May 31, 2019

Uh oh!

free May 31, 2019

Uh oh!

bwplotka commented Mar 5, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	// This state has to exists for the chosen project.
	// This state must exist for the chosen project and should ideally be reachable from all other states.

	* a unique name (matching the Alertmanager receiver name)
	* a unique name (matching the Alertmanager receiver name),

	* handful of required issue fields (such as the JIRA project and issue summary),
	* required issue fields (such as the JIRA project and issue summary),

	* some optional issue fields (e.g. priority) and a `fields` map for other (standard or custom) JIRA fields.
	* optional issue fields (e.g. priority), including a `fields` map for other (standard or custom) JIRA fields.

	// Description specifies Golang template invocation for generating the issue description.
	// Description is a plain string; or Golang template invocation to generate the issue description.

-	// Fields specifies standard or custom field values to set on created issue.
+	// Fields specifies standard or custom field values to set on created issue. E.g.
+	// * TextField: "Random text"
+	// * SelectList: { "value": "red" }
+	// * MultiSelect: [{"value": "red" }, {"value": "blue" }, {"value": "green" }]

	// Default specifies default values to be used in place of any ReceiverConfig' empty field.
	// Default specifies default values to be used in place of any ReceiverConfig empty field.

	level.Info(logger).Log("msg", "no template was passed.")
	level.Info(logger).Log("msg", "no template file provided")

Conversation

bwplotka commented Apr 12, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

free left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bwplotka commented Mar 5, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

bwplotka commented Apr 12, 2019 •

edited

Loading