jiralert

README

JIRAlert

Prometheus Alertmanager webhook receiver for JIRA.

Overview

JIRAlert implements Alertmanager's webhook HTTP API and connects to one or more JIRA instances to create highly configurable JIRA issues. One issue is created per distinct group key — as defined by the group_by parameter of Alertmanager's route configuration section — but not closed when the alert is resolved. The expectation is that a human will look at the issue, take any necessary action, then close it. If no human interaction is necessary then it should probably not alert in the first place.

If a corresponding JIRA issue already exists but is resolved, it is reopened. A JIRA transition must exist between the resolved state and the reopened state — as defined by reopen_state — or reopening will fail. Optionally a "won't fix" resolution — defined by wont_fix_resolution — may be defined: a JIRA issue with this resolution will not be reopened by JIRAlert.

Usage

Get JIRAlert, either as a packaged release or build it yourself:

$ go get github.com/free/jiralert/cmd/jiralert

then run it from the command line:

$ jiralert

Use the -help flag to get help information.

$ jiralert -help
Usage of jiralert:
  -config string
      The JIRAlert configuration file (default "config/jiralert.yml")
  -listen-address string
      The address to listen on for HTTP requests. (default ":9097")
  [...]

Testing

JIRAlert expects a JSON object from Alertmanager. The format of this JSON is described in the Alertmanager documentation or, alternatively, in the Alertmanager GoDoc.

To quickly test if JIRAlert is working you can run:

$ curl -H "Content-type: application/json" -X POST \
  -d '{"receiver": "jira-ab", "status": "firing", "alerts": [{"status": "firing", "labels": {"alertname": "TestAlert", "key": "value"} }], "groupLabels": {"alertname": "TestAlert"}}' \
  http://localhost:9097/alert

Configuration

The configuration file is essentially a list of receivers matching 1-to-1 all Alertmanager receivers using JIRAlert; plus defaults (in the form of a partially defined receiver); and a pointer to the template file.

Each receiver must have a unique name (matching the Alertmanager receiver name), JIRA API access fields (URL, username and password), a 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. Most of these may use Go templating to generate the actual field values based on the contents of the Alertmanager notification. The exact same data structures and functions as those defined in the Alertmanager template reference are available in JIRAlert.

Alertmanager configuration

To enable Alertmanager to talk to JIRAlert you need to configure a webhook in Alertmanager. You can do that by adding a webhook receiver to your Alertmanager configuration.

receivers:
- name: 'jira-ab'
  webhook_configs:
  - url: 'http://localhost:9097/alert'
    # JIRAlert ignores resolved alerts, avoid unnecessary noise
    send_resolved: false

Profiling

JIRAlert imports net/http/pprof to expose runtime profiling data on the /debug/pprof endpoint. For example, to use the pprof tool to look at a 30-second CPU profile:

go tool pprof http://localhost:9097/debug/pprof/profile

To enable mutex and block profiling (i.e. /debug/pprof/mutex and /debug/pprof/block) run JIRAlert with the DEBUG environment variable set:

env DEBUG=1 ./jiralert

License

JIRAlert is licensed under the MIT License.

Copyright (c) 2017, Alin Sinpalean

Documentation

Index

• type APIConfig
• type Config
  • func ReadConfiguration(configDir string) (*Config, error)
  • func (c *Config) ReceiverByName(name string) *ReceiverConfig
  • func (c Config) String() string
• type Notifier
• type Receiver
  • func NewReceiver(context context.Context, a *APIConfig, c *ReceiverConfig, t *Template, ...) (*Receiver, error)
  • func (r *Receiver) Notify(context context.Context, data *alertmanager.Data) (map[string]StatusNotify, error)
• type ReceiverConfig
• type StatusNotify
• type Template
  • func LoadTemplate(path string) (*Template, error)
  • func (t *Template) Execute(text string, data interface{}) string

Types

type APIConfig

type APIConfig struct {
	// API access fields
	URL      string
	User     string
	Password string
}

APIConfig contains API access fields (URL, user and password)

type Config

type Config struct {
	API       *APIConfig
	Receivers []*ReceiverConfig
	Template  string

	// Catches all undefined fields and must be empty after parsing.
	XXX map[string]interface{} `yaml:",inline" json:"-"`
}

Config is the top-level configuration for JIRAlert's config file.

func ReadConfiguration

func ReadConfiguration(configDir string) (*Config, error)

ReadConfiguration parses the YAML input into a Config

func (*Config) ReceiverByName

func (c *Config) ReceiverByName(name string) *ReceiverConfig

ReceiverByName loops the receiver list and returns the first instance with that name

func (Config) String

func (c Config) String() string

type Notifier

type Notifier interface {
	Notify(data *alertmanager.Data) map[string]StatusNotify
}

type Receiver

type Receiver struct {
	// contains filtered or unexported fields
}

github.com/andygrunwald/go-jira Receiver wraps a JIRA client corresponding to a specific Alertmanager receiver, with its configuration and templates.

func NewReceiver

func NewReceiver(context context.Context, a *APIConfig, c *ReceiverConfig, t *Template, file string) (*Receiver, error)

NewReceiver creates a Receiver using the provided configuration and template.

func (*Receiver) Notify

func (r *Receiver) Notify(context context.Context, data *alertmanager.Data) (map[string]StatusNotify, error)

Notify implements the Notifier interface.

type ReceiverConfig

type ReceiverConfig struct {
	Name string

	// Required issue fields
	Project     string
	IssueType   string
	Summary     string
	ReopenState string

	// Optional issue fields
	Priority          string
	Description       string
	Comment           string
	WontFixResolution string
	Fields            map[string]interface{}
	Components        []string

	// Label copy settings
	AddGroupLabels bool

	// Catches all undefined fields and must be empty after parsing.
	XXX map[string]interface{}
}

ReceiverConfig is the configuration for one receiver. It has a unique name and includes and issue fields (required -- e.g. project, issue type -- and optional -- e.g. priority).

type StatusNotify

type StatusNotify struct {
	Status int
	Err    error
}

type Template

type Template struct {
	// contains filtered or unexported fields
}

Template wraps a text template and error, to make it easier to execute multiple templates and only check for errors once at the end (assuming one is only interested in the first error, which is usually the case).

func LoadTemplate

func LoadTemplate(path string) (*Template, error)

LoadTemplate reads and parses all templates defined in the given file and constructs a jiralert.Template.

func (*Template) Execute

func (t *Template) Execute(text string, data interface{}) string

Execute parses the provided text (or returns it unchanged if not a Go template), associates it with the templates defined in t.tmpl (so they may be referenced and used) and applies the resulting template to the specified data object, returning the output as a string.