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 a `Creator` to create and initialize the Beater instance. See the `Beater` interface and `Creator` 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 AddFlagsCallback(cb func(*Beat) error)
• func AddFlagsHandler(h FlagsHandler)
• func Run(name, version string, bt Creator) error
• type Beat
  • func New(name, v string) (*Beat, error)
  • func (b *Beat) BeatConfig() (*common.Config, error)
  • func (b *Beat) Init() error
  • func (b *Beat) Setup(bt Creator, template, dashboards, machineLearning bool) error
  • func (b *Beat) TestConfig(bt Creator) error
• type BeatConfig
• type Beater
• type Creator
• type FlagsHandler
• type FlagsHandlerCallback
  • func (cb FlagsHandlerCallback) HandleFlags(b *Beat) error
• type SetupMLCallback
• type TemplateConfig

Variables

var GracefulExit = errors.New("graceful exit")

GracefulExit is an error that signals to exit with a code of 0.

Functions

func AddFlagsCallback

func AddFlagsCallback(cb func(*Beat) error)

func AddFlagsHandler

func AddFlagsHandler(h FlagsHandler)

func Run

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

Run initializes and runs a Beater implementation. name is the name of the Beat (e.g. packetbeat or metricbeat). version is version number of the Beater implementation. bt is the `Creator` callback for creating a new beater instance. XXX Move this as a *Beat method?

Types

type Beat

type Beat struct {
	Info      common.BeatInfo     // beat metadata.
	RawConfig *common.Config      // Raw config that can be unpacked to get Beat specific config data.
	Config    BeatConfig          // Common Beat configuration data.
	Publisher publisher.Publisher // Publisher

	SetupMLCallback SetupMLCallback // setup callback for ML job configs
	InSetupCmd      bool            // this is set to true when the `setup` command is called
}

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

func New

func New(name, v string) (*Beat, error)

New creates a new beat instance

func (*Beat) BeatConfig

func (b *Beat) BeatConfig() (*common.Config, error)

BeatConfig returns config section for this beat

func (*Beat) Init

func (b *Beat) Init() error

init does initialization of things common to all actions (read confs, flags)

func (*Beat) Setup

func (b *Beat) Setup(bt Creator, template, dashboards, machineLearning bool) error

Setup registers ES index template and kibana dashboards

func (*Beat) TestConfig

func (b *Beat) TestConfig(bt Creator) error

TestConfig check all settings are ok and the beat can be run

type BeatConfig

type BeatConfig struct {
	Shipper    publisher.ShipperConfig `config:",inline"`
	Output     common.ConfigNamespace  `config:"output"`
	Monitoring *common.Config          `config:"xpack.monitoring"`
	Logging    logp.Logging            `config:"logging"`
	Processors processors.PluginConfig `config:"processors"`
	Path       paths.Path              `config:"path"`
	Dashboards *common.Config          `config:"setup.dashboards"`
	Template   *common.Config          `config:"setup.template"`
	Kibana     *common.Config          `config:"setup.kibana"`
	Http       *common.Config          `config:"http"`
}

BeatConfig struct contains the basic configuration of every beat

type Beater

type Beater interface {
	// The main event loop. This method should block until signalled to stop by an
	// invocation of the Stop() method.
	Run(b *Beat) error

	// Stop is invoked to signal that the Run method should finish its execution.
	// It will be invoked at most once.
	Stop()
}

Beater is the interface that must be implemented by every Beat. A Beater provides the main Run-loop and a Stop method to break the Run-loop. Instantiation and Configuration is normally provided by a Beat-`Creator`.

Once the beat is fully configured, the Run() method is invoked. The Run()-method implements the beat its run-loop. Once the Run()-method returns, the beat shuts down.

The Stop() method is invoked the first time (and only the first time) a shutdown signal is received. The Stop()-method normally will stop the Run()-loop, such that the beat can gracefully shutdown.

type Creator

type Creator func(*Beat, *common.Config) (Beater, error)

Creator initializes and configures a new Beater instance used to execute the beat its run-loop.

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.

type FlagsHandlerCallback

type FlagsHandlerCallback func(*Beat) error

func (FlagsHandlerCallback) HandleFlags

func (cb FlagsHandlerCallback) HandleFlags(b *Beat) error

type SetupMLCallback

type SetupMLCallback func(*Beat) error

SetupMLCallback can be used by the Beat to register MachineLearning configurations for the enabled modules.

type TemplateConfig

type TemplateConfig struct {
	Enabled   bool              `config:"enabled"`
	Name      string            `config:"name"`
	Fields    string            `config:"fields"`
	Overwrite bool              `config:"overwrite"`
	Settings  map[string]string `config:"settings"`
}