alertnotification

README

Send Alert Notifications for Go Errors.
Notify when new error arrives.

Throttle notifications to avoid overwhelming your inbox.
Supports multiple Emails, MS Teams and proxy support.

Usage

go install github.com/rakutentech/go-alertnotification@latest

Configurations

This package use golang env variables as settings.

General Configs

Env Variable	default	Description
APP_ENV		application environment to be appeared in email/teams message
APP_NAME		application name to be appeared in email/teams message

Email Configs

Env Variable	default	Description
EMAIL_SENDER		required sender email address
EMAIL_RECEIVERS		required receiver email addresses. Eg. test1@gmail.com,test2@gmail.com
EMAIL_ALERT_ENABLED	false	change to "true" to enable
SMTP_HOST		SMTP server hostname
SMTP_PORT		SMTP server port
EMAIL_USERNAME		SMTP username
EMAIL_PASSWORD		SMTP password

Ms Teams Configs

Env Variable	default	Description
MS_TEAMS_WEBHOOK		required Ms Teams webhook.
MS_TEAMS_ALERT_ENABLED	false	change to "true" to enable
MS_TEAMS_CARD_SUBJECT		MS teams card subject
ALERT_CARD_SUBJECT		Alert MessageCard subject
ALERT_THEME_COLOR		Themes color
MS_TEAMS_PROXY_URL		Work behind corporate proxy

Throttling Configs

Env Variable	default	Explanation
THROTTLE_DURATION	7	throttling duration in minutes
THROTTLE_GRACE_SECONDS	0	throttling grace in seconds
THROTTLE_DISKCACHE_DIR	/tmp/cache/{APP_NAME}_throttler_disk_cache	disk location for throttling
THROTTLE_ENABLED	true	Disable all together

Usage

Simple

 //import
 import n "github.com/rakutentech/go-alertnotification"
 err := errors.New("Alert me")
 ignoringErrs := []error{errors.New("Ignore 001"), errors.New("Ignore 002")};

 //Create New Alert
 alert := n.NewAlert(err, ignoringErrs)
 //Send notification
 alert.Notify()

With customized fields

 import n "github.com/rakutentech/go-alertnotification"

 //Create expandos, can keep the field value as configured by removing that field from expandos
 expandos := &n.Expandos{
        EmailBody:                  "This is the customized email body",
        EmailSubject:               "This is the customized email subject",
        MsTeamsCardSubject:         "This is the customized MS Teams card summary",
        MsTeamsAlertCardSubject:    "This is the customized MS Teams card title",
        MsTeamsError:               "This is the customized MS Teams card error message",
 }

 //Create New Alert
 alert := n.NewAlertWithExpandos(err, ignoringErr, expandos)

 //Send notification
 alert.Notify()

 // To remove all current throttling
 alert.RemoveCurrentThrotting()

Documentation

Index

• func DoSendNotification(alert AlertNotification) error
• type Alert
  • func NewAlert(err error, doNotAlertErrors []error) Alert
  • func NewAlertWithExpandos(err error, doNotAlertErrors []error, expandos *Expandos) Alert
  • func (a *Alert) Notify() (err error)
  • func (a *Alert) RemoveCurrentThrotting() error
• type AlertNotification
• type EmailConfig
  • func NewEmailConfig(err error, expandos *Expandos) EmailConfig
  • func (ec *EmailConfig) Send() error
• type ErrorOccurrence
• type Expandos
• type FactStruct
• type MsTeam
  • func NewMsTeam(err error, expandos *Expandos) MsTeam
  • func (card *MsTeam) Send() (err error)
• type SectionStruct
• type Throttler
  • func NewThrottler() Throttler
  • func (t *Throttler) CleanThrottlingCache() (err error)
  • func (t *Throttler) InitGrace(errObj error) []byte
  • func (t *Throttler) IsThrottledOrGraced(ocError error) bool
  • func (t *Throttler) ThrottleError(errObj error) error

Functions

func DoSendNotification

func DoSendNotification(alert AlertNotification) error

DoSendNotification is to send the alert to the specified implemenation of the AlertNoticication interface

Types

type Alert

type Alert struct {
	Error            error
	DoNotAlertErrors []error
	Expandos         *Expandos
}

Alert struct for specify the ignoring error and the occuring error

func NewAlert

func NewAlert(err error, doNotAlertErrors []error) Alert

NewAlert creates Alert struct instance

func NewAlertWithExpandos

func NewAlertWithExpandos(err error, doNotAlertErrors []error, expandos *Expandos) Alert

NewAlertWithExpandos creates Alert struct instance with expandos

func (*Alert) Notify

func (a *Alert) Notify() (err error)

Notify send and do throttling when error occur

func (*Alert) RemoveCurrentThrotting

func (a *Alert) RemoveCurrentThrotting() error

RemoveCurrentThrotting remove all current throttlings.

type AlertNotification

type AlertNotification interface {
	Send() error
}

AlertNotification is interface that all send notification function satify including send email

type EmailConfig

type EmailConfig struct {
	Username     string
	Password     string
	Host         string
	Port         string
	Sender       string
	EnvelopeFrom string
	Receivers    []string // Can use comma for multiple email
	Subject      string
	ErrorObj     error
	Expandos     *Expandos // can modify mail subject and content on demand
}

EmailConfig is email setting struct

func NewEmailConfig

func NewEmailConfig(err error, expandos *Expandos) EmailConfig

NewEmailConfig create new EmailConfig struct

func (*EmailConfig) Send

func (ec *EmailConfig) Send() error

Send Alert email

type ErrorOccurrence

type ErrorOccurrence struct {
	StartTime time.Time
	ErrorType error
}

ErrorOccurrence store error time and error

type Expandos

type Expandos struct {
	EmailBody               string
	EmailSubject            string
	MsTeamsAlertCardSubject string
	MsTeamsCardSubject      string
	MsTeamsError            string
}

Expandos struct for body and subject

type FactStruct

type FactStruct struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

FactStruct is sub-struct of SectionStruct

type MsTeam

type MsTeam struct {
	Type       string          `json:"@type"`
	Context    string          `json:"@context"`
	Summary    string          `json:"summary"`
	ThemeColor string          `json:"themeColor"`
	Title      string          `json:"title"`
	Sections   []SectionStruct `json:"sections"`
}

MsTeam is MessageCard for Team notification

func NewMsTeam

func NewMsTeam(err error, expandos *Expandos) MsTeam

NewMsTeam is used to create MsTeam

func (*MsTeam) Send

func (card *MsTeam) Send() (err error)

Send is implementation of interface AlertNotification's Send()

type SectionStruct

type SectionStruct struct {
	ActivityTitle    string       `json:"activityTitle"`
	ActivitySubtitle string       `json:"activitySubtitle"`
	ActivityImage    string       `json:"activityImage"`
	Facts            []FactStruct `json:"facts"`
}

SectionStruct is sub-struct of MsTeam

type Throttler

type Throttler struct {
	CacheOpt         string
	ThrottleDuration int
	GraceDuration    int
}

Throttler struct storing disckage directory and Throttling duration

func NewThrottler

func NewThrottler() Throttler

NewThrottler constructs new Throttle struct and init diskcache directory

func (*Throttler) CleanThrottlingCache

func (t *Throttler) CleanThrottlingCache() (err error)

CleanThrottlingCache clean all the diskcache in throttling cache directory

func (*Throttler) InitGrace

func (t *Throttler) InitGrace(errObj error) []byte

ThrottleError throttle the alert within the limited duration

func (*Throttler) IsThrottledOrGraced

func (t *Throttler) IsThrottledOrGraced(ocError error) bool

IsThrottled checks if the error has been throttled. If not, throttle it

func (*Throttler) ThrottleError

func (t *Throttler) ThrottleError(errObj error) error

ThrottleError throttle the alert within the limited duration