kkok

package module
v0.0.0-...-1b1fa67 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 31, 2017 License: MIT Imports: 19 Imported by: 0

README

GitHub release GoDoc Build Status Go Report Card License

kkok (taken from Japanese word 警告 - keikoku -, in English alert) is a service to process alerts nicely. It gathers alerts from miscellaneous sources, applies filters to edit or route them, then sends the processed alerts via email, SMS (Twilio), Slack, etc.

Architecture

kkok sends alerts through these steps:

  1. Generate alerts from sources.
  2. Collect and pool alerts for some duration.
  3. Edit/route collected alerts by filters.
  4. Send alerts along with the given routes.

Please read Architecture.md for more details.

Features

  • Generators:

    • HTTP REST API.
    • maildir: generate alerts from mails in a Maildir directory.

  • Filters:

    • freq: calculate and add frequency information to alerts.
    • discard: discard alerts based on the given conditions.
    • group: merge alerts into groups by field values.
    • route: add or replace routes to alert receivers.
    • edit: edit alerts by JavaScript.
    • exec: invoke an external command to edit alerts.

  • Transports:

    • email: format and send alerts via email.
    • slack: format and send alerts to a Slack channel.
    • twilio: format and send SMS via Twilio.
    • exec: invoke an external command to send alerts.

Build

Use Go 1.7 or better.

Run the command below exactly as shown, including the ellipsis. They are significant - see go help packages.

go get -u github.com/cybozu-go/kkok/...

Usage

Read Usage.md and API.md.

License

MIT

Authors & Contributors

Documentation

Overview

Package kkok provides fundamentals to compose kkok.

Index

Constants

View Source 
const (
	// Version is a constant string of the kkok version.
	Version = "0.1.0"
)

Variables

This section is empty.

Functions

func CompileJS 

func CompileJS(s string) (*otto.Script, error)

CompileJS compiles a JavaScript expression s. The returned script can be passed to VM.EvalAlert and VM.EvalAlerts.

func NewHTTPServer 

func NewHTTPServer(addr, apiToken string, k *Kkok, d *Dispatcher) (*cmd.HTTPServer, error)

NewHTTPServer returns *cmd.HTTPServer for REST API.

func RegisterFilter 

func RegisterFilter(typ string, ctor FilterConstructor)

RegisterFilter registers a construction function of a Filter type.

func RegisterSource 

func RegisterSource(typ string, ctor SourceConstructor)

RegisterSource registers a construction function of a Source type.

func RegisterTransport 

func RegisterTransport(typ string, ctor TransportConstructor)

RegisterTransport registers a construction function of a Transport type.

Types

type Alert 

type Alert struct {

	// From is an identifying string who sent this alert.
	// Example: "NTP monitor"
	From string

	// Date is the time when this alert is generated.
	Date time.Time

	// Host is the hostname or IP address where this alert is generated.
	Host string

	// Title is one-line description of the alert.
	Title string

	// Message is multi-line description of the alert.
	Message string `json:",omitempty"`

	// Routes contain route ID strings along which this alert is delivered.
	Routes []string

	// Info is a map of additional alert properties.
	Info map[string]interface{} `json:",omitempty"`

	// Stats is a map of dynamically calculated values by filters.
	// This field is ignored for JSON.
	Stats map[string]float64 `json:"-"`

	// Sub may list alerts grouped into this.
	Sub []*Alert `json:",omitempty"`
}

Alert represents an alert.

func (*Alert) Clone 

func (a *Alert) Clone() *Alert

Clone returns a deeply-copied clone of a.

Stats field is not copied.

func (*Alert) SetInfo 

func (a *Alert) SetInfo(key string, value interface{})

SetInfo sets a value in Info with key.

func (*Alert) SetStat 

func (a *Alert) SetStat(key string, value float64)

SetStat sets a statistics value with key.

func (*Alert) String 

func (a *Alert) String() string

String returns a string representation of the alert.

func (*Alert) Validate 

func (a *Alert) Validate() error

Validate validates constructed Alert struct. For invalid structs, non-nil errors are returned.

type AlertHandler 

type AlertHandler interface {
	Handle([]*Alert)
}

AlertHandler is an interface for NewDispatcher.

type BaseFilter 

type BaseFilter struct {
	VM
	// contains filtered or unexported fields
}

BaseFilter provides the common implementation for all filters.

Filter plugins MUST embed BaseFilter anonymously.

func (*BaseFilter) AddParams 

func (b *BaseFilter) AddParams(m map[string]interface{})

AddParams adds basic parameters for Filter.Params method. The map must not be nil.

func (*BaseFilter) All 

func (b *BaseFilter) All() bool

All returns true iff the filter processes all alerts at once. If false, the filter processes alerts one by one.

func (*BaseFilter) Disabled 

func (b *BaseFilter) Disabled() bool

Disabled returns true if the filter is disabled or inactive.

func (*BaseFilter) Dynamic 

func (b *BaseFilter) Dynamic() bool

Dynamic returns true if the filter is added dynamically.

func (*BaseFilter) Enable 

func (b *BaseFilter) Enable(e bool)

Enable enables the filter if e is true, otherwise disables the filter. If the filter is currently inactive and e is true, then the filter gets activated immediately.

func (*BaseFilter) Expired 

func (b *BaseFilter) Expired() bool

Expired returns true iff the filter has already been expired.

func (*BaseFilter) ID 

func (b *BaseFilter) ID() string

ID returns the ID of the filter.

func (*BaseFilter) If 

func (b *BaseFilter) If(a *Alert) (bool, error)

If evaluates an alert with "if" condition.

func (*BaseFilter) IfAll 

func (b *BaseFilter) IfAll(alerts []*Alert) (bool, error)

IfAll evaluates all alerts with "if" condition.

func (*BaseFilter) Inactivate 

func (b *BaseFilter) Inactivate(until time.Time)

Inactivate disables the filter until the given time. Calling Enable(true) immediately re-enables the filter.

func (*BaseFilter) Init 

func (b *BaseFilter) Init(id string, params map[string]interface{}) error

Init initializes BaseFilter with parameters.

Significant keys in params are: 

label    string    Arbitrary string label of the filter.
disabled bool      If true, this filter is disabled.
expire   string    RFC3339 format time at which this filter expires.
all      bool      If true, the filter process all alerts at once.
if       string | []string
                   string must be a JavaScript expression.
                   []string must be a command and arguments
                   to be invoked.
scripts  []string  JavaScript filenames.

func (*BaseFilter) Label 

func (b *BaseFilter) Label() string

Label returns the string label of the filter.

func (*BaseFilter) Reload 

func (b *BaseFilter) Reload() error

Reload reloads JavaScript files.

func (*BaseFilter) SetDynamic 

func (b *BaseFilter) SetDynamic()

SetDynamic sets the filter dynamic. This should be used privately inside kkok.

type Config 

type Config struct {
	// InitialInterval specifies the initial interval seconds
	// to pool posted alerts before procession.
	// Default is 30 (seconds).
	InitialInterval int `toml:"initial_interval"`

	// MaxInterval specifies the maximum interval seconds to
	// pool posted alerts.  The interval begins with InitialInterval
	// then doubles if one or more alerts are posted during the
	// interval until it reaches MaxInterval.
	//
	// The interval will return to InitialInterval if no alerts are
	// posted during the current interval.
	//
	// Default is 30 (seconds).
	MaxInterval int `toml:"max_interval"`

	// Addr is the listen address for HTTP API.
	//
	// Default is ":19898"
	Addr string `toml:"listen"`

	// APIToken is used for API authentication if not empty.
	//
	// Default is empty.
	APIToken string `toml:"api_token"`

	// Log from cybozu-go/cmd.
	Log cmd.LogConfig `toml:"log"`

	// Sources is a list of parameters to construct alert generators.
	Sources []PluginParams `toml:"source"`

	// Routes is a map between route ID and a list of transports.
	Routes map[string][]PluginParams `toml:"route"`

	// Filters is a list of parameters to construct filters.
	Filters []PluginParams `toml:"filter"`
}

Config is a struct to load TOML configuration file for kkok.

func NewConfig 

func NewConfig() *Config

NewConfig returns *Config with default settings.

func (*Config) InitialDuration 

func (c *Config) InitialDuration() time.Duration

InitialDuration returns the initial dispatch interval.

func (*Config) MaxDuration 

func (c *Config) MaxDuration() time.Duration

MaxDuration returns the maximum dispatch interval.

type Dispatcher 

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

Dispatcher accepts and pools alerts then dispatches them periodically.

func NewDispatcher 

func NewDispatcher(init, max time.Duration, handler AlertHandler) *Dispatcher

NewDispatcher creates Dispatcher. init and max is the initial and maximum duration between dispatches. handler handles pooled alerts. To start dispatching, invoke Run.

func (*Dispatcher) Post 

func (d *Dispatcher) Post(a *Alert)

Post puts an alert into the pool.

func (*Dispatcher) Run 

func (d *Dispatcher) Run(ctx context.Context) error

Run starts dispatching alerts until ctx is canceled. This method will always return nil.

type Filter 

type Filter interface {

	// Params returns PluginParams that can be used to construct
	// this filter.
	Params() PluginParams

	// Process applies the filter for all alerts and returns
	// the filtered alerts.
	Process(alerts []*Alert) ([]*Alert, error)

	// ID returns the ID of the filter.
	ID() string

	// Label returns the string label of the filter.
	Label() string

	// Dynamic returns true if the filter is added dynamically.
	Dynamic() bool

	// SetDynamic sets the filter dynamic.
	// This should be used privately inside kkok.
	SetDynamic()

	// Disabled returns true if the filter is disabled or inactive.
	Disabled() bool

	// Enable enables the filter if e is true, otherwise disables the filter.
	// If the filter is currently inactive and e is true, then the filter
	// gets activated immediately.
	Enable(e bool)

	// Inactivate disables the filter until the given time.
	// Calling Enable(true) immediately re-enables the filter.
	Inactivate(until time.Time)

	// Expired returns true iff the filter has already been expired.
	Expired() bool

	// Reload reloads JavaScript files.
	Reload() error
}

Filter is the interface that filter plugins must implement.

Methods other than Params and Process are implemented in BaseFilter so that a filter implementation can embed BaseFilter to provide them.

func NewFilter 

func NewFilter(typ string, params map[string]interface{}) (Filter, error)

NewFilter constructs a Filter.

type FilterConstructor 

type FilterConstructor func(id string, params map[string]interface{}) (Filter, error)

FilterConstructor is a function signature for filter construction.

id should be passed to BaseFilter.Init. params may be used to initialize the filter.

type Kkok 

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

Kkok is the struct to compose kkok.

Internal APIs to work on generators/routes/filters are provided by this.

func NewKkok 

func NewKkok() *Kkok

NewKkok constructs a new empty Kkok.

func (*Kkok) AddRoute 

func (k *Kkok) AddRoute(id string, route []Transport) error

AddRoute adds or replaces a route with id.

func (*Kkok) AddStaticFilter 

func (k *Kkok) AddStaticFilter(filter Filter) error

AddStaticFilter adds a filter statically.

func (*Kkok) Filters 

func (k *Kkok) Filters() []Filter

Filters return a snapshot of the current filters.

func (*Kkok) Handle 

func (k *Kkok) Handle(alerts []*Alert)

Handle implements AlertHandler interface.

func (*Kkok) PutFilter 

func (k *Kkok) PutFilter(filter Filter)

PutFilter adds or replaces a filter with filter.ID().

func (*Kkok) RouteIDs 

func (k *Kkok) RouteIDs() []string

RouteIDs return a slice of route IDs.

type PluginParams 

type PluginParams struct {
	Type   string
	Params map[string]interface{}
}

PluginParams is used to construct plugins including filters and transports.

func (PluginParams) MarshalJSON 

func (t PluginParams) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*PluginParams) UnmarshalJSON 

func (t *PluginParams) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

func (*PluginParams) UnmarshalTOML 

func (t *PluginParams) UnmarshalTOML(i interface{}) error

UnmarshalTOML is to load PluginParams from TOML file.

type Source 

type Source interface {

	// Run the generator until ctx.Done() is canceled.
	// Use post to post the generated alerts.
	Run(ctx context.Context, post func(*Alert)) error
}

Source is the interface that generators must implement.

func NewSource 

func NewSource(typ string, params map[string]interface{}) (Source, error)

NewSource constructs a Source.

type SourceConstructor 

type SourceConstructor func(params map[string]interface{}) (Source, error)

SourceConstructor is a function signature for source construction.

type Transport 

type Transport interface {

	// Params returns PluginParams that can be used to construct
	// this transport.
	Params() PluginParams

	// String should return a descriptive one-line string of the transport.
	String() string

	// Deliver alerts via the transport.
	//
	// The transport may merge alerts into one, or may deliver
	// alerts one by one.
	Deliver(alerts []*Alert) error
}

Transport is the interface that transport plugins must implement.

func NewTransport 

func NewTransport(typ string, params map[string]interface{}) (Transport, error)

NewTransport constructs a Transport.

type TransportConstructor 

type TransportConstructor func(params map[string]interface{}) (Transport, error)

TransportConstructor is a function signature for transport construction.

type VM 

type VM struct {
	*otto.Otto
}

VM wraps otto JavaScript engine to provide convenient methods.

func NewVM 

func NewVM() VM

NewVM creates a new JavaScript virtual machine.

func (VM) EvalAlert 

func (vm VM) EvalAlert(a *Alert, s *otto.Script) (otto.Value, error)

EvalAlert evaluates a JavaScript script. Before evaluation, a is assigned to "alert" variable. This will not alter any VM state.

func (VM) EvalAlerts 

func (vm VM) EvalAlerts(alerts []*Alert, s *otto.Script) (otto.Value, error)

EvalAlerts evaluates a JavaScript script. Before evaluation, alerts are assigned to "alerts" variable. This will not alter any VM state.

func (VM) Load 

func (vm VM) Load(filenames []string) error

Load reads JavaScript files and executes them. This alters VM states for later use.

Source Files

View all Source files

Directories

Path Synopsis
cmd
kkok
kkokc
plugins
filters/all
Package all imports all filters to be compiled-in.
 Package all imports all filters to be compiled-in.
filters/discard
Package discard provides a filter to eliminate alerts matching given conditions.
 Package discard provides a filter to eliminate alerts matching given conditions.
filters/edit
Package edit provides a filter to edit alerts by JavaScript.
 Package edit provides a filter to edit alerts by JavaScript.
filters/exec
Package exec provides a filter to edit alerts by an external command.
 Package exec provides a filter to edit alerts by an external command.
filters/freq
Package freq provides a filter to calculate frequency of the given alerts.
 Package freq provides a filter to calculate frequency of the given alerts.
filters/group
Package group provides a filter to merge alerts into groups.
 Package group provides a filter to merge alerts into groups.
filters/route
Package route provides a filter to add or replace routes.
 Package route provides a filter to add or replace routes.
sources/all
Package all imports all sources to be compiled-in.
 Package all imports all sources to be compiled-in.
sources/maildir
Package maildir reads mails in a Maildir directory to generate alerts.
 Package maildir reads mails in a Maildir directory to generate alerts.
transports/all
Package all imports all static transport plugins.
 Package all imports all static transport plugins.
transports/email
Package email provides a transport to send alerts as emails.
 Package email provides a transport to send alerts as emails.
transports/exec
Package exec provides a transport to send alerts via external commands.
 Package exec provides a transport to send alerts via external commands.
transports/slack
Package slack provides a transport to send alerts to Slack.
 Package slack provides a transport to send alerts to Slack.
transports/twilio
Package twilio provides a transport to send alerts via SMS using Twilio.
 Package twilio provides a transport to send alerts via SMS using Twilio.
Package util provides utility functions to lookup and convert parameter values from map[string]interface{}.
 Package util provides utility functions to lookup and convert parameter values from map[string]interface{}.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.