integrations

Documentation

Overview

Package integrations provides a way to run and manage Grafana Agent "integrations," which integrate some external system (such as MySQL) to Grafana Agent's existing metrics, logging, and tracing subsystems.

Integrations are implemented in sub-packages. Every integration must have an implementation of Config that configures the integration. The Config interface is then used to instantiate an instance of the Integration interface.

Implementations of integrations implement extra functionality by implementing interface extensions. The Integration interface is the most basic interface that all integrations must implement. Extensions like the MetricsIntegration interface define an integration that supports metrics.

Extension interfaces are used by the integrations subsystem to enable common use cases. New behaviors can be implemented by manually using the other subsystems of the agent provided in IntegrationOptions.

Index

• Constants
• Variables
• func CompareConfigs(a, b Config) bool
• func MarshalYAML(v interface{}) (interface{}, error)
• func Register(cfg Config, ty Type)
• func RegisterLegacy(cfg v1.Config, ty Type, upgrader UpgradeFunc)
• func UnmarshalYAML(out interface{}, unmarshal func(interface{}) error) error
• type ComparableConfig
• type Config
  • func Registered() []Config
• type Configs
• type Endpoint
• type FuncIntegration
  • func (fi FuncIntegration) Handler(prefix string) (http.Handler, error)
  • func (fi FuncIntegration) RunIntegration(ctx context.Context) error
• type Globals
  • func (g Globals) CloneAgentBaseURL() *url.URL
• type HTTPIntegration
• type Integration
• type MetricsIntegration
• type MetricsSubsystemOptions
• type SubsystemOptions
  • func (o *SubsystemOptions) ApplyDefaults(mcfg *metrics.Config) error
  • func (o SubsystemOptions) MarshalYAML() (interface{}, error)
  • func (o *SubsystemOptions) UnmarshalYAML(unmarshal func(interface{}) error) error
• type Type
  • func RegisteredType(c Config) (Type, bool)
• type UpdateIntegration
• type UpgradeFunc
• type UpgradedConfig

Constants

const (
	// IntegrationsSDEndpoint is the API endpoint where the integration HTTP SD
	// API is exposed. The API uses query parameters to customize what gets
	// returned by discovery.
	IntegrationsSDEndpoint = "/agent/api/v1/metrics/integrations/sd"

	// IntegrationsAutoscrapeTargetsEndpoint is the API endpoint where autoscrape
	// integrations targets are exposed.
	IntegrationsAutoscrapeTargetsEndpoint = "/agent/api/v1/metrics/integrations/targets"
)

Variables

var (
	DefaultSubsystemOptions = SubsystemOptions{
		Metrics: DefaultMetricsSubsystemOptions,
	}

	DefaultMetricsSubsystemOptions = MetricsSubsystemOptions{
		Autoscrape: autoscrape.DefaultGlobal,
	}
)

DefaultSubsystemOptions holds the default settings for a Controller.

var (
	// ErrInvalidUpdate is returned by ApplyConfig when the config cannot
	// be dynamically applied.
	ErrInvalidUpdate = fmt.Errorf("invalid dynamic update")
)

var NoOpIntegration = FuncIntegration(func(ctx context.Context) error {
	<-ctx.Done()
	return nil
})

NoOpIntegration is an Integration that does nothing.

Functions

func CompareConfigs

func CompareConfigs(a, b Config) bool

CompareConfigs will return true if a and b are equal. If neither a nor b implements ComparableConfig, then configs are compared by marshaling to YAML and comparing the results.

func MarshalYAML

func MarshalYAML(v interface{}) (interface{}, error)

MarshalYAML helps implement yaml.Marshaler for structs that have a Configs field that should be inlined in the YAML string.

func Register

func Register(cfg Config, ty Type)

Register dynamically registers a new integration. The Config will represent the configuration that controls the specific integration. Registered Configs may be loaded using UnmarshalYAML or manually constructed.

ty controls how the integration can be unmarshaled from YAML.

Register panics if cfg is not a pointer.

func RegisterLegacy

func RegisterLegacy(cfg v1.Config, ty Type, upgrader UpgradeFunc)

RegisterLegacy registers a v1.Config. upgrader will be used to upgrade it. upgrader will only be invoked after unmarshaling cfg from YAML, and the upgraded Config will be unwrapped again when marshaling back to YAML.

RegisterLegacy only exists for the transition period where the v2 integrations subsystem is an experiment. RegisterLegacy will be removed at a later date.

func UnmarshalYAML

func UnmarshalYAML(out interface{}, unmarshal func(interface{}) error) error

UnmarshalYAML helps implement yaml.Unmarshaller for structs that have a Configs field that should be inlined in the YAML string. Code adapted from Prometheus:

https://github.com/prometheus/prometheus/blob/511511324adfc4f4178f064cc104c2deac3335de/discovery/registry.go#L111

Types

type ComparableConfig

type ComparableConfig interface {
	Config

	// ConfigEquals should return true if c is equal to the ComparableConfig.
	ConfigEquals(c Config) bool
}

ComparableConfig extends Config with an ConfigEquals method.

type Config

type Config interface {
	// Name returns the YAML field name of the integration. Name is used
	// when unmarshaling the Config from YAML.
	Name() string

	// ApplyDefaults should apply default settings to Config.
	ApplyDefaults(Globals) error

	// Identifier returns a string to uniquely identify the integration created
	// by this Config. Identifier must be unique for each integration that shares
	// the same Name.
	//
	// If there is no reasonable identifier to use for an integration,
	// Globals.AgentIdentifier may be used by default.
	Identifier(Globals) (string, error)

	// NewIntegration should return a new Integration using the provided
	// Globals to help initialize the Integration.
	//
	// NewIntegration must be idempotent for a Config. Use
	// Integration.RunIntegration to do anything with side effects, such as
	// opening a port.
	NewIntegration(log.Logger, Globals) (Integration, error)
}

Config provides a configuration and constructor for an integration.

func Registered

func Registered() []Config

Registered all Configs that were passed to Register or RegisterLegacy. Each call will generate a new set of configs.

type Configs

type Configs []Config

Configs is a list of integrations. Note that Configs does not implement yaml.Unmarshaler or yaml.Marshaler. Use the UnmarshalYAML or MarshalYAML methods to deal with integrations defined from YAML.

type Endpoint

type Endpoint struct {
	// Hostname (and optional port) where endpoint is exposed.
	Host string
	// Base prefix of the endpoint.
	Prefix string
}

Endpoint is a location where something is exposed.

type FuncIntegration

type FuncIntegration func(ctx context.Context) error

FuncIntegration is a function that implements Integration.

func (FuncIntegration) Handler

func (fi FuncIntegration) Handler(prefix string) (http.Handler, error)

Handler implements HTTPIntegration

func (FuncIntegration) RunIntegration

func (fi FuncIntegration) RunIntegration(ctx context.Context) error

RunIntegration implements Integration.

type Globals

type Globals struct {
	// AgentIdentifier provides an identifier for the running agent. This can
	// be used for labelling whenever appropriate.
	//
	// AgentIdentifier will be set to the hostname:port of the running agent.
	// TODO(rfratto): flag to override identifier at agent level?
	AgentIdentifier string

	// Options the integrations subsystem is using.
	SubsystemOpts SubsystemOptions
	// BaseURL to use to invoke methods against the embedded HTTP server.
	AgentBaseURL *url.URL
	// Dialer to use for making connections. May be nil.
	DialContextFunc server.DialContextFunc
}

Globals are used to pass around subsystem-wide settings that integrations can take advantage of.

func (Globals) CloneAgentBaseURL

func (g Globals) CloneAgentBaseURL() *url.URL

CloneAgentBaseURL returns a copy of AgentBaseURL that can be modified.

type HTTPIntegration

type HTTPIntegration interface {
	Integration

	// Handler returns an http.Handler. Handler will be invoked for any endpoint
	// under prefix. If Handler returns nil, nothing will be called. Handler
	// may be called multiple times.
	//
	// prefix will not be removed from the HTTP request by default.
	Handler(prefix string) (http.Handler, error)
}

HTTPIntegration is an integration that exposes an HTTP handler.

Integrations are given a unique base path prefix where HTTP requests will be routed. The prefix chosen for an integration is not guaranteed to be predictable.

type Integration

type Integration interface {
	// RunIntegration starts the integration and performs background tasks. It
	// must not return until ctx is canceled, even if there is no work to do.
	//
	// An error will be returned if the integration failed. Integrations will
	// never return the ctx error.
	RunIntegration(ctx context.Context) error
}

An Integration integrates some external system with Grafana Agent's existing subsystems.

All integrations must at least implement this interface. More behaviors can be added by implementing additional *Integration interfaces, such as HTTPIntegration.

type MetricsIntegration

type MetricsIntegration interface {
	HTTPIntegration

	// Targets should return the current set of active targets exposed by this
	// integration. Targets may be called multiple times throughout the lifecycle
	// of the integration. Targets will not be called when the integration is not
	// running.
	//
	// prefix will be the same prefixed passed to HTTPIntegration.Handler and
	// can be used to update __metrics_path__ for targets.
	Targets(ep Endpoint) []*targetgroup.Group

	// ScrapeConfigs configures automatic scraping of targets. ScrapeConfigs
	// is optional if an integration should not scrape itself.
	//
	// Unlike Targets, ScrapeConfigs is only called once per config load, and may be
	// called before the integration runs. Use the provided discovery.Configs to
	// discover the targets exposed by this integration.
	ScrapeConfigs(discovery.Configs) []*autoscrape.ScrapeConfig
}

MetricsIntegration is an integration that exposes Prometheus scrape targets.

It is assumed, but not required, that HTTPIntegration is also implemented to expose metrics. See HTTPIntegration for more information about how HTTP works with integrations.

type MetricsSubsystemOptions

type MetricsSubsystemOptions struct {
	Autoscrape autoscrape.Global `yaml:"autoscrape,omitempty"`
}

MetricsSubsystemOptions controls how metrics integrations behave.

type SubsystemOptions

type SubsystemOptions struct {
	Metrics MetricsSubsystemOptions `yaml:"metrics,omitempty"`

	// Configs are configurations of integration to create. Unmarshaled through
	// the custom UnmarshalYAML method of Controller.
	Configs Configs `yaml:"-"`
}

SubsystemOptions controls how the integrations subsystem behaves.

func (*SubsystemOptions) ApplyDefaults

func (o *SubsystemOptions) ApplyDefaults(mcfg *metrics.Config) error

ApplyDefaults will apply defaults to o.

func (SubsystemOptions) MarshalYAML

func (o SubsystemOptions) MarshalYAML() (interface{}, error)

MarshalYAML implements yaml.Marshaler for SubsystemOptions. Integrations will be marshaled inline.

func (*SubsystemOptions) UnmarshalYAML

func (o *SubsystemOptions) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML implements yaml.Unmarshaler for SubsystemOptions. Inline integrations will be unmarshaled into o.Configs.

type Type

type Type int

Type determines a specific type of integration.

const (
	// TypeInvalid is an invalid type.
	TypeInvalid Type = iota

	// TypeSingleton is an integration that can only be defined exactly once in
	// the config, unmarshaled through "<integration name>"
	TypeSingleton

	// TypeMultiplex is an integration that can only be defined through an array,
	// unmarshaled through "<integration name>_configs"
	TypeMultiplex

	// TypeEither is an integration that can be unmarshaled either as a singleton
	// or as an array, but not both.
	//
	// Deprecated. Use either TypeSingleton or TypeMultiplex for new integrations.
	TypeEither
)

func RegisteredType

func RegisteredType(c Config) (Type, bool)

RegisteredType returns the registered integrations.Type for c.

type UpdateIntegration

type UpdateIntegration interface {
	Integration

	// ApplyConfig should apply the config c to the integration. An error can be
	// returned if the Config is invalid. When this happens, the old config will
	// continue to run.
	//
	// If ApplyConfig returns ErrInvalidUpdate, the integration will be
	// recreated.
	ApplyConfig(c Config, g Globals) error
}

UpdateIntegration is an Integration whose config can be updated dynamically. Integrations that do not implement this interface will be shut down and re-instantiated with the new Config.

type UpgradeFunc

type UpgradeFunc func(cfg v1.Config, common common.MetricsConfig) UpgradedConfig

UpgradeFunc upgrades cfg to a UpgradedConfig.

type UpgradedConfig

type UpgradedConfig interface {
	Config

	// LegacyConfig returns the old v1.Config.
	LegacyConfig() (v1.Config, common.MetricsConfig)
}

UpgradedConfig is a v2 Config that was constructed through a legacy v1.Config. It allows unwrapping to retrieve the original config for the purposes of marshaling or unmarshaling.