alloy

Documentation

Overview

Package alloy implements the Alloy component graph system. Alloy configuration sources are parsed from Alloy syntax, which contain a listing of components to run.

Components

Each component has a set of arguments (Alloy attributes and blocks) and optionally a set of exported fields. Components can reference the exports of other components using Alloy expressions.

See the top-level component package for more information on components, and subpackages for defined components.

Component Health

A component will have various health states during its lifetime:

1. Unknown: The initial health state for new components.
2. Healthy: A healthy component
3. Unhealthy: An unhealthy component.
4. Exited: A component which is no longer running.

Health states are paired with a time for when the health state was generated and a message providing more detail for the health state.

Components can report their own health states. The health state reported by a component is merged with the Alloy-level health of that component: an error when evaluating the configuration for a component will always be reported as unhealthy until the next successful evaluation.

Node Evaluation

The process of converting the Alloy block associated with a node into the appropriate Go struct is called "node evaluation."

Nodes are only evaluated after all nodes they reference have been evaluated; cyclic dependencies are invalid.

If a node updates its Exports at runtime, other nodes which directly or indirectly reference the updated node will have their Arguments re-evaluated.

The arguments and exports for a node will be left in their last valid state if a node shuts down or is given an invalid config. This prevents a domino effect of a single failed node taking down other node which are otherwise healthy.

Index

• type Alloy
  • func New(o Options) *Alloy
  • func (f *Alloy) GetComponent(id component.ID, opts component.InfoOptions) (*component.Info, error)
  • func (f *Alloy) GetService(name string) (service.Service, bool)
  • func (f *Alloy) GetServiceConsumers(serviceName string) []service.Consumer
  • func (f *Alloy) ListComponents(moduleID string, opts component.InfoOptions) ([]*component.Info, error)
  • func (f *Alloy) LoadSource(source *Source, args map[string]any) error
  • func (f *Alloy) NewController(id string) service.Controller
  • func (f *Alloy) Ready() bool
  • func (f *Alloy) Run(ctx context.Context)
• type Options
• type Source
  • func ParseSource(name string, bb []byte) (*Source, error)
  • func ParseSources(sources map[string][]byte) (*Source, error)
  • func (s *Source) RawConfigs() map[string][]byte
  • func (s *Source) SHA256() [sha256.Size]byte

Types

type Alloy

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

Alloy is the Alloy system.

func New

func New(o Options) *Alloy

New creates a new, unstarted Alloy controller. Call Run to run the controller.

func (*Alloy) GetComponent

func (f *Alloy) GetComponent(id component.ID, opts component.InfoOptions) (*component.Info, error)

GetComponent implements component.Provider.

func (*Alloy) GetService

func (f *Alloy) GetService(name string) (service.Service, bool)

GetService implements service.Host. It looks up a service.Service by name.

func (*Alloy) GetServiceConsumers

func (f *Alloy) GetServiceConsumers(serviceName string) []service.Consumer

GetServiceConsumers implements service.Host. It returns a slice of component.Component and [service.Service]s which declared a dependency on the named service.

func (*Alloy) ListComponents

func (f *Alloy) ListComponents(moduleID string, opts component.InfoOptions) ([]*component.Info, error)

ListComponents implements component.Provider.

func (*Alloy) LoadSource

func (f *Alloy) LoadSource(source *Source, args map[string]any) error

LoadSource synchronizes the state of the controller with the current config source. Components in the graph will be marked as unhealthy if there was an error encountered during Load.

The controller will only start running components after Load is called once without any configuration errors. LoadSource uses default loader configuration.

func (*Alloy) NewController

func (f *Alloy) NewController(id string) service.Controller

NewController returns a new, unstarted, isolated Alloy controller so that services can instantiate their own components.

func (*Alloy) Ready

func (f *Alloy) Ready() bool

Ready returns whether the Alloy controller has finished its initial load.

func (*Alloy) Run

func (f *Alloy) Run(ctx context.Context)

Run starts the Alloy controller, blocking until the provided context is canceled. Run must only be called once.

type Options

type Options struct {
	// ControllerID is an identifier used to represent the controller.
	// ControllerID is used to generate a globally unique display name for
	// components in a binary where multiple controllers are used.
	//
	// If running multiple Alloy controllers, each controller must have a
	// different value for ControllerID to be able to differentiate between
	// components in telemetry data.
	ControllerID string

	// Logger to use for controller logs and components. A no-op logger will be
	// created if this is nil.
	Logger *logging.Logger

	// Tracer for components to use. A no-op tracer will be created if this is
	// nil.
	Tracer *tracing.Tracer

	// Directory where components can write data. Constructed components will be
	// given a subdirectory of DataPath using the local ID of the component.
	//
	// If running multiple Alloy controllers, each controller must have a
	// different value for DataPath to prevent components from colliding.
	DataPath string

	// Reg is the prometheus register to use
	Reg prometheus.Registerer

	// MinStability is the minimum stability level of features that can be used by the collector. It is defined by
	// the user, for example, via command-line flags.
	MinStability featuregate.Stability

	// OnExportsChange is called when the exports of the controller change.
	// Exports are controlled by "export" configuration blocks. If
	// OnExportsChange is nil, export configuration blocks are not allowed in the
	// loaded config source.
	OnExportsChange func(exports map[string]any)

	// List of Services to run with the Alloy controller.
	//
	// Services are configured when LoadFile is invoked. Services are started
	// when the Alloy controller runs after LoadFile is invoked at least once.
	Services []service.Service
}

Options holds static options for an Alloy controller.

type Source

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

A Source holds the contents of a parsed Alloy configuration source module.

func ParseSource

func ParseSource(name string, bb []byte) (*Source, error)

ParseSource parses the Alloy file specified by bb into a File. name should be the name of the file used for reporting errors.

bb must not be modified after passing to ParseSource.

func ParseSources

func ParseSources(sources map[string][]byte) (*Source, error)

ParseSources parses the map of sources and combines them into a single Source. sources must not be modified after calling ParseSources.

func (*Source) RawConfigs

func (s *Source) RawConfigs() map[string][]byte

RawConfigs returns the raw source content used to create Source. Do not modify the returned map.

func (*Source) SHA256

func (s *Source) SHA256() [sha256.Size]byte

SHA256 returns the sha256 checksum of the source. Do not modify the returned byte array.