configsource

Documentation

Overview

Package configsource is an experimental package that defines the interface of "configuration sources," e.g., Vault, ZooKeeper, etcd2, and others. Configuration sources retrieve values from their respective storages. A configuration parser/loader can inject these values in the configuration data used by the collector. ATTENTION: the package is still experimental and subject to changes without advanced notice.

Index

• Variables
• type ConfigSource
• type Retrieved
• type Watchable

Variables

var ErrSessionClosed = errors.New("parent session was closed")

ErrSessionClosed is returned by WatchForUpdate functions when its parent Session object is closed. This error can be wrapped with additional information. Callers trying to identify this specific error must use errors.Is.

var ErrValueUpdated = errors.New("configuration must retrieve the updated value")

ErrValueUpdated is returned by WatchForUpdate functions when the value being watched was changed or expired and needs to be retrieved again. This error can be wrapped with additional information. Callers trying to identify this specific error must use errors.Is.

Types

type ConfigSource

type ConfigSource interface {
	// Retrieve goes to the configuration source and retrieves the selected data which
	// contains the value to be injected in the configuration and the corresponding watcher that
	// will be used to monitor for updates of the retrieved value. The retrieved value is selected
	// according to the selector and the params passed in the call to Retrieve.
	//
	// The selector is a string that is required on all invocations, the params are optional. Each
	// implementation handles the generic params according to their requirements.
	Retrieve(ctx context.Context, selector string, paramsConfigMap *confmap.Conf) (Retrieved, error)

	// Close signals that the configuration for which it was used to retrieve values is no longer in use
	// and the object should close and release any watchers that it may have created.
	// This method must be called when the configuration session ends, either in case of success or error.
	Close(ctx context.Context) error
}

ConfigSource is the interface to be implemented by objects used by the collector to retrieve external configuration information.

ConfigSource object will be used to retrieve full configuration or data to be injected into a configuration.

The ConfigSource object should use its creation according to the source needs: lock resources, open connections, etc. An implementation, for instance, can use the creation time to prevent torn configurations, by acquiring a lock (or some other mechanism) that prevents concurrent changes to the configuration during time that data is being retrieved from the source.

The code managing the ConfigSource instance must guarantee that the object is not used concurrently.

type Retrieved

type Retrieved interface {
	// Value is the retrieved data that will be injected on the configuration.
	Value() interface{}
}

Retrieved holds the result of a call to the Retrieve method of a Session object.

type Watchable

type Watchable interface {
	// WatchForUpdate is used to monitor for updates on the retrieved value.
	// It must not return until one of the following happens:
	//
	// 1. An update is detected for the monitored value. In this case the function should
	//    return ErrValueUpdated or an error wrapping it.
	//
	// 2. The parent Session object is closed, in which case the method should return
	//    ErrSessionClosed or an error wrapping it.
	//
	// 3. An error happens while watching for updates. The method should not return
	//    on first instances of transient errors, optionally there should be
	//    configurable thresholds to control for how long such errors can be ignored.
	WatchForUpdate() error
}

Watchable is an optional interface that Retrieved can implement if the given source supports monitoring for updates.