Documentation
¶
Overview ¶
Package source implements an Icinga Notifications source to send events to the Icinga Notifications API.
To create a new source, start by creating a new Client. Then, for each event you want to forward to Icinga Notifications, call Client.ProcessEvent. This method forwards the event to the Icinga Notifications API and reports further information, such as outdated rules.
Index ¶
- Constants
- Variables
- type Client
- func (client *Client) GetIncidents(ctx context.Context, filter any) ([]Incident, error)
- func (client *Client) GetNotificationHistory(ctx context.Context, filter any, since int64) ([]NotificationHistory, error)
- func (client *Client) ModifyIncidents(ctx context.Context, attrs ModifiableIncidentAttrs, filter any) error
- func (client *Client) ProcessEvent(ctx context.Context, ev *event.Event, rejectIncomplete bool) ([]string, error)
- func (client *Client) YieldIncidents(ctx context.Context, filter any) (<-chan Incident, <-chan error)
- func (client *Client) YieldNotificationHistory(ctx context.Context, filter any, since int64) (<-chan NotificationHistory, <-chan error)
- type Config
- type ErrorState
- type Incident
- type ModifiableIncidentAttrs
- type ModifiedIncidentResp
- type ModifyError
- type NotificationHistory
- type Response
Constants ¶
const ( // ResponseStatusSuccess indicates a successful response from the Icinga Notifications API. ResponseStatusSuccess = "success" // ResponseStatusError indicates an error response from the Icinga Notifications API. ResponseStatusError = "error" )
Variables ¶
var ( // ErrAttrsNegotiation implies missing attributes. ErrAttrsNegotiation = stderrors.New("attribute negotiation required") ErrUnauthorizedRequest = stderrors.New("unauthorized request") // ErrReadPartialResp indicates that a partial response was received from the API, which may require special handling. ErrReadPartialResp = stderrors.New("read partial response") )
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client provides a common interface to interact with the Icinga Notifications API.
It stores the configuration for the API endpoint and holds a reusable HTTP client for requests. To create a Client, the NewClient function should be used.
func NewClient ¶
NewClient creates a new Client instance with the provided configuration.
The clientName argument is used as the User-Agent header in HTTP requests sent by this Client and should represent the project using this client, e.g., "Icinga DB v1.5.0".
It may return an error if the API base URL cannot be parsed.
func (*Client) GetIncidents ¶ added in v0.10.0
GetIncidents retrieves the current incidents of this source from the Icinga Notifications /v1/incidents API endpoint.
The filter parameter is used to filter the incidents returned by the API. It must be a non-nil value that can be marshaled to JSON. If filter is nil, an error is returned. Please refer to the Icinga Notifications API doc for details on the filter syntax and supported fields.
func (*Client) GetNotificationHistory ¶ added in v0.10.0
func (client *Client) GetNotificationHistory(ctx context.Context, filter any, since int64) ([]NotificationHistory, error)
GetNotificationHistory retrieves the notification history from the API for the specified time range.
The since parameter is a Unix timestamp in milliseconds that specifies the start of the time range for which to retrieve notification history entries. It must be a positive integer. If since is less than or equal to zero, an error is returned.
func (*Client) ModifyIncidents ¶ added in v0.10.0
func (client *Client) ModifyIncidents(ctx context.Context, attrs ModifiableIncidentAttrs, filter any) error
ModifyIncidents modifies the incidents that match the provided filter with the given attributes.
The filter parameter is used to select which incidents to modify. It must be a non-nil value that can be marshaled to JSON. If filter is nil, an error is returned. Please refer to the Icinga Notifications API doc for details on the filter syntax and supported fields.
If some matching incidents couldn't be modified, the function returns a ModifyError containing the details of the incidents that failed to be modified. The caller can inspect that error to determine and act up the erroneous incidents if needed.
func (*Client) ProcessEvent ¶
func (client *Client) ProcessEvent(ctx context.Context, ev *event.Event, rejectIncomplete bool) ([]string, error)
ProcessEvent submits an event.Event to the Icinga Notifications /v1/process-event API endpoint.
When rejectIncomplete is set and the returned error is ErrAttrsNegotiation, the first return parameter is an array of required attributes.
func (*Client) YieldIncidents ¶ added in v0.10.0
func (client *Client) YieldIncidents(ctx context.Context, filter any) (<-chan Incident, <-chan error)
YieldIncidents retrieves the current incidents of this source from the Icinga Notifications /v1/incidents endpoint and yields them as a stream of Incident objects.
The filter parameter is used to filter the incidents returned by the API. It must be a non-nil value that can be marshaled to JSON. If filter is nil, an error is returned. Please refer to the Icinga Notifications API doc for details on the filter syntax and supported fields.
The function returns a channel of Incident objects and a channel of errors. The caller should read from both channels until they are closed. If an error occurs during the request or while decoding the response, it will be sent to the error channel. Also, this might send ErrReadPartialResp to the error channel when something went wrong midstream in Icinga Notifications, and that will be the last thing sent to the error channel, after which no more incidents will be sent to the incident channel.
If you want to collect all incidents into a slice, consider using Client.GetIncidents instead, which internally uses this function and collects the incidents for you.
func (*Client) YieldNotificationHistory ¶ added in v0.10.0
func (client *Client) YieldNotificationHistory(ctx context.Context, filter any, since int64) (<-chan NotificationHistory, <-chan error)
YieldNotificationHistory retrieves the notification history from the API for the specified time range and yields them as a stream of NotificationHistory objects.
The since parameter is a Unix timestamp in milliseconds that specifies the start of the time range for which to retrieve notification history entries. It must be a positive integer. If since is less than or equal to zero, an error is returned.
The function returns a channel of NotificationHistory objects and a channel of errors. The caller should read from both channels until they are closed. If an error occurs during the request or while decoding the response, it will be sent to the error channel. Also, this might send ErrReadPartialResp to the error channel when it receives a notification history entry with a non-zero Error field from the API, which indicates that something went wrong after streaming the first chunk of the response body.
If you want to collect all notification history entries into a slice, consider using Client.GetNotificationHistory instead, which internally uses this function and collects the entries for you.
type Config ¶
type Config struct {
// Url of the Icinga Notifications API.
//
// A transport is chosen based on the URI scheme:
// - http: Unencrypted HTTP connection. Requires Username and Password/PasswordFile to be set.
// For example: http://example.com:5680
// - https: HTTPS connection. Either Username and Password/PasswordFile or TlsOptions.{Cert,Key} are required.
// For example: https://example.com:5680
// - unix: HTTP connection over a Unix Domain Socket. Authentication is based on the operating system user.
// So, Username or Password/PasswordFile must not be set. For example: unix:///path/to/socket
Url string `yaml:"url" env:"URL"`
// Icingaweb2Url is the base URL of the Icinga Web 2 setup in front of this source,
// e.g. "https://example.com/icingaweb2".
//
// A source resolves the object URL it transmits with each event against this base. Icinga Notifications
// hands that URL to the notified contacts and cannot complete a relative reference by itself, so it has
// to be absolute. If left empty, the source submits its events without an object URL.
Icingaweb2Url string `yaml:"icingaweb2_url" env:"ICINGAWEB2_URL"`
// Username is the API user for the Icinga Notifications API.
//
// Based on the Config.Url scheme, Username and Password/PasswordFile are either required, allowed, or forbidden.
Username string `yaml:"username" env:"USERNAME"`
// Password is the API user's password for the Icinga Notifications API.
Password string `yaml:"password" env:"PASSWORD,unset"` // #nosec G117 -- exported password field
PasswordFile string `yaml:"password_file" env:"PASSWORD_FILE"`
// TlsOptions are relevant for the "https" Url scheme.
TlsOptions config.TLS `yaml:",inline"`
// DefaultRelations to always resolve and include in the events submitted to Icinga Notifications.
DefaultRelations []string `yaml:"default_relations" env:"DEFAULT_RELATIONS"`
// Icingaweb2UrlParsed holds the parsed Icingaweb2Url after validation of the config.
//
// This field is not part of the YAML config and is only populated after successful validation.
// The resulting URL always ends with a trailing slash, making it easier to resolve relative paths against it.
Icingaweb2UrlParsed *url.URL
}
Config defines all configuration for the Icinga Notifications API Client.
type ErrorState ¶ added in v0.10.0
type ErrorState struct {
Error string `json:"error,omitempty"`
}
ErrorState represents an error state returned by the Icinga Notifications API as a Response.Result when the Response.Status is "error".
type Incident ¶ added in v0.10.0
type Incident struct {
IsMuted bool `json:"is_muted"`
ObjectTags map[string]string `json:"object_tags,omitempty"`
Severity event.Severity `json:"severity,omitempty"`
}
Incident represents an incident as returned by the Icinga Notifications /v1/incidents API endpoint as a Response.Result when the Response.Status is "success".
type ModifiableIncidentAttrs ¶ added in v0.10.0
type ModifiableIncidentAttrs struct {
Message types.String `json:"message,omitzero"`
Close types.Bool `json:"close,omitzero"`
}
ModifiableIncidentAttrs represents the attributes of an incident that can be modified via the /incident endpoint.
The Message field is a string that can be set to update the incident's message. The Close field is a boolean that can only be set to true to close the incident. Setting Close to false is not allowed and will result in a validation error.
func (*ModifiableIncidentAttrs) Validate ¶ added in v0.10.0
func (attrs *ModifiableIncidentAttrs) Validate() error
Validate checks if the ModifiableIncidentAttrs struct has valid values for its fields.
type ModifiedIncidentResp ¶ added in v0.10.0
type ModifiedIncidentResp struct {
ObjectTags map[string]string `json:"object_tags,omitempty"`
ErrorState
}
ModifiedIncidentResp represents the response for a modified incident from the Icinga Notifications API as a Response.Result in both success and error cases. However, if Response.Status is "error", the ErrorState field will be populated with the error details, otherwise, it's omitted entirely.
It contains the ObjectTags of the modified incident.
type ModifyError ¶ added in v0.10.0
type ModifyError struct {
// contains filtered or unexported fields
}
ModifyError represents an error that occurred while modifying incidents via the /incident endpoint.
func (*ModifyError) Error ¶ added in v0.10.0
func (e *ModifyError) Error() string
Error implements the error interface for ModifyError.
func (*ModifyError) Results ¶ added in v0.10.0
func (e *ModifyError) Results() []ModifiedIncidentResp
Results returns the slice of ModifiedIncidentResp that contains the details of the incidents that failed to be modified.
type NotificationHistory ¶ added in v0.10.0
type NotificationHistory struct {
EventID types.UUID `json:"event_id"`
TriggeredAt types.UnixMilli `json:"triggered_at"`
ContactName types.String `json:"contact_name"`
ContactgroupName types.String `json:"contactgroup_name"`
ScheduleName types.String `json:"schedule_name"`
ChannelName string `json:"channel_name"`
EventMessage string `json:"event_message"`
EventSummary string `json:"event_summary"`
IncidentClosed types.Bool `json:"incident_closed"`
}
NotificationHistory represents a single entry in the notification history retrieved from the Icinga Notifications API.
The struct is designed to be used with JSON serialization and deserialization.
type Response ¶ added in v0.10.0
type Response[T any] struct { Status string `json:"status"` // success or error Result T `json:"result"` }
Response represents a generic response from the Icinga Notifications API.
The Status field indicates whether the request was successful or resulted in an error. The Result field contains the actual response data, which can be of any type T. If the request was successful, Result will contain the expected data, otherwise, contains the error state information.