Documentation
¶
Index ¶
- Variables
- type ArgumentConfigNode
- type BlockNode
- type ComponentGlobals
- type ComponentID
- type ComponentNode
- func (cn *ComponentNode) Arguments() component.Arguments
- func (cn *ComponentNode) Block() *ast.BlockStmt
- func (cn *ComponentNode) Component() component.Component
- func (cn *ComponentNode) ComponentName() string
- func (cn *ComponentNode) CurrentHealth() component.Health
- func (cn *ComponentNode) DebugInfo() interface{}
- func (cn *ComponentNode) Evaluate(scope *vm.Scope) error
- func (cn *ComponentNode) Exports() component.Exports
- func (cn *ComponentNode) HTTPHandler() http.Handler
- func (cn *ComponentNode) ID() ComponentID
- func (cn *ComponentNode) Label() string
- func (cn *ComponentNode) ModuleIDs() []string
- func (cn *ComponentNode) NodeID() string
- func (cn *ComponentNode) Reevaluate() error
- func (cn *ComponentNode) Registration() component.Registration
- func (cn *ComponentNode) Run(ctx context.Context) error
- func (cn *ComponentNode) UpdateBlock(b *ast.BlockStmt)
- type ConfigNodeMap
- func (nodeMap *ConfigNodeMap) Append(configNode BlockNode) diag.Diagnostics
- func (nodeMap *ConfigNodeMap) Validate(isInModule bool, args map[string]any) diag.Diagnostics
- func (nodeMap *ConfigNodeMap) ValidateModuleConstraints(isInModule bool) diag.Diagnostics
- func (nodeMap *ConfigNodeMap) ValidateUnsupportedArguments(args map[string]any) diag.Diagnostics
- type DialFunc
- type ExportConfigNode
- type Loader
- func (l *Loader) Apply(args map[string]any, componentBlocks []*ast.BlockStmt, ...) diag.Diagnostics
- func (l *Loader) Cleanup()
- func (l *Loader) Components() []*ComponentNode
- func (l *Loader) EvaluateDependencies(c *ComponentNode)
- func (l *Loader) Graph() *dag.Graph
- func (l *Loader) OriginalGraph() *dag.Graph
- func (l *Loader) Variables() map[string]interface{}
- type LoggingConfigNode
- type ModuleController
- type Queue
- type Reference
- type RunnableNode
- type Scheduler
- type TracingConfigNode
- type Traversal
Constants ¶
This section is empty.
Variables ¶
var ErrUnevaluated = errors.New("managed component not built")
ErrUnevaluated is returned if ComponentNode.Run is called before a managed component is built.
Functions ¶
This section is empty.
Types ¶
type ArgumentConfigNode ¶ added in v0.34.0
type ArgumentConfigNode struct {
// contains filtered or unexported fields
}
func NewArgumentConfigNode ¶ added in v0.34.0
func NewArgumentConfigNode(block *ast.BlockStmt, globals ComponentGlobals) *ArgumentConfigNode
NewArgumentConfigNode creates a new ArgumentConfigNode from an initial ast.BlockStmt. The underlying config isn't applied until Evaluate is called.
func (*ArgumentConfigNode) Block ¶ added in v0.34.0
func (cn *ArgumentConfigNode) Block() *ast.BlockStmt
Block implements BlockNode and returns the current block of the managed config node.
func (*ArgumentConfigNode) Default ¶ added in v0.34.0
func (cn *ArgumentConfigNode) Default() any
func (*ArgumentConfigNode) Evaluate ¶ added in v0.34.0
func (cn *ArgumentConfigNode) Evaluate(scope *vm.Scope) error
Evaluate implements BlockNode and updates the arguments for the managed config block by re-evaluating its River block with the provided scope. The managed config block will be built the first time Evaluate is called.
Evaluate will return an error if the River block cannot be evaluated or if decoding to arguments fails.
func (*ArgumentConfigNode) Label ¶ added in v0.34.0
func (cn *ArgumentConfigNode) Label() string
func (*ArgumentConfigNode) NodeID ¶ added in v0.34.0
func (cn *ArgumentConfigNode) NodeID() string
NodeID implements dag.Node and returns the unique ID for the config node.
func (*ArgumentConfigNode) Optional ¶ added in v0.34.0
func (cn *ArgumentConfigNode) Optional() bool
type BlockNode ¶ added in v0.33.0
type BlockNode interface { dag.Node // Block returns the current block of the managed config node. Block() *ast.BlockStmt // Evaluate updates the arguments for the managed component // by re-evaluating its River block with the provided scope. The managed component // will be built the first time Evaluate is called. // // Evaluate will return an error if the River block cannot be evaluated or if // decoding to arguments fails. Evaluate(scope *vm.Scope) error }
BlockNode is a node in the DAG which manages a River block and can be evaluated.
func NewConfigNode ¶ added in v0.29.0
func NewConfigNode(block *ast.BlockStmt, globals ComponentGlobals) (BlockNode, diag.Diagnostics)
NewConfigNode creates a new ConfigNode from an initial ast.BlockStmt. The underlying config isn't applied until Evaluate is called.
type ComponentGlobals ¶
type ComponentGlobals struct { Logger *logging.Logger // Logger shared between all managed components. TraceProvider trace.TracerProvider // Tracer shared between all managed components. Clusterer *cluster.Clusterer // Clusterer shared between all managed components. DataPath string // Shared directory where component data may be stored OnComponentUpdate func(cn *ComponentNode) // Informs controller that we need to reevaluate OnExportsChange func(exports map[string]any) // Invoked when the managed component updated its exports Registerer prometheus.Registerer // Registerer for serving agent and component metrics HTTPPathPrefix string // HTTP prefix for components. HTTPListenAddr string // Base address for server DialFunc DialFunc // Function to connect to HTTPListenAddr. ControllerID string // ID of controller. NewModuleController func(id string) ModuleController // Func to generate a module controller. }
ComponentGlobals are used by ComponentNodes to build managed components. All ComponentNodes should use the same ComponentGlobals.
type ComponentID ¶
type ComponentID []string
ComponentID is a fully-qualified name of a component. Each element in ComponentID corresponds to a fragment of the period-delimited string; "remote.http.example" is ComponentID{"remote", "http", "example"}.
func BlockComponentID ¶
func BlockComponentID(b *ast.BlockStmt) ComponentID
BlockComponentID returns the ComponentID specified by an River block.
func (ComponentID) Equals ¶
func (id ComponentID) Equals(other ComponentID) bool
Equals returns true if id == other.
func (ComponentID) String ¶
func (id ComponentID) String() string
String returns the string representation of a component ID.
type ComponentNode ¶
type ComponentNode struct { OnComponentUpdate func(cn *ComponentNode) // Informs controller that we need to reevaluate // contains filtered or unexported fields }
ComponentNode is a controller node which manages a user-defined component.
ComponentNode manages the underlying component and caches its current arguments and exports. ComponentNode manages the arguments for the component from a River block.
func NewComponentNode ¶
func NewComponentNode(globals ComponentGlobals, b *ast.BlockStmt) *ComponentNode
NewComponentNode creates a new ComponentNode from an initial ast.BlockStmt. The underlying managed component isn't created until Evaluate is called.
func (*ComponentNode) Arguments ¶
func (cn *ComponentNode) Arguments() component.Arguments
Arguments returns the current arguments of the managed component.
func (*ComponentNode) Block ¶ added in v0.33.0
func (cn *ComponentNode) Block() *ast.BlockStmt
Block implements BlockNode and returns the current block of the managed component.
func (*ComponentNode) Component ¶ added in v0.35.0
func (cn *ComponentNode) Component() component.Component
Component returns the instance of the managed component. Component may be nil if the ComponentNode has not been successfully evaluated yet.
func (*ComponentNode) ComponentName ¶ added in v0.28.0
func (cn *ComponentNode) ComponentName() string
ComponentName returns the component's type, i.e. `local.file.test` returns `local.file`.
func (*ComponentNode) CurrentHealth ¶
func (cn *ComponentNode) CurrentHealth() component.Health
CurrentHealth returns the current health of the ComponentNode.
The health of a ComponentNode is determined by combining:
- Health from the call to Run().
- Health from the last call to Evaluate().
- Health reported from the component.
func (*ComponentNode) DebugInfo ¶
func (cn *ComponentNode) DebugInfo() interface{}
DebugInfo returns debugging information from the managed component (if any).
func (*ComponentNode) Evaluate ¶
func (cn *ComponentNode) Evaluate(scope *vm.Scope) error
Evaluate implements BlockNode and updates the arguments for the managed component by re-evaluating its River block with the provided scope. The managed component will be built the first time Evaluate is called.
Evaluate will return an error if the River block cannot be evaluated or if decoding to arguments fails.
func (*ComponentNode) Exports ¶
func (cn *ComponentNode) Exports() component.Exports
Exports returns the current set of exports from the managed component. Exports returns nil if the managed component does not have exports.
func (*ComponentNode) HTTPHandler ¶ added in v0.28.0
func (cn *ComponentNode) HTTPHandler() http.Handler
HTTPHandler returns an http handler for a component IF it implements HTTPComponent. otherwise it will return nil.
func (*ComponentNode) ID ¶
func (cn *ComponentNode) ID() ComponentID
ID returns the component ID of the managed component from its River block.
func (*ComponentNode) Label ¶ added in v0.28.0
func (cn *ComponentNode) Label() string
Label returns the label for the block or "" if none was specified.
func (*ComponentNode) ModuleIDs ¶ added in v0.35.0
func (cn *ComponentNode) ModuleIDs() []string
ModuleIDs returns the current list of modules that this component is managing.
func (*ComponentNode) NodeID ¶
func (cn *ComponentNode) NodeID() string
NodeID implements dag.Node and returns the unique ID for this node. The NodeID is the string representation of the component's ID from its River block.
func (*ComponentNode) Reevaluate ¶ added in v0.33.0
func (cn *ComponentNode) Reevaluate() error
Reevaluate calls Update on the managed component with its last used arguments.Reevaluate does not build the component if it is not already built and does not re-evaluate the River block itself. Its only use case is for components opting-in to clustering where calling Update with the same Arguments may result in different functionality.
func (*ComponentNode) Registration ¶ added in v0.35.0
func (cn *ComponentNode) Registration() component.Registration
Registration returns the original registration of the component.
func (*ComponentNode) Run ¶
func (cn *ComponentNode) Run(ctx context.Context) error
Run runs the managed component in the calling goroutine until ctx is canceled. Evaluate must have been called at least once without retuning an error before calling Run.
Run will immediately return ErrUnevaluated if Evaluate has never been called successfully. Otherwise, Run will return nil.
func (*ComponentNode) UpdateBlock ¶
func (cn *ComponentNode) UpdateBlock(b *ast.BlockStmt)
UpdateBlock updates the River block used to construct arguments for the managed component. The new block isn't used until the next time Evaluate is invoked.
UpdateBlock will panic if the block does not match the component ID of the ComponentNode.
type ConfigNodeMap ¶ added in v0.34.0
type ConfigNodeMap struct {
// contains filtered or unexported fields
}
ConfigNodeMap represents the config BlockNodes in their explicit types. This is helpful when validating node conditions specific to config node types.
func NewConfigNodeMap ¶ added in v0.34.0
func NewConfigNodeMap() *ConfigNodeMap
NewConfigNodeMap will create an initial ConfigNodeMap. Append must be called to populate NewConfigNodeMap.
func (*ConfigNodeMap) Append ¶ added in v0.34.0
func (nodeMap *ConfigNodeMap) Append(configNode BlockNode) diag.Diagnostics
Append will add a config node to the ConfigNodeMap. This will overwrite values on the ConfigNodeMap that are matched and previously set.
func (*ConfigNodeMap) Validate ¶ added in v0.34.0
func (nodeMap *ConfigNodeMap) Validate(isInModule bool, args map[string]any) diag.Diagnostics
Validate wraps all validators for ConfigNodeMap.
func (*ConfigNodeMap) ValidateModuleConstraints ¶ added in v0.34.0
func (nodeMap *ConfigNodeMap) ValidateModuleConstraints(isInModule bool) diag.Diagnostics
ValidateModuleConstraints will make sure config blocks with module constraints get followed.
func (*ConfigNodeMap) ValidateUnsupportedArguments ¶ added in v0.34.0
func (nodeMap *ConfigNodeMap) ValidateUnsupportedArguments(args map[string]any) diag.Diagnostics
ValidateUnsupportedArguments will validate each provided argument is supported in the config.
type ExportConfigNode ¶ added in v0.33.0
type ExportConfigNode struct {
// contains filtered or unexported fields
}
func NewExportConfigNode ¶ added in v0.33.0
func NewExportConfigNode(block *ast.BlockStmt, globals ComponentGlobals) *ExportConfigNode
NewExportConfigNode creates a new ExportConfigNode from an initial ast.BlockStmt. The underlying config isn't applied until Evaluate is called.
func (*ExportConfigNode) Block ¶ added in v0.33.0
func (cn *ExportConfigNode) Block() *ast.BlockStmt
Block implements BlockNode and returns the current block of the managed config node.
func (*ExportConfigNode) Evaluate ¶ added in v0.33.0
func (cn *ExportConfigNode) Evaluate(scope *vm.Scope) error
Evaluate implements BlockNode and updates the arguments for the managed config block by re-evaluating its River block with the provided scope. The managed config block will be built the first time Evaluate is called.
Evaluate will return an error if the River block cannot be evaluated or if decoding to arguments fails.
func (*ExportConfigNode) Label ¶ added in v0.34.0
func (cn *ExportConfigNode) Label() string
func (*ExportConfigNode) NodeID ¶ added in v0.33.0
func (cn *ExportConfigNode) NodeID() string
NodeID implements dag.Node and returns the unique ID for the config node.
func (*ExportConfigNode) Value ¶ added in v0.34.0
func (cn *ExportConfigNode) Value() any
Value returns the value of the export.
type Loader ¶
type Loader struct {
// contains filtered or unexported fields
}
The Loader builds and evaluates ComponentNodes from River blocks.
func NewLoader ¶
func NewLoader(globals ComponentGlobals) *Loader
NewLoader creates a new Loader. Components built by the Loader will be built with co for their options.
func (*Loader) Apply ¶
func (l *Loader) Apply(args map[string]any, componentBlocks []*ast.BlockStmt, configBlocks []*ast.BlockStmt) diag.Diagnostics
Apply loads a new set of components into the Loader. Apply will drop any previously loaded component which is not described in the set of River blocks.
Apply will reuse existing components if there is an existing component which matches the component ID specified by any of the provided River blocks. Reused components will be updated to point at the new River block.
Apply will perform an evaluation of all loaded components before returning. The provided parentContext can be used to provide global variables and functions to components. A child context will be constructed from the parent to expose values of other components.
func (*Loader) Cleanup ¶ added in v0.35.0
func (l *Loader) Cleanup()
Cleanup unregisters any existing metrics.
func (*Loader) Components ¶
func (l *Loader) Components() []*ComponentNode
Components returns the current set of loaded components.
func (*Loader) EvaluateDependencies ¶
func (l *Loader) EvaluateDependencies(c *ComponentNode)
EvaluateDependencies re-evaluates components which depend directly or indirectly on c. EvaluateDependencies should be called whenever a component updates its exports.
The provided parentContext can be used to provide global variables and functions to components. A child context will be constructed from the parent to expose values of other components.
func (*Loader) OriginalGraph ¶ added in v0.28.0
OriginalGraph returns a copy of the graph before Reduce was called. This can be used if you want to show a UI of the original graph before the reduce function was called.
type LoggingConfigNode ¶ added in v0.33.0
type LoggingConfigNode struct {
// contains filtered or unexported fields
}
func NewDefaultLoggingConfigNode ¶ added in v0.33.0
func NewDefaultLoggingConfigNode(globals ComponentGlobals) *LoggingConfigNode
NewDefaultLoggingConfigNode creates a new LoggingConfigNode with nil block and eval. This will force evaluate to use the default logging options for this node.
func NewLoggingConfigNode ¶ added in v0.33.0
func NewLoggingConfigNode(block *ast.BlockStmt, globals ComponentGlobals) *LoggingConfigNode
NewLoggingConfigNode creates a new LoggingConfigNode from an initial ast.BlockStmt. The underlying config isn't applied until Evaluate is called.
func (*LoggingConfigNode) Block ¶ added in v0.33.0
func (cn *LoggingConfigNode) Block() *ast.BlockStmt
Block implements BlockNode and returns the current block of the managed config node.
func (*LoggingConfigNode) Evaluate ¶ added in v0.33.0
func (cn *LoggingConfigNode) Evaluate(scope *vm.Scope) error
Evaluate implements BlockNode and updates the arguments for the managed config block by re-evaluating its River block with the provided scope. The managed config block will be built the first time Evaluate is called.
Evaluate will return an error if the River block cannot be evaluated or if decoding to arguments fails.
func (*LoggingConfigNode) NodeID ¶ added in v0.33.0
func (cn *LoggingConfigNode) NodeID() string
NodeID implements dag.Node and returns the unique ID for the config node.
type ModuleController ¶ added in v0.35.0
type ModuleController interface { component.ModuleController // ModuleIDs returns the list of managed modules in unspecified order. ModuleIDs() []string }
ModuleController is a lower-level interface for module controllers which allows probing for the list of managed modules.
type Queue ¶
type Queue struct {
// contains filtered or unexported fields
}
Queue is an unordered queue of components.
Queue is intended for tracking components that have updated their Exports for later reevaluation.
func (*Queue) Chan ¶
func (q *Queue) Chan() <-chan struct{}
Chan returns a channel which is written to when the queue is non-empty.
func (*Queue) Enqueue ¶
func (q *Queue) Enqueue(c *ComponentNode)
Enqueue inserts a new component into the Queue. Enqueue is a no-op if the component is already in the Queue.
func (*Queue) TryDequeue ¶
func (q *Queue) TryDequeue() *ComponentNode
TryDequeue dequeues a randomly queued component. TryDequeue will return nil if the queue is empty.
type Reference ¶
type Reference struct { Target BlockNode // BlockNode being referenced // Traversal describes which nested field relative to Target is being // accessed. Traversal Traversal }
Reference describes an River expression reference to a BlockNode.
func ComponentReferences ¶
ComponentReferences returns the list of references a component is making to other components.
type RunnableNode ¶
RunnableNode is any dag.Node which can also be run.
type Scheduler ¶
type Scheduler struct {
// contains filtered or unexported fields
}
Scheduler runs components.
func NewScheduler ¶
func NewScheduler() *Scheduler
NewScheduler creates a new Scheduler. Call Synchronize to manage the set of components which are running.
Call Close to stop the Scheduler and all running components.
func (*Scheduler) Close ¶
Close stops the Scheduler and returns after all running goroutines have exited.
func (*Scheduler) Synchronize ¶
func (s *Scheduler) Synchronize(rr []RunnableNode) error
Synchronize synchronizes the running components to those defined by rr.
New RunnableNodes will be launched as new goroutines. RunnableNodes already managed by Scheduler will be kept running, while running RunnableNodes that are not in rr will be shut down and removed.
Existing components will be restarted if they stopped since the previous call to Synchronize.
type TracingConfigNode ¶ added in v0.33.0
type TracingConfigNode struct {
// contains filtered or unexported fields
}
func NewDefaulTracingConfigNode ¶ added in v0.33.0
func NewDefaulTracingConfigNode(globals ComponentGlobals) *TracingConfigNode
NewDefaulTracingConfigNode creates a new TracingConfigNode with nil block and eval. This will force evaluate to use the default tracing options for this node.
func NewTracingConfigNode ¶ added in v0.33.0
func NewTracingConfigNode(block *ast.BlockStmt, globals ComponentGlobals) *TracingConfigNode
NewTracingConfigNode creates a new TracingConfigNode from an initial ast.BlockStmt. The underlying config isn't applied until Evaluate is called.
func (*TracingConfigNode) Block ¶ added in v0.33.0
func (cn *TracingConfigNode) Block() *ast.BlockStmt
Block implements BlockNode and returns the current block of the managed config node.
func (*TracingConfigNode) Evaluate ¶ added in v0.33.0
func (cn *TracingConfigNode) Evaluate(scope *vm.Scope) error
Evaluate implements BlockNode and updates the arguments for the managed config block by re-evaluating its River block with the provided scope. The managed config block will be built the first time Evaluate is called.
Evaluate will return an error if the River block cannot be evaluated or if decoding to arguments fails.
func (*TracingConfigNode) NodeID ¶ added in v0.33.0
func (cn *TracingConfigNode) NodeID() string
NodeID implements dag.Node and returns the unique ID for the config node.