jobreceiver

README

Monitoring Job Receiver

Status
Stability	[alpha]: logs

This receiver makes it possible to collect telemetry data from sources that do not instrument well. The monitoring job receiver executes a script or executable at defined intervals, and propagates the output from that process as log events. In addition, the monitoring job receiver simplifies the process of downloading runtime assets necessary to run a particular monitoring job.

Configuration

Configuration	Default	Description
exec	required	A exec configuration block. See details below
schedule	required	A schedule configuration block. See details below
output		An output configuration block. See details below

Execution Configuration

Configuration	Default	Description
command	required	The command to run. Should start a binary that writes to stdout and/or stderr
arguments		A list of string arguments to pass the command
timeout		Time to wait for the process to exit before attempting to make it exit
runtime_assets		A list of runtime_assets required for the monitoring job. See details below

Schedule Configuration

The scheduling configuration block currently only supports a single required interval Time parameter. Counting from collector startup, the command will be scheduled every interval.

Output Configuration

The monitoringjob receiver output is a configurable as a Stanza pipeline. This allows complex operators to be chained to parse the command output.

Configuration	Default	Description
type	event	The output handler type see below. Valid values are event and log_entries.
event	{}	When type == event this block may be configured with additional properties as described below.
log_entries	{}	When type == log_entries this block may be configured with additional properties as described below.
operators	[]	An array of stanza operators to act on the output.
retry_on_failure.enabled	false	If true, the receiver will pause reading a file and attempt to resend the current batch of logs if it encounters an error from downstream components.
retry_on_failure.initial_interval	1s	Time to wait after the first failure before retrying.
retry_on_failure.max_interval	30s	Upper bound on retry backoff interval. Once this value is reached the delay between consecutive retries will remain constant at the specified value.
retry_on_failure.max_elapsed_time	5m	Maximum amount of time (including retries) spent trying to send a logs batch to a downstream consumer. Once this value is reached, the data is discarded. Retrying never stops if set to 0.
attributes	{}	A map of key: value pairs to add to the entry's attributes.
resource	{}	A map of key: value pairs to add to the entry's resource.

Output Handler Type

The monitoringjob receiver can feed output into the stanza pipeline in one of two ways depending on the configured type.

By default, the type: 'event' output handler is used. When configured with the event output type, command output will be buffered until the process exits, at which time the receiver will emit a single structured event capturing the command output and optionally metadata about the execution such as exit code and duration. This is useful for true monitoring jobs, such as using a monitoring plugin not supported natively by OTEL.

When configured with the log_entries output type, command output will be emitted as distinct log entries line-by-line. This can be used to act as a bridge to third party logs and other log events that may not be straightforward to access.

Output Configuration - event

Configuration	Default	Description
include_command_name	true	When set, includes the attribute command.name in the log event.
include_command_status	true	When set, includes the attribute command.status in the log event.
include_command_duration	true	When set, includes the attribute command.duration in the log event.
max_body_size		When set, restricts the length of command output to a specified ByteSize.

Output Configuration - log_entries

Configuration	Default	Description
include_command_name	true	When set, includes the attribute command.name in the log event.
include_stream_name	true	When set, includes the attribute command.stream.name in the log event. Indicating stdin or stderr as the origin of the event.
max_log_size		When set, restricts the length of a log entry to a specified ByteSize.
encoding	utf-8	Encoding to expect from the command output. Used to detect log entry boundaries.
multiline		Used to override the default newline delimited log entries.
multiline.line_start_pattern		Regex pattern for the beginning of a log entry. Mutualy exclusive with end pattern.
multiline.line_end_pattern		Regex pattern for the ending of a log entry. Mutualy exclusive with start pattern.

Runtime Assets

Runtime assets can be specified on a monitoring job to make it easier to distribute monitoring instrumentation to collectors. When a runtime asset is specified on a monitoring job receiver, the collector will download and install the asset locally before the monitoring job is ran. This eliminates the need to pre-install monitoring instrumentation alongside the collector.

Runtime assets are packaged according to the sensu-go asset specification, allowing users to take advantage of the existing asset definitions in Bonsai, sensu-go's asset hub. Packaging an asset yourself is relatively straight-forward. Simply serve a tar archive (optionally gzipped) containing a bin directory containing one or multiple executables. The asset will be unpacked and the monitoring job will be executed with ./bin included in the PATH environment variable, ./lib included in LD_LIBRARY_PATH and ./include in CPATH.

Configuration	Default	Description
name	required	Name for the asset.
url	required	HTTP URL used to fetch the asset.
sha512	required	SHA512 hash of the asset archive.

Additional Features

Time Parameters

Time parameters are expressed as go duration strings as defined by time.ParseDuration.

Examples: 60s, 45m, 2h30m40s.

ByteSize Parameters

ByteSize parameters can be specified either as an integer number or as a string starting with decimal numbers optionally followed by a common byte unit prefixes. e.g. 16kb, 32MiB, 1GB.

Example configuration

monitoringjob:
  schedule:
    interval: 1h
  exec:
    command: check_ntp_time
    arguments:
      - "-H"
      - time.nist.gov
    timeout: 8s
  output:
    type: event
    event:
      include_command_name: false
      include_command_status: true
      include_command_duration: true
      max_body_size: "32kib"

Documentation

Index

• Variables
• func NewFactory() receiver.Factory
• type Config
  • func (c Config) Build(logger *zap.SugaredLogger, out consumer.Interface) (builder.JobRunner, error)
  • func (cfg *Config) Validate() error
• type ExecutionConfig
• type ScheduleConfig

Variables

var Type = component.MustNewType("monitoringjob")

Functions

func NewFactory

func NewFactory() receiver.Factory

NewFactory uses the stanza adapter factory to facilitate the initialization and running of the stanza output pipeline.

Types

type Config

type Config struct {
	Exec     ExecutionConfig `mapstructure:"exec"`
	Schedule ScheduleConfig  `mapstructure:"schedule"`
	Output   output.Config   `mapstructure:"output"`
}

Config for monitoringjob receiver

func (Config) Build

func (c Config) Build(logger *zap.SugaredLogger, out consumer.Interface) (builder.JobRunner, error)

Build returns the job runner, the process responsible for scheduling and running commands and piping their output to the output consumer.

func (*Config) Validate

func (cfg *Config) Validate() error

Validate checks the configuration is valid

type ExecutionConfig

type ExecutionConfig struct {
	// Command is the name of the binary to be executed
	Command string `mapstructure:"command"`
	// Arguments to pass to the command
	Arguments []string `mapstructure:"arguments"`
	// RuntimeAssets made available to the execution context
	RuntimeAssets []asset.Spec `mapstructure:"runtime_assets"`
	// Timeout is the time to wait for the process to exit before attempting
	// to make it stop
	Timeout time.Duration `mapstructure:"timeout,omitempty"`
}

ExecutionConfig defines the configuration for execution of a monitoringjob process

type ScheduleConfig

type ScheduleConfig struct {
	// Interval to schedule monitoring job at
	Interval time.Duration `mapstructure:"interval,omitempty"`
}

ScheduleConfig defines configuration for the scheduling of the monitoringjob receiver