nagios

ExampleBasicPluginStructure demonstrates the basic structure for a monitoring plugin that uses this package.

package main

import (
	"github.com/atc0005/go-nagios"
)

// Ignore this. This is just to satisfy the "whole file" example requirements
// per https://go.dev/blog/examples.
var _ = "https://github.com/atc0005/go-nagios"

// ExampleBasicPluginStructure demonstrates the basic structure for a
// monitoring plugin that uses this package.
func main() {
	// First, create an instance of the Plugin type. By default this value is
	// configured to indicate a successful execution. This should be
	// overridden by client code to indicate the final plugin state to Nagios
	// when the plugin exits.
	var plugin = nagios.NewPlugin()

	// Second, immediately defer ReturnCheckResults() so that it runs as the
	// last step in your client code. If you do not defer ReturnCheckResults()
	// immediately any other deferred functions in your client code will not
	// run.
	//
	// Avoid calling os.Exit() directly from your code. If you do, this
	// library is unable to function properly; this library expects that it
	// will handle calling os.Exit() with the required exit code (and
	// specifically formatted output).
	//
	// For handling error cases, the approach is roughly the same, only you
	// call return explicitly to end execution of the client code and allow
	// deferred functions to run.
	defer plugin.ReturnCheckResults()

	// more stuff here

	plugin.ServiceOutput = "one-line summary of plugin results "

	plugin.LongServiceOutput = "more detailed output from plugin here"
}

Output:

ExampleEmitPerformanceData demonstrates providing multiple plugin performance data values explicitly.

NOTE: While this example illustrates providing a time metric, this metric is provided for you if using the nagios.NewPlugin constructor. If specifying this value ourselves, *our* value takes precedence and the default value is ignored.

package main

import (
	"fmt"
	"log"
	"time"

	"github.com/atc0005/go-nagios"
)

// Ignore this. This is just to satisfy the "whole file" example requirements
// per https://go.dev/blog/examples.
var _ = "https://github.com/atc0005/go-nagios"

// ExampleEmitPerformanceData demonstrates providing multiple plugin
// performance data values explicitly.
//
// NOTE: While this example illustrates providing a time metric, this metric
// is provided for you if using the nagios.NewPlugin constructor. If
// specifying this value ourselves, *our* value takes precedence and the
// default value is ignored.
func main() {
	// Start the timer. We'll use this to emit the plugin runtime as a
	// performance data metric.
	//
	// NOTE: While this example illustrates providing a time metric, this
	// metric is provided for you if using the nagios.NewPlugin constructor.
	// If specifying this value ourselves, *our* value takes precedence and
	// the default value is ignored.
	pluginStart := time.Now()

	// First, create an instance of the Plugin type. Here we're opting to
	// manually construct the Plugin value instead of using the constructor
	// (mostly for contrast).
	//
	// We set the ExitStatusCode value to reflect a successful plugin
	// execution. If we do not alter the exit status code later this is what
	// will be reported to Nagios when the plugin exits.
	var plugin = nagios.Plugin{
		LastError:      nil,
		ExitStatusCode: nagios.StateOKExitCode,
	}

	// Second, immediately defer ReturnCheckResults() so that it runs as the
	// last step in your client code. If you do not defer ReturnCheckResults()
	// immediately any other deferred functions in your client code will not
	// run.
	//
	// Avoid calling os.Exit() directly from your code. If you do, this
	// library is unable to function properly; this library expects that it
	// will handle calling os.Exit() with the required exit code (and
	// specifically formatted output).
	//
	// For handling error cases, the approach is roughly the same, only you
	// call return explicitly to end execution of the client code and allow
	// deferred functions to run.
	defer plugin.ReturnCheckResults()

	pd := []nagios.PerformanceData{
		{
			// NOTE: This metric is provided by default if using the provided
			// nagios.NewPlugin constructor.
			//
			// If we specify this value ourselves, *our* value takes
			// precedence and the default value is ignored.
			Label: "time",
			Value: fmt.Sprintf("%dms", time.Since(pluginStart).Milliseconds()),
		},
		{
			Label: "datacenters",
			Value: fmt.Sprintf("%d", 2),
		},
		{
			Label: "triggered_alarms",
			Value: fmt.Sprintf("%d", 14),
		},
	}

	if err := plugin.AddPerfData(false, pd...); err != nil {
		log.Printf("failed to add performance data metrics: %v", err)
		plugin.Errors = append(plugin.Errors, err)

		// NOTE: You might wish to make this a "best effort" scenario and
		// proceed with plugin execution. In that case, don't return yet until
		// further data has been gathered.
		return
	}

	// more stuff here

	plugin.ServiceOutput = "one-line summary of plugin results "

	plugin.LongServiceOutput = "more detailed output from plugin here"
}

Output:

ExampleEmitPerformanceDataViaDeferredAnonymousFunc demonstrates emitting plugin performance data provided via a deferred anonymous function.

NOTE: While this example illustrates providing a time metric, this metric is provided for you if using the nagios.NewPlugin constructor. If specifying this value ourselves, *our* value takes precedence and the default value is ignored.

package main

import (
	"fmt"
	"log"
	"time"

	"github.com/atc0005/go-nagios"
)

// Ignore this. This is just to satisfy the "whole file" example requirements
// per https://go.dev/blog/examples.
var _ = "https://github.com/atc0005/go-nagios"

// ExampleEmitPerformanceDataViaDeferredAnonymousFunc demonstrates emitting
// plugin performance data provided via a deferred anonymous function.
//
// NOTE: While this example illustrates providing a time metric, this metric
// is provided for you if using the nagios.NewPlugin constructor. If specifying
// this value ourselves, *our* value takes precedence and the default value is
// ignored.
func main() {

	// Start the timer. We'll use this to emit the plugin runtime as a
	// performance data metric.
	//
	// NOTE: While this example illustrates providing a time metric, this
	// metric is provided for you if using the nagios.NewPlugin constructor.
	// If specifying this value ourselves, *our* value takes precedence and
	// the default value is ignored.
	pluginStart := time.Now()

	// First, create an instance of the Plugin type. Here we're opting to
	// manually construct the Plugin value instead of using the constructor
	// (mostly for contrast).
	//
	// We set the ExitStatusCode value to reflect a successful plugin
	// execution. If we do not alter the exit status code later this is what
	// will be reported to Nagios when the plugin exits.
	var plugin = nagios.Plugin{
		LastError:      nil,
		ExitStatusCode: nagios.StateOKExitCode,
	}

	// Second, immediately defer ReturnCheckResults() so that it runs as the
	// last step in your client code. If you do not defer ReturnCheckResults()
	// immediately any other deferred functions in your client code will not
	// run.
	//
	// Avoid calling os.Exit() directly from your code. If you do, this
	// library is unable to function properly; this library expects that it
	// will handle calling os.Exit() with the required exit code (and
	// specifically formatted output).
	//
	// For handling error cases, the approach is roughly the same, only you
	// call return explicitly to end execution of the client code and allow
	// deferred functions to run.
	defer plugin.ReturnCheckResults()

	// Collect last minute details just before ending plugin execution.
	defer func(plugin *nagios.Plugin, start time.Time) {

		// Record plugin runtime, emit this metric regardless of exit
		// point/cause.
		runtimeMetric := nagios.PerformanceData{
			// NOTE: This metric is provided by default if using the provided
			// nagios.NewPlugin constructor.
			//
			// If we specify this value ourselves, *our* value takes
			// precedence and the default value is ignored.
			Label: "time",
			Value: fmt.Sprintf("%dms", time.Since(start).Milliseconds()),
		}
		if err := plugin.AddPerfData(false, runtimeMetric); err != nil {
			log.Printf("failed to add time (runtime) performance data metric: %v", err)
			plugin.Errors = append(plugin.Errors, err)
		}

	}(&plugin, pluginStart)

	// more stuff here

	//nolint:goconst
	plugin.ServiceOutput = "one-line summary text here"

	//nolint:goconst
	plugin.LongServiceOutput = "more detailed output here"
}

Output:

ExampleHideSections demonstrates explicitly hiding or omitting the optional section headers for thresholds and errors.

package main

import (
	"github.com/atc0005/go-nagios"
)

// Ignore this. This is just to satisfy the "whole file" example requirements
// per https://go.dev/blog/examples.
var _ = "https://github.com/atc0005/go-nagios"

// ExampleHideSections demonstrates explicitly hiding or omitting the optional
// section headers for thresholds and errors.
func main() {
	// First, create an instance of the Plugin type. By default this value is
	// configured to indicate a successful execution. This should be
	// overridden by client code to indicate the final plugin state to Nagios
	// when the plugin exits.
	var plugin = nagios.NewPlugin()

	// Second, immediately defer ReturnCheckResults() so that it runs as the
	// last step in your client code. If you do not defer ReturnCheckResults()
	// immediately any other deferred functions in your client code will not
	// run.
	//
	// Avoid calling os.Exit() directly from your code. If you do, this
	// library is unable to function properly; this library expects that it
	// will handle calling os.Exit() with the required exit code (and
	// specifically formatted output).
	//
	// For handling error cases, the approach is roughly the same, only you
	// call return explicitly to end execution of the client code and allow
	// deferred functions to run.
	defer plugin.ReturnCheckResults()

	// more stuff here

	// Hide/Omit these sections from plugin output
	plugin.HideErrorsSection()
	plugin.HideThresholdsSection()

	//nolint:goconst
	plugin.ServiceOutput = "one-line summary text here"

	//nolint:goconst
	plugin.LongServiceOutput = "more detailed output here"
}

Output:

ExampleOverrideSectionHeaders demonstrates overriding the default text with values that better fit our use case.

package main

import (
	"github.com/atc0005/go-nagios"
)

// Ignore this. This is just to satisfy the "whole file" example requirements
// per https://go.dev/blog/examples.
var _ = "https://github.com/atc0005/go-nagios"

// ExampleOverrideSectionHeaders demonstrates overriding the default text with
// values that better fit our use case.
func main() {
	// First, create an instance of the Plugin type. By default this value is
	// configured to indicate a successful execution. This should be
	// overridden by client code to indicate the final plugin state to Nagios
	// when the plugin exits.
	var plugin = nagios.NewPlugin()

	// Second, immediately defer ReturnCheckResults() so that it runs as the
	// last step in your client code. If you do not defer ReturnCheckResults()
	// immediately any other deferred functions in your client code will not
	// run.
	//
	// Avoid calling os.Exit() directly from your code. If you do, this
	// library is unable to function properly; this library expects that it
	// will handle calling os.Exit() with the required exit code (and
	// specifically formatted output).
	//
	// For handling error cases, the approach is roughly the same, only you
	// call return explicitly to end execution of the client code and allow
	// deferred functions to run.
	defer plugin.ReturnCheckResults()

	// more stuff here

	// Override default section headers with our custom values.
	plugin.SetErrorsLabel("VALIDATION ERRORS")
	plugin.SetDetailedInfoLabel("VALIDATION CHECKS REPORT")
}

Output:

ExampleUseABrandingCallback demonstrates using a branding callback to emit custom branding details at plugin exit. This can be useful to brand plugin output so that it is easier to tell which plugin generated it.

package main

import (
	"github.com/atc0005/go-nagios"
)

// Ignore this. This is just to satisfy the "whole file" example requirements
// per https://go.dev/blog/examples.
var _ = "https://github.com/atc0005/go-nagios"

// Pretend that this is provided by another package. Included here for
// simplicity.
type Config struct {
	EmitBranding bool
}

// Branding accepts a message and returns a function that concatenates that
// message with version information. This function is intended to be called as
// a final step before application exit after any other output has already
// been emitted.
//
// Pretend that this is provided by another package. Included here for
// simplicity.
func Branding(s string) func() string {
	return func() string {
		return s + " appended branding string"
	}
}

// ExampleUseABrandingCallback demonstrates using a branding callback to emit
// custom branding details at plugin exit. This can be useful to brand plugin
// output so that it is easier to tell which plugin generated it.
func main() {
	// First, create an instance of the Plugin type. By default this value is
	// configured to indicate a successful execution. This should be
	// overridden by client code to indicate the final plugin state to Nagios
	// when the plugin exits.
	var plugin = nagios.NewPlugin()

	// Second, immediately defer ReturnCheckResults() so that it runs as the
	// last step in your client code. If you do not defer ReturnCheckResults()
	// immediately any other deferred functions in your client code will not
	// run.
	//
	// Avoid calling os.Exit() directly from your code. If you do, this
	// library is unable to function properly; this library expects that it
	// will handle calling os.Exit() with the required exit code (and
	// specifically formatted output).
	//
	// For handling error cases, the approach is roughly the same, only you
	// call return explicitly to end execution of the client code and allow
	// deferred functions to run.
	defer plugin.ReturnCheckResults()

	// ...

	// In this example, we'll make a further assumption that you have a config
	// value with an EmitBranding field to indicate whether the user/sysadmin
	// has opted to emit branding information. This value might be returned
	// from another package. Here we're representing it as a literal value for
	// simplicity.
	config := Config{
		EmitBranding: true,
	}

	if config.EmitBranding {
		// If enabled, show application details at end of notification
		plugin.BrandingCallback = Branding("Notification generated by ")
	}

	// You could just as easily create an anonymous function as the callback:
	if config.EmitBranding {
		// If enabled, show application details at end of notification
		plugin.BrandingCallback = func(msg string) func() string {
			return func() string {
				return "Notification generated by " + msg
			}
		}("HelloWorld")
	}
}

Output:

Example_usingOnlyTheProvidedConstants is a simple example that illustrates using only the provided constants from this package. After you've imported this library, reference the exported data types as you would from any other package.

// In this example, we reference a specific exit code for the OK state and
// also use the provided state "labels" to avoid using literal string
// state values (recommended):
fmt.Printf(
	"%s: All checks have passed%s",
	nagios.StateOKLabel,
	nagios.CheckOutputEOL,
)

os.Exit(nagios.StateOKExitCode)

Output:

Example_usingOnlyTheProvidedExitCodeConstants is a simple example that illustrates using only the provided exit code constants from this package. After you've imported this library, reference the exported data types as you would from any other package.

// In this example, we reference a specific exit code for the OK state:
fmt.Println("OK: All checks have passed")

os.Exit(nagios.StateOKExitCode)

Output: