ayd

Documentation

Overview

Ayd plugin library

Example (AlertPlugin)

args, err := ayd.ParseAlertPluginArgs()
if err != nil {
	fmt.Fprintln(os.Stderr, err)
	os.Exit(1)
}

logger := ayd.NewLogger(args.AlertURL)

// Fetch extra information from Ayd json API
aydURL, err := url.Parse(os.Getenv("AYD_URL"))
if err != nil {
	logger.Failure("failed to get Ayd URL")
	return
}
resp, err := ayd.Fetch(aydURL)
if err != nil {
	logger.Failure("failed to fetch status")
	return
}
incidents, err := resp.CurrentIncidents()
if err != nil {
	logger.Failure("failed to get current incidents")
	return
}

_ = incidents // you can use this extra inciden information

logger = logger.StartTimer() // start timer for measure time to send alert

// send alert to somewhere

logger.Healthy("alert sent")

Example (ProbePlugin)

args, err := ayd.ParseProbePluginArgs()
if err != nil {
	fmt.Fprintln(os.Stderr, err)
	os.Exit(1)
}

logger := ayd.NewLogger(args.TargetURL).StartTimer()

// check your target here
ok := true

if ok {
	logger.Healthy("target is healthy!")
} else {
	logger.Failure("target is down")
}

Index

• Variables
• type AlertPluginArgs
  • func ParseAlertPluginArgs() (AlertPluginArgs, error)
  • func ParseAlertPluginArgsFrom(args []string) (AlertPluginArgs, error)
• type Incident
• type Logger
  • func NewLogger(target *url.URL) Logger
  • func NewLoggerWithWriter(w io.Writer, target *url.URL) Logger
  • func (l Logger) Aborted(message string) error
  • func (l Logger) Failure(message string) error
  • func (l Logger) Healthy(message string) error
  • func (l Logger) Print(r Record) error
  • func (l Logger) StartTimer() Logger
  • func (l Logger) StopTimer() Logger
  • func (l Logger) Unknown(message string) error
  • func (l Logger) WithTarget(target *url.URL) Logger
  • func (l Logger) WithTime(startTime time.Time, latency time.Duration) Logger
• type ProbePluginArgs
  • func ParseProbePluginArgs() (ProbePluginArgs, error)
  • func ParseProbePluginArgsFrom(args []string) (ProbePluginArgs, error)
• type Record
  • func ParseRecord(s string) (Record, error)
  • func (r Record) String() string
• type Response
  • func Fetch(u *url.URL) (Response, error)
  • func (r Response) AllRecords() ([][]Record, error)
  • func (r Response) CurrentIncidents() ([]Incident, error)
  • func (r Response) IncidentHistory() ([]Incident, error)
  • func (r Response) RecordsOf(target *url.URL) ([]Record, error)
  • func (r Response) Targets() ([]*url.URL, error)
• type Status
  • func ParseStatus(raw string) Status
  • func (s Status) MarshalText() ([]byte, error)
  • func (s Status) String() string
  • func (s *Status) UnmarshalText(text []byte) error

Examples

• Package (AlertPlugin)
• Package (ProbePlugin)
• Fetch
• Logger
• Logger (SetExtraValues)
• Logger.Print
• Logger.StartTimer
• Logger.StopTimer
• Logger.WithTarget
• Logger.WithTime

Variables

var (
	// ErrEmptyTarget is the error means target URL of Record was empty
	ErrEmptyTarget = errors.New("the target URL is required")
)

var (
	ErrInvalidArgument = errors.New("invalid argument")
)

var (
	ErrNoSuchTarget = errors.New("no such target")
)

Types

type AlertPluginArgs

type AlertPluginArgs struct {
	AlertURL  *url.URL
	TargetURL *url.URL
	Status    Status
	CheckedAt time.Time
}

AlertPluginArgs is arguments for alert plugin

func ParseAlertPluginArgs

func ParseAlertPluginArgs() (AlertPluginArgs, error)

ParseAlertPluginArgs is get arguments for alert plugin

This function is shorthand of `ayd.ParseAlertPluginArgs(os.Args)`.

func ParseAlertPluginArgsFrom

func ParseAlertPluginArgsFrom(args []string) (AlertPluginArgs, error)

ParseAlertPluginArgsFrom is parse arguments for alert plugin

type Incident

type Incident struct {
	Target *url.URL

	Status Status

	Message string

	// CausedAt is the first detected time the target is unhealthy status
	CausedAt time.Time

	// ResolvedAt is the earliest time that detected the target back to healthy status
	ResolvedAt time.Time
}

Incident is a period of failure or unknown status that has the same status and message

type Logger

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

Logger is the logger for Ayd plugin

Example

target, _ := url.Parse("foobar:your-plugin-url")

logger := ayd.NewLogger(target)

logger.Healthy("hello world")

Example (SetExtraValues)

logger := ayd.NewLogger(nil)

// change target URL
target, _ := url.Parse("foobar:your-plugin-url")
logger = logger.WithTarget(target)

// set check time and latency of the target
startTime, _ := time.Parse(time.RFC3339, "2001-02-03T16:05:06+09:00")
latency := 123 * time.Millisecond
logger = logger.WithTime(startTime, latency)

// report target status with a message
logger.Healthy("target is healthy")
logger.Failure("target seems down")
logger.Unknown("failed to check, so target status is unknown")
logger.Aborted("the check was aborted by user or something")

Output:

2001-02-03T16:05:06+09:00	HEALTHY	123.000	foobar:your-plugin-url	target is healthy
2001-02-03T16:05:06+09:00	FAILURE	123.000	foobar:your-plugin-url	target seems down
2001-02-03T16:05:06+09:00	UNKNOWN	123.000	foobar:your-plugin-url	failed to check, so target status is unknown
2001-02-03T16:05:06+09:00	ABORTED	123.000	foobar:your-plugin-url	the check was aborted by user or something

func NewLogger

func NewLogger(target *url.URL) Logger

NewLogger makes new Logger

This is the shorthand to `ayd.NewLoggerWithWriter(os.Stdout, target)`.

func NewLoggerWithWriter

func NewLoggerWithWriter(w io.Writer, target *url.URL) Logger

NewLoggerWithWriter makes new Logger with a io.Writer

func (Logger) Aborted

func (l Logger) Aborted(message string) error

Aborted prints Aborted status record

Seealso StatusAborted.

func (Logger) Failure

func (l Logger) Failure(message string) error

Failure prints Failure status record

Seealso StatusFailure.

func (Logger) Healthy

func (l Logger) Healthy(message string) error

Healthy prints Healthy status record

Seealso StatusHealthy.

func (Logger) Print

func (l Logger) Print(r Record) error

Print prints a Record

Example

logger := ayd.NewLogger(nil)

logger.Print(ayd.Record{
	Target:    &url.URL{Scheme: "foo", Host: "bar"},
	Status:    ayd.StatusHealthy,
	CheckedAt: time.Date(2001, 2, 3, 16, 5, 6, 7, time.UTC),
	Message:   "hello world",
})

logger.Print(ayd.Record{
	Target:    &url.URL{Scheme: "foo", Host: "bar"},
	CheckedAt: time.Date(2001, 2, 3, 16, 5, 7, 0, time.UTC),
	Message:   "without status",
})

err := logger.Print(ayd.Record{
	CheckedAt: time.Date(2001, 2, 3, 16, 5, 8, 0, time.UTC),
	Message:   "without target",
})
fmt.Println("error:", err)

Output:

2001-02-03T16:05:06Z	HEALTHY	0.000	foo://bar	hello world
2001-02-03T16:05:07Z	UNKNOWN	0.000	foo://bar	without status
error: the target URL is required

func (Logger) StartTimer

func (l Logger) StartTimer() Logger

StartTimer makes new Logger that set start time as current time, and start timer for latency from now.

You can stop the timer with StopTimer method, or just call print method like Healthy or Failure.

Example

target, _ := url.Parse("foobar:your-plugin-url")

logger := ayd.NewLogger(target)

l := logger.StartTimer()
// check your target status
l.Healthy("hello world")

func (Logger) StopTimer

func (l Logger) StopTimer() Logger

StopTimer stops latency timer that started by StartTimer method, and makes new Logger with measured latency.

Example

target, _ := url.Parse("foobar:your-plugin-url")

logger := ayd.NewLogger(target)

l := logger.StartTimer()
// check your target status
l = l.StopTimer()

// do something, for example calculate result of the check

l.Healthy("hello world")

func (Logger) Unknown

func (l Logger) Unknown(message string) error

Unknown prints Unknown status record

Seealso StatusUnknown.

func (Logger) WithTarget

func (l Logger) WithTarget(target *url.URL) Logger

WithTarget makes new Logger with new target URL

Example

logger := ayd.NewLogger(nil)

target, _ := url.Parse("foobar:your-plugin-url")

logger.WithTarget(target).Healthy("hello world")

func (Logger) WithTime

func (l Logger) WithTime(startTime time.Time, latency time.Duration) Logger

WithTime makes new Logger with start time and latency value

Example

target, _ := url.Parse("foobar:your-plugin-url")

logger := ayd.NewLogger(target)

startTime, _ := time.Parse(time.RFC3339, "2001-02-03T16:05:06+09:00")
latency := 123 * time.Millisecond

logger.WithTime(startTime, latency).Healthy("hello world")

Output:

2001-02-03T16:05:06+09:00	HEALTHY	123.000	foobar:your-plugin-url	hello world

type ProbePluginArgs

type ProbePluginArgs struct {
	TargetURL *url.URL
}

ProbePluginArgs is arguments for probe plugin

func ParseProbePluginArgs

func ParseProbePluginArgs() (ProbePluginArgs, error)

ParseProbePluginArgs is get arguments for probe plugin

This function is shorthand of `ayd.ParseProbePluginArgs(os.Args)`.

func ParseProbePluginArgsFrom

func ParseProbePluginArgsFrom(args []string) (ProbePluginArgs, error)

ParseProbePluginArgsFrom is parse arguments for probe plugin

type Record

type Record struct {
	// CheckedAt is the time the check started
	CheckedAt time.Time

	Status Status

	Latency time.Duration

	Target *url.URL

	// Message is the reason of the status, or extra informations of the check
	Message string
}

Record is a record in Ayd log

func ParseRecord

func ParseRecord(s string) (Record, error)

ParseRecord is parse string as a Record row in the log

func (Record) String

func (r Record) String() string

String is make Result a string for row in the log

type Response

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

Response is a response from Ayd server

func Fetch

func Fetch(u *url.URL) (Response, error)

Fetch is fetch Ayd json API and returns Response

Example

aydURL, _ := url.Parse("http://localhost:9000")

// fetch status from Ayd server
resp, err := ayd.Fetch(aydURL)
if err != nil {
	panic(err)
}

// parse status of all targets
allRecords, err := resp.AllRecords()
if err != nil {
	panic(err)
}

// show targets status
for _, targetRecords := range allRecords {
	record := targetRecords[len(targetRecords)-1]
	fmt.Println(record.Target.String(), ":", record.Status)
}

func (Response) AllRecords

func (r Response) AllRecords() ([][]Record, error)

AllRecords returns Record history of all targets

func (Response) CurrentIncidents

func (r Response) CurrentIncidents() ([]Incident, error)

CurrentIncidents returns list of Incident that current causing

func (Response) IncidentHistory

func (r Response) IncidentHistory() ([]Incident, error)

IncidentHistory returns list of Incident that already resolved

If you want get current causing incidents, please use CurrentIncidents method.

func (Response) RecordsOf

func (r Response) RecordsOf(target *url.URL) ([]Record, error)

RecordsOf returns Record history of specified target by argument

func (Response) Targets

func (r Response) Targets() ([]*url.URL, error)

Targets returns target URLs that to status checking

type Status

type Status int8

Status is the status of target service

const (
	// StatusUnknown means UNKNOWN current status because failed to check the target status
	StatusUnknown Status = iota

	// StatusHealthy means success to status check and the target is HEALTHY
	StatusHealthy

	// StatusFailure means the target is in FAILURE, but status check is success
	StatusFailure

	// StatusAborted means the status check ABORTED because stop Ayd server
	StatusAborted
)

func ParseStatus

func ParseStatus(raw string) Status

ParseStatus is parse status string

If passed unsupported status, it will returns StatusUnknown

func (Status) MarshalText

func (s Status) MarshalText() ([]byte, error)

MarshalText is marshal Status as text

func (Status) String

func (s Status) String() string

String is make Status a string

func (*Status) UnmarshalText

func (s *Status) UnmarshalText(text []byte) error

UnmarshalText is unmarshal text as status

This function always returns nil. This parses as StatusUnknown instead of returns error if unsupported status passed.