beat

Documentation

Overview

Package beat provides the functions required to manage the life-cycle of a Beat. It provides the standard mechanism for launching a Beat. It manages configuration, logging, and publisher initialization and registers a signal handler to gracefully stop the process.

Each Beat implementation must implement the Beater interface and may optionally implement the FlagsHandler interface. See the Beater interface documentation for more details.

To use this package, create a simple main that invokes the Run() function.

func main() {
	if err := beat.Run("mybeat", myVersion, beater.New()); err != nil {
		os.Exit(1)
	}
}

In the example above, the beater package contains the implementation of the Beater interface and the New() method returns a new instance of Beater. The Beater implementation is placed into its own package so that it can be reused or combined with other Beats.

Recommendations

• Use the logp package for logging rather than writing to stdout or stderr.
• Do not call os.Exit in any of your code. Return an error instead. Or if your code needs to exit without an error, return beat.GracefulExit.

Index

• Variables
• func NewExitError(code int, format string, args ...interface{}) error
• func Run(name, version string, bt Beater) error
• type Beat
• type BeatConfig
• type Beater
• type ExitError
  • func (e ExitError) Error() string
• type FlagsHandler

Variables

var (
	// GracefulExit is an error that signals to exit with a code of 0.
	GracefulExit = ExitError{}
)

Functions

func NewExitError

func NewExitError(code int, format string, args ...interface{}) error

NewExitError returns a new ExitError.

func Run

func Run(name, version string, bt Beater) error

Run initializes and runs a Beater implementation. name is the name of the Beat (e.g. packetbeat or topbeat). version is version number of the Beater implementation. bt is Beater implementation to run.

Types

type Beat

type Beat struct {
	Name      string                   // Beat name.
	Version   string                   // Beat version number. Defaults to the libbeat version when an implementation does not set a version.
	UUID      uuid.UUID                // ID assigned to a Beat instance.
	BT        Beater                   // Beater implementation.
	RawConfig *common.Config           // Raw config that can be unpacked to get Beat specific config data.
	Config    BeatConfig               // Common Beat configuration data.
	Events    publisher.Client         // Client used for publishing events.
	Publisher *publisher.PublisherType // Publisher
	// contains filtered or unexported fields
}

Beat contains the basic beat data and the publisher client used to publish events.

type BeatConfig

type BeatConfig struct {
	Output  map[string]*common.Config
	Logging logp.Logging
	Shipper publisher.ShipperConfig
	Filter  []filter.FilterConfig
}

BeatConfig struct contains the basic configuration of every beat

type Beater

type Beater interface {
	Config(*Beat) error  // Read and validate configuration.
	Setup(*Beat) error   // Initialize the Beat.
	Run(*Beat) error     // The main event loop. This method should block until signalled to stop by an invocation of the Stop() method.
	Cleanup(*Beat) error // Cleanup is invoked to perform any final clean-up prior to exiting.
	Stop()               // Stop is invoked to signal that the Run method should finish its execution. It will be invoked at most once.
}

Beater is the interface that must be implemented every Beat. The full lifecycle of a Beat instance is managed through this interface.

Life-cycle of Beater

The four operational methods are always invoked serially in the following order:

Config -> Setup -> Run -> Cleanup

The Stop() method is invoked the first time (and only the first time) a shutdown signal is received. The Stop() method is eligible to be invoked at any point after Setup() completes (this ensures that the Beater implementation is fully initialized before Stop() can be invoked).

The Cleanup() method is guaranteed to be invoked upon shutdown iff the Beater reaches the Setup stage. For example, if there is a failure in the Config stage then Cleanup will not be invoked.

type ExitError

type ExitError struct {
	ExitCode int
	Cause    error
}

ExitError is an error type that can be returned to set a specific exit code.

func (ExitError) Error

func (e ExitError) Error() string

type FlagsHandler

type FlagsHandler interface {
	HandleFlags(*Beat) error // Handle any custom command line arguments.
}

FlagsHandler is an interface that can optionally be implemented by a Beat if it needs to process command line flags on startup. If implemented, the HandleFlags method will be invoked after parsing the command line flags and before any of the Beater interface methods are invoked. There will be no callback when '-help' or '-version' are specified.