README
¶
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:
- Generate alerts from sources.
- Collect and pool alerts for some duration.
- Edit/route collected alerts by filters.
- 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:
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
License
Authors & Contributors
- Yamamoto, Hirotaka @ymmt2005
Documentation
¶
Overview ¶
Package kkok provides fundamentals to compose kkok.
Index ¶
- Constants
- func CompileJS(s string) (*otto.Script, error)
- func NewHTTPServer(addr, apiToken string, k *Kkok, d *Dispatcher) (*well.HTTPServer, error)
- func RegisterFilter(typ string, ctor FilterConstructor)
- func RegisterSource(typ string, ctor SourceConstructor)
- func RegisterTransport(typ string, ctor TransportConstructor)
- type Alert
- type AlertHandler
- type BaseFilter
- func (b *BaseFilter) AddParams(m map[string]interface{})
- func (b *BaseFilter) All() bool
- func (b *BaseFilter) Disabled() bool
- func (b *BaseFilter) Dynamic() bool
- func (b *BaseFilter) Enable(e bool)
- func (b *BaseFilter) Expired() bool
- func (b *BaseFilter) ID() string
- func (b *BaseFilter) If(a *Alert) (bool, error)
- func (b *BaseFilter) IfAll(alerts []*Alert) (bool, error)
- func (b *BaseFilter) Inactivate(until time.Time)
- func (b *BaseFilter) Init(id string, params map[string]interface{}) error
- func (b *BaseFilter) Label() string
- func (b *BaseFilter) Reload() error
- func (b *BaseFilter) SetDynamic()
- type Config
- type Dispatcher
- type Filter
- type FilterConstructor
- type Kkok
- type PluginParams
- type Source
- type SourceConstructor
- type Transport
- type TransportConstructor
- type VM
Constants ¶
const (
// Version is a constant string of the kkok version.
Version = "0.1.0"
)
Variables ¶
This section is empty.
Functions ¶
func CompileJS ¶
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) (*well.HTTPServer, error)
NewHTTPServer returns *well.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.
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) 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) 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/well.
Log well.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 (*Config) InitialDuration ¶
InitialDuration returns the initial dispatch interval.
func (*Config) MaxDuration ¶
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.
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.
type FilterConstructor ¶
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 (*Kkok) AddStaticFilter ¶
AddStaticFilter adds a filter statically.
type PluginParams ¶
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.
type SourceConstructor ¶
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.
type TransportConstructor ¶
TransportConstructor is a function signature for transport construction.
type VM ¶
VM wraps otto JavaScript engine to provide convenient methods.
func (VM) EvalAlert ¶
EvalAlert evaluates a JavaScript script. Before evaluation, a is assigned to "alert" variable. This will not alter any VM state.
func (VM) EvalAlerts ¶
EvalAlerts evaluates a JavaScript script. Before evaluation, alerts are assigned to "alerts" variable. This will not alter any VM state.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
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{}. |