icinga2

package
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Jul 29, 2024 License: GPL-2.0 Imports: 31 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// Acknowledgement* consts are describing an acknowledgement, e.g., from HostServiceRuntimeAttributes.
	AcknowledgementNone   = 0
	AcknowledgementNormal = 1
	AcknowledgementSticky = 2

	// EntryType* consts are describing an entry_type, e.g., from Comment.
	EntryTypeUser            = 1
	EntryTypeDowntime        = 2
	EntryTypeFlapping        = 3
	EntryTypeAcknowledgement = 4

	// StateHost* consts are describing a host state, e.g., from CheckResult.
	StateHostUp   = 0
	StateHostDown = 1

	// StateService* consts are describing a service state, e.g., from CheckResult.
	StateServiceOk       = 0
	StateServiceWarning  = 1
	StateServiceCritical = 2
	StateServiceUnknown  = 3

	// StateType* consts are describing a state type, e.g., from HostServiceRuntimeAttributes.
	StateTypeSoft = 0
	StateTypeHard = 1
)

The following const values are representing constant integer values, e.g., 0 for an OK state service.

Variables

This section is empty.

Functions

func UnmarshalEventStreamResponse 

func UnmarshalEventStreamResponse(bytes []byte) (any, error)

UnmarshalEventStreamResponse unmarshal a JSON response line from the Icinga 2 API Event Stream.

The function expects an Icinga 2 API Event Stream Response in its JSON form and tries to unmarshal it into one of the implemented types based on its type argument. Thus, the returned any value will be a pointer to such a struct type.

Types

type Acknowledgement 

type Acknowledgement struct {
	Timestamp UnixFloat `json:"timestamp"`
	Host      string    `json:"host"`
	Service   string    `json:"service"`
	State     int       `json:"state"`
	StateType int       `json:"state_type"`
	Author    string    `json:"author"`
	Comment   string    `json:"comment"`
	EventType string    `json:"type"`
}

Acknowledgement represents the Icinga 2 API Event Stream AcknowledgementSet or AcknowledgementCleared response for acknowledgements set/cleared on/from hosts/services.

NOTE:

  • An empty Service field indicates a host acknowledgement.
  • State might be StateHost{Up,Down} for hosts or StateService{Ok,Warning,Critical,Unknown} for services.
  • StateType might be StateTypeSoft or StateTypeHard.
  • EventType is either set to typeAcknowledgementSet or typeAcknowledgementCleared.
  • Author and Comment fields are always empty when EventType is set to typeAcknowledgementCleared.

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#event-stream-type-acknowledgementset https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#event-stream-type-acknowledgementcleared

type CheckResult 

type CheckResult struct {
	ExitStatus     int       `json:"exit_status"`
	Output         string    `json:"output"`
	State          int       `json:"state"`
	ExecutionStart UnixFloat `json:"execution_start"`
	ExecutionEnd   UnixFloat `json:"execution_end"`
}

CheckResult represents the Icinga 2 API CheckResult object.

https://icinga.com/docs/icinga-2/latest/doc/08-advanced-topics/#advanced-value-types-checkresult

func (*CheckResult) MarshalLogObject 

func (cr *CheckResult) MarshalLogObject(encoder zapcore.ObjectEncoder) error

MarshalLogObject implements the zapcore.ObjectMarshaler interface.

type Client 

type Client struct {
	// ApiBaseURL et al. configure where and how the Icinga 2 API can be reached.
	ApiBaseURL       string
	ApiBasicAuthUser string
	ApiBasicAuthPass string

	// ApiHttpTransport is a shared http.Transport and http.RoundTripper for all API connections, set by the Launcher.
	ApiHttpTransport http.RoundTripper

	// ApiTimeout specifies the timeout for API connections outside the Event Stream API.
	//
	// If set to 0 or no value was explicitly configured, its value will be raised to 1m within Client.Process.
	//
	// Depending on both the Icinga 2 server power and the amount of objects to be queried, the initial flood of
	// request might take a bit longer. However, one minute is still a very huge time which shouldn't be reached
	// for most setups unless the system is under immense stress or other issues are also present.
	ApiTimeout time.Duration

	// EventSourceId to be reflected in generated event.Events.
	EventSourceId int64
	// IcingaWebRoot points to the Icinga Web 2 endpoint for generated URLs.
	IcingaWebRoot string

	// CallbackFn receives generated event.Event objects.
	CallbackFn func(*event.Event)
	// Ctx for all web requests as well as internal wait loops. The CtxCancel can be used to stop this Client.
	// Both fields are being populated with a new context from the NewClientFromConfig function.
	Ctx       context.Context
	CtxCancel context.CancelFunc
	// Logger to log to.
	Logger *zap.SugaredLogger
	// contains filtered or unexported fields
}

Client for the Icinga 2 Event Stream API with support for other Icinga 2 APIs to gather additional information and perform a catch-up of unknown events either when starting up to or in case of a connection loss.

Within the icinga-notifications scope, one or multiple Client instances can be generated by the Launcher.

A Client must be started by calling its Process method, which blocks until Ctx is marked as done. Reconnections and the necessary state replaying in an internal catch-up-phase from the Icinga 2 API will be taken care off. Internally, the Client executes a worker within its own goroutine, which dispatches event.Event to the CallbackFn and enforces order during catching up after (re-)connections.

func (*Client) Process 

func (client *Client) Process()

Process incoming events and reconnect to the Event Stream with catching up on missed objects if necessary.

This method blocks as long as the Client runs, which, unless Ctx is cancelled, is forever. While its internal loop takes care of reconnections, messages are being logged while generated event.Event will be dispatched to the CallbackFn function.

type Comment 

type Comment struct {
	Host      string    `json:"host_name"`
	Service   string    `json:"service_name"`
	Author    string    `json:"author"`
	Text      string    `json:"text"`
	EntryTime UnixFloat `json:"entry_time"`
	EntryType int       `json:"entry_type"`
}

Comment represents the Icinga 2 API Comment object.

NOTE:

  • An empty Service field indicates a host comment.
  • The optional EntryType should be represented by one of the EntryType* consts.

https://icinga.com/docs/icinga-2/latest/doc/09-object-types/#objecttype-comment

type CommentAdded 

type CommentAdded struct {
	Timestamp UnixFloat `json:"timestamp"`
	Comment   Comment   `json:"comment"`
}

CommentAdded represents the Icinga 2 API Event Stream CommentAdded response for added host/service comments.

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#event-stream-type-commentadded

type CommentRemoved 

type CommentRemoved struct {
	Timestamp UnixFloat `json:"timestamp"`
	Comment   Comment   `json:"comment"`
}

CommentRemoved represents the Icinga 2 API Event Stream CommentRemoved response for removed host/service comments.

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#event-stream-type-commentremoved

type Downtime 

type Downtime struct {
	Host        string `json:"host_name"`
	Service     string `json:"service_name"`
	Author      string `json:"author"`
	Comment     string `json:"comment"`
	ConfigOwner string `json:"config_owner"`

	// RemoveTime is used to indicate whether a downtime was ended automatically or cancelled prematurely by a user.
	// It is set to zero time for the former case, otherwise to the timestamp at which time has been cancelled.
	RemoveTime UnixFloat `json:"remove_time"`

	// IsFixed is used to differentiate between fixed and flexible downtimes.
	// Fixed downtimes always emits a start and triggered event and cause two notifications being sent
	// for the very (same) event. Flexible downtimes, on the other hand, only emits a trigger event, and
	// don't produce duplicates for the same event.
	IsFixed bool `json:"fixed"`
}

Downtime represents the Icinga 2 API Downtime object.

NOTE:

  • An empty Service field indicates a host downtime.
  • If a downtime was added by a ScheduledDowntime object, ConfigOwner is set to the name of that object and can only be cancelled by its owner. Otherwise, it is empty and indicates user-created downtimes (via API or/and UI).

https://icinga.com/docs/icinga-2/latest/doc/09-object-types/#objecttype-downtime

func (*Downtime) MarshalLogObject 

func (d *Downtime) MarshalLogObject(encoder zapcore.ObjectEncoder) error

MarshalLogObject implements the zapcore.ObjectMarshaler interface.

func (*Downtime) WasCancelled 

func (d *Downtime) WasCancelled() bool

WasCancelled returns true when the current downtime was cancelled prematurely by a user.

type DowntimeAdded 

type DowntimeAdded struct {
	Timestamp UnixFloat `json:"timestamp"`
	Downtime  Downtime  `json:"downtime"`
}

DowntimeAdded represents the Icinga 2 API Event Stream DowntimeAdded response for added downtimes on host/services.

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#event-stream-type-downtimeadded

type DowntimeRemoved 

type DowntimeRemoved struct {
	Timestamp UnixFloat `json:"timestamp"`
	Downtime  Downtime  `json:"downtime"`
}

DowntimeRemoved represents the Icinga 2 API Event Stream DowntimeRemoved response for removed downtimes on host/services.

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#event-stream-type-commentremoved

type DowntimeStarted 

type DowntimeStarted struct {
	Timestamp UnixFloat `json:"timestamp"`
	Downtime  Downtime  `json:"downtime"`
}

DowntimeStarted represents the Icinga 2 API Event Stream DowntimeStarted response for started downtimes on host/services.

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#event-stream-type-downtimestarted

type DowntimeTriggered 

type DowntimeTriggered struct {
	Timestamp UnixFloat `json:"timestamp"`
	Downtime  Downtime  `json:"downtime"`
}

DowntimeTriggered represents the Icinga 2 API Event Stream DowntimeTriggered response for triggered downtimes on host/services.

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#event-stream-type-downtimetriggered

type Flapping 

type Flapping struct {
	Timestamp       UnixFloat `json:"timestamp"`
	Host            string    `json:"host"`
	Service         string    `json:"service"`
	IsFlapping      bool      `json:"is_flapping"`
	State           int       `json:"state"`
	CurrentFlapping int       `json:"current_flapping"`
	ThresholdLow    int       `json:"threshold_low"`
	ThresholdHigh   int       `json:"threshold_high"`
}

Flapping represents the Icinga 2 API Event Stream Flapping response for flapping host/services.

NOTE:

  • An empty Service field indicates a host being in flapping state.
  • State includes the current state of the Checkable at the point in time at which it enters or exits the flapping state.
  • CurrentFlapping indicates the current flapping value of a Checkable in percent.
  • ThresholdLow is the low/min flapping threshold value set by the user (CurrentFlapping < ThresholdLow = flapping end).
  • ThresholdHigh is the high/max flapping threshold value set by the user (CurrentFlapping > ThresholdHigh = flapping start).

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#event-stream-type-flapping

type HostServiceRuntimeAttributes 

type HostServiceRuntimeAttributes struct {
	Name                      string      `json:"name"`
	Host                      string      `json:"host_name,omitempty"`
	Groups                    []string    `json:"groups"`
	State                     int         `json:"state"`
	StateType                 int         `json:"state_type"`
	LastCheckResult           CheckResult `json:"last_check_result"`
	LastStateChange           UnixFloat   `json:"last_state_change"`
	DowntimeDepth             int         `json:"downtime_depth"`
	Acknowledgement           int         `json:"acknowledgement"`
	IsFlapping                bool        `json:"flapping"`
	AcknowledgementLastChange UnixFloat   `json:"acknowledgement_last_change"`
	EnableFlapping            bool        `json:"enable_flapping"`
}

HostServiceRuntimeAttributes are common attributes of both Host and Service objects.

When catching up potentially missed changes, the following fields are holding relevant changes which, fortunately, are identical for Icinga 2 Host and Service objects.

NOTE:

  • Name is either the Host or the Service name.
  • Host is empty for Host objects; Host contains the Service's Host object name for Services.
  • State might be StateHost{Up,Down} for hosts or StateService{Ok,Warning,Critical,Unknown} for services.
  • StateType might be StateTypeSoft or StateTypeHard.
  • Acknowledgement type might be acknowledgement{None,Normal,Sticky}.

https://icinga.com/docs/icinga-2/latest/doc/09-object-types/#host https://icinga.com/docs/icinga-2/latest/doc/09-object-types/#service

func (*HostServiceRuntimeAttributes) MarshalLogObject 

func (hsra *HostServiceRuntimeAttributes) MarshalLogObject(encoder zapcore.ObjectEncoder) error

MarshalLogObject implements the zapcore.ObjectMarshaler interface.

type IcingaApplication 

type IcingaApplication struct {
	App struct {
		EnableFlapping bool `json:"enable_flapping"`
	} `json:"app"`
}

IcingaApplication represents the Icinga 2 API status endpoint query result of type IcingaApplication. https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#status-and-statistics

type Launcher 

type Launcher struct {
	Ctx           context.Context
	Logs          *logging.Logging
	Db            *database.DB
	RuntimeConfig *config.RuntimeConfig
	// contains filtered or unexported fields
}

Launcher allows starting a new Icinga 2 Event Stream API Client through a callback from within the config package.

This architecture became kind of necessary to work around circular imports due to the RuntimeConfig's omnipresence.

func (*Launcher) Launch 

func (launcher *Launcher) Launch(src *config.Source)

Launch either directly launches an Icinga 2 Event Stream Client for this Source or enqueues it until the Launcher is Ready.

func (*Launcher) Ready 

func (launcher *Launcher) Ready()

Ready marks the Launcher as ready and launches all enqueued, postponed Sources.

type ObjectCreatedDeleted 

type ObjectCreatedDeleted struct {
	ObjectName string `json:"object_name"`
	ObjectType string `json:"object_type"`
	EventType  string `json:"type"`
}

ObjectCreatedDeleted represents the Icinga 2 API stream object created/deleted response.

NOTE:

  • The ObjectName field already contains the composed name of the checkable if the ObjectType is `Service`.
  • The EventType field indicates which event type is currently being streamed and is either set to typeObjectCreated or typeObjectDeleted.

type ObjectQueriesResult 

type ObjectQueriesResult[T Comment | Downtime | HostServiceRuntimeAttributes] struct {
	Name  string `json:"name"`
	Type  string `json:"type"`
	Attrs T      `json:"attrs"`
}

ObjectQueriesResult represents the Icinga 2 API Object Queries Result wrapper object.

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#object-queries-result

type StateChange 

type StateChange struct {
	Timestamp       UnixFloat   `json:"timestamp"`
	Host            string      `json:"host"`
	Service         string      `json:"service"`
	State           int         `json:"state"`
	StateType       int         `json:"state_type"`
	CheckResult     CheckResult `json:"check_result"`
	DowntimeDepth   int         `json:"downtime_depth"`
	Acknowledgement bool        `json:"acknowledgement"`
}

StateChange represents the Icinga 2 API Event Stream StateChange response for host/service state changes.

NOTE:

  • An empty Service field indicates a host state change.
  • State might be StateHost{Up,Down} for hosts or StateService{Ok,Warning,Critical,Unknown} for services.
  • StateType might be StateTypeSoft or StateTypeHard.

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#event-stream-type-statechange

func (*StateChange) MarshalLogObject 

func (sc *StateChange) MarshalLogObject(encoder zapcore.ObjectEncoder) error

MarshalLogObject implements the zapcore.ObjectMarshaler interface.

type UnixFloat 

type UnixFloat time.Time

UnixFloat is a custom time.Time type for millisecond Unix timestamp, as used in Icinga 2's API.

func (*UnixFloat) Time 

func (t *UnixFloat) Time() time.Time

Time returns the time.Time of UnixFloat.

func (*UnixFloat) UnmarshalJSON 

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

Source Files

View all Source files

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.