integrations

package
v0.43.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 11, 2024 License: Apache-2.0 Imports: 30 Imported by: 0

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

View Source 
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

View Source 
var (
	DefaultSubsystemOptions = SubsystemOptions{
		Metrics: DefaultMetricsSubsystemOptions,
	}

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

DefaultSubsystemOptions holds the default settings for a Controller.

View Source 
var (
	// ErrInvalidUpdate is returned by ApplyConfig when the config cannot
	// be dynamically applied.
	ErrInvalidUpdate = fmt.Errorf("invalid dynamic update")
)
View Source 
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

	Metrics *metrics.Agent // Metrics subsystem
	Logs    *logs.Logs     // Logs subsystem
	Tracing *traces.Traces // Traces subsystem

	// 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 Subsystem 

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

Subsystem runs the integrations subsystem, managing a set of integrations.

func NewSubsystem 

func NewSubsystem(l log.Logger, globals Globals) (*Subsystem, error)

NewSubsystem creates and starts a new integrations Subsystem. Every field in IntegrationOptions must be filled out.

func (*Subsystem) ApplyConfig 

func (s *Subsystem) ApplyConfig(globals Globals) error

ApplyConfig updates the configuration of the integrations subsystem.

func (*Subsystem) Stop 

func (s *Subsystem) Stop()

Stop stops the manager and all running integrations. Blocks until all running integrations exit.

func (*Subsystem) WireAPI 

func (s *Subsystem) WireAPI(r *mux.Router)

WireAPI hooks up integration endpoints to r.

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 TargetOptions 

type TargetOptions struct {
	// Integrations is the set of integrations to return. An empty slice will
	// default to returning all integrations.
	Integrations []string
	// Instance matches a specific instance from all integrations. An empty
	// string will match any instance.
	Instance string
}

TargetOptions controls which targets should be returned by the subsystem.

func TargetOptionsFromParams 

func TargetOptionsFromParams(u url.Values) (TargetOptions, error)

TargetOptionsFromParams creates TargetOptions from parsed URL query parameters.

func (TargetOptions) ToParams 

func (to TargetOptions) ToParams() url.Values

ToParams will convert to into URL query parameters.

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.

Source Files

View all Source files

Directories

Path Synopsis
Package agent is an "example" integration that has very little functionality, but is still useful in practice.
 Package agent is an "example" integration that has very little functionality, but is still useful in practice.
Package apache_http embeds https://github.com/Lusitaniae/apache_exporter
 Package apache_http embeds https://github.com/Lusitaniae/apache_exporter
Package autoscrape implements a scraper for integrations.
 Package autoscrape implements a scraper for integrations.
Package eventhandler watches for Kubernetes Event objects and hands them off to Agent's Logs subsystem (embedded promtail)
 Package eventhandler watches for Kubernetes Event objects and hands them off to Agent's Logs subsystem (embedded promtail)
Package snmp_exporter embeds https://github.com/prometheus/snmp_exporter
 Package snmp_exporter embeds https://github.com/prometheus/snmp_exporter

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.