agent

Documentation

Index

• Constants
• Variables
• func SetupLogging(prefix, taskId string) error
• type Agent
  • func New(opts Options) (*Agent, error)
  • func (agt *Agent) CheckIn(command model.PluginCommandConf, duration time.Duration)
  • func (agt *Agent) GetCurrentCommand() model.PluginCommandConf
  • func (agt *Agent) GetTaskConfig() (*model.TaskConfig, error)
  • func (agt *Agent) Run() error
  • func (agt *Agent) RunCommands(commands []model.PluginCommandConf, returnOnError bool, stop chan bool) error
  • func (agt *Agent) RunTask() (*apimodels.EndTaskResponse, error)
  • func (agt *Agent) RunTaskCommands() string
  • func (agt *Agent) Setup() error
  • func (agt *Agent) StartBackgroundActions(signalHandler TerminateHandler)
• type AgentCommand
  • func (ac *AgentCommand) Run(workingDir string) error
• type ExecTracker
• type Options
• type SignalHandler
  • func (sh *SignalHandler) HandleSignals(agt *Agent)
• type StatsCollector
  • func NewSimpleStatsCollector(logger *slogger.Logger, interval time.Duration, stop <-chan struct{}, ...) *StatsCollector
  • func (sc *StatsCollector) LogStats(exp *command.Expansions)
• type TerminateHandler

Constants

const (
	// DefaultCmdTimeout specifies the duration after which agent sends
	// an IdleTimeout signal if a task's command does not run to completion.
	DefaultCmdTimeout = 2 * time.Hour

	// DefaultExecTimeoutSecs specifies in seconds the maximum time a task is allowed to run
	// for, even if it is not idle. This default is used if exec_timeout_secs is not specified
	// in the project file.
	DefaultExecTimeoutSecs = 60 * 60 * 6 // six hours

	// DefaultIdleTimeout specifies the duration after which agent sends an
	// IdleTimeout signal if a task produces no logs.
	DefaultIdleTimeout = 20 * time.Minute
	// DefaultCallbackCmdTimeout specifies the duration after when the "post" or
	// "timeout" command sets should be shut down.
	DefaultCallbackCmdTimeout = 15 * time.Minute
	// DefaultHeartbeatInterval is interval after which agent sends a heartbeat
	// to API server.
	DefaultHeartbeatInterval = 30 * time.Second
	// DefaultStatsInterval is the interval after which agent sends system stats
	// to API server
	DefaultStatsInterval = time.Minute

	// DefaultAgentSleepInterval is the interval after which the agent retries getting a next task
	DefaultAgentSleepInterval = 30 * time.Second
)

Variables

var (
	// InitialSetupTimeout indicates the time allowed for the agent to collect
	// relevant information - for running a task - from the API server.
	InitialSetupTimeout = 20 * time.Minute
	// InitialSetupCommand is a placeholder command for the period during which
	// the agent requests information for running a task
	InitialSetupCommand = model.PluginCommandConf{
		DisplayName: "initial task setup",
		Type:        model.SystemCommandType,
	}
)

var InterruptedCmdError = errors.New("Command interrupted")

InterruptedCmdError is returned by commands that were stopped before they could complete.

Functions

func SetupLogging

func SetupLogging(prefix, taskId string) error

SetupLogging configures the agent's local logging to a file.

Types

type Agent

type Agent struct {

	// TaskCommunicator handles all communication with the API server -
	// marking task started/ended, sending test results, logs, heartbeats, etc
	comm.TaskCommunicator

	// ExecTracker keeps track of the agent's current stage of execution.
	ExecTracker

	// KillChan is a channel which once closed, causes any in-progress commands to abort.
	KillChan chan bool

	// APILogger is a slogger.Appender which sends log messages
	// to the API server.
	APILogger *comm.APILogger

	// Registry manages plugins available for the agent.
	Registry plugin.Registry
	// contains filtered or unexported fields
}

Agent controls the various components and background processes needed throughout the lifetime of the execution of the task.

func New

func New(opts Options) (*Agent, error)

New creates a new agent to run a given task.

func (*Agent) CheckIn

func (agt *Agent) CheckIn(command model.PluginCommandConf, duration time.Duration)

CheckIn updates the agent's execution stage and current timeout duration, and resets its timer back to zero.

func (*Agent) GetCurrentCommand

func (agt *Agent) GetCurrentCommand() model.PluginCommandConf

GetCurrentCommand returns the current command being executed by the agent.

func (*Agent) GetTaskConfig

func (agt *Agent) GetTaskConfig() (*model.TaskConfig, error)

GetTaskConfig fetches task configuration data required to run the task from the API server.

func (*Agent) Run

func (agt *Agent) Run() error

Run is the agent loop which gets the next task if it exists, and runs the task if it gets one. It returns an exit code when the agent needs to exit

func (*Agent) RunCommands

func (agt *Agent) RunCommands(commands []model.PluginCommandConf, returnOnError bool, stop chan bool) error

RunCommands takes a slice of commands and executes then sequentially. If returnOnError is set, it returns immediately if one of the commands fails. All plugins listen on the stop channel and must terminate immediately when a value is received.

func (*Agent) RunTask

func (agt *Agent) RunTask() (*apimodels.EndTaskResponse, error)

RunTask manages the process of running a task. It returns a response indicating the end result of the task.

func (*Agent) RunTaskCommands

func (agt *Agent) RunTaskCommands() string

RunTaskCommands runs all commands for the task currently assigned to the agent and returns the task status

func (*Agent) Setup

func (agt *Agent) Setup() error

Setup initializes all the signal chans and loggers that are used during one run of the agent.

func (*Agent) StartBackgroundActions

func (agt *Agent) StartBackgroundActions(signalHandler TerminateHandler)

StartBackgroundActions spawns goroutines that monitor various parts of the execution - heartbeats, timeouts, logging, etc.

type AgentCommand

type AgentCommand struct {
	*comm.StreamLogger
	ScriptLine string
	Expansions *command.Expansions
	KillChan   chan bool
}

AgentCommand encapsulates a running local command and streams logs back to the API server.

func (*AgentCommand) Run

func (ac *AgentCommand) Run(workingDir string) error

Run will execute the command in workingDir, by applying the expansions to the script and then invoking it with sh -c, and logging all of the command's stdout/stderr using the Logger. It will block until the command either finishes, or is aborted prematurely via the kill channel.

type ExecTracker

type ExecTracker interface {
	// Returns the current command being executed.
	CurrentCommand() *model.PluginCommandConf
	// Sets the current command being executed as well as a timeout for the command.
	CheckIn(command model.PluginCommandConf, timeout time.Duration)
}

ExecTracker exposes functions to update and get the current execution stage of the agent.

type Options

type Options struct {
	APIURL      string
	HostId      string
	HostSecret  string
	Certificate string
	LogPrefix   string
	StatusPort  int
}

Options represents an agent configuration.

type SignalHandler

type SignalHandler struct {
	// contains filtered or unexported fields
}

SignalHandler is an implementation of TerminateHandler which runs the post-run script when a task finishes, and reports its results back to the API server.

func (*SignalHandler) HandleSignals

func (sh *SignalHandler) HandleSignals(agt *Agent)

HandleSignals listens on its signal channel and properly handles any signal received.

type StatsCollector

type StatsCollector struct {
	Cmds []string
	// indicates the sampling frequency
	Interval time.Duration
	// contains filtered or unexported fields
}

StatsCollector samples machine statistics and logs them back to the API server at regular intervals.

func NewSimpleStatsCollector

func NewSimpleStatsCollector(logger *slogger.Logger, interval time.Duration,
	stop <-chan struct{}, cmds ...string) *StatsCollector

NewSimpleStatsCollector creates a StatsCollector that runs the given commands at the given interval and sends the results to the given logger.

func (*StatsCollector) LogStats

func (sc *StatsCollector) LogStats(exp *command.Expansions)

type TerminateHandler

type TerminateHandler interface {
	HandleSignals(*Agent)
}

TerminateHandler is an interface which defines how the agent should respond to signals resulting in the end of the task (heartbeat fail, timeout, etc)