opampextension

README

OpAMP Agent Extension

Status
Stability	alpha
Distributions	contrib, k8s
Issues
Code coverage
Code Owners	@portertech, @evan-bradley, @tigrannajaryan, @douglascamata, @dpaasman00

Configuration

The following settings are required:

• server: The OpAMP server connection settings.
  • ws: The OpAMP websocket transport settings.
    • endpoint (no default): The OpAMP server websocket endpoint (URL).

The following settings are optional for the websocket client:

• server: The OpAMP server connection settings.
  • ws: The OpAMP websocket transport settings.
    • tls: TLS settings.
    • headers: HTTP headers to set.
    • auth: The ID of an auth extension to use for authentication.

The following settings are optional for the HTTP client:

• server: The OpAMP server connection settings.
  • http: The OpAMP HTTP transport settings.
    • tls: TLS settings.
    • headers: HTTP headers to set.
    • polling_interval: The interval at which the extension will poll the server. Defaults to 30s.
    • auth: The ID of an auth extension to use for authentication.

The following settings are optional for both transports:

• instance_uid: A UUIDv7 formatted as a 36 character string in canonical representation. Auto-generated on start if missing. Setting this ensures the instance UID remains constant across process restarts.
• capabilities: Keys with boolean true/false values that enable a particular OpAMP capability.
  • reports_effective_config: Whether to enable the OpAMP ReportsEffectiveConfig capability. Default is true.
  • reports_health: Whether to enable the OpAMP ReportsHealth capability. Default is true.
  • reports_available_components: Whether to enable the OpAMP ReportsAvailableComponents capability. Default is true.
  • accepts_restart_command: Whether to enable the OpAMP AcceptsRestartCommand capability. Default is false. The extension sends a SIGHUP signal to the collector to initiate a restart (however, SIGHUP isn't supported on windows systems, so it will be ignored). This functionality is also behind a feature gate (alpha) called extension.opampextension.RemoteRestarts
• agent_description: Setting that modifies the agent description reported to the OpAMP server.
  • include_resource_attributes: Copy the Collector's resource attributes into the set of non-identifying attributes in the agent description.
  • non_identifying_attributes: A map of key value pairs that will be added to the non-identifying attributes reported to the OpAMP server. If an attribute collides with the default non-identifying attributes that are automatically added, the ones specified here take precedence.
• ppid: An optional process ID to monitor. When this process is no longer running, the extension will emit a fatal error, causing the collector to exit. This is meant to be set by the Supervisor or some other parent process, and should not be configured manually.
• ppid_poll_interval: The poll interval between check for whether ppid is still alive or not. Defaults to 5 seconds.

Example

extensions:
  opamp:
    server:
      ws:
        endpoint: wss://127.0.0.1:4320/v1/opamp

Custom Messages

Other components may use a configured OpAMP extension to send and receive custom messages to and from an OpAMP server.

See the opampcustommessages module for more information on the custom message API.

Using the AcceptsRestartCommand capability to orchestrate collector config updates

If the accepts_restart_command capability is enabled (along with the extension.opampextension.RemoteRestarts feature gate), upon receiving a restart ServerToAgentCommand, the extension will send a SIGHUP signal to the Collector process.

The SIGHUP signal is trapped in the Collector and initiates a graceful restart of all the components by restarting the Collectors service, which restarts all components, pipelines, and Collector self-monitoring. This functionality might be desired if the Collector's config was updated, as the restart also fetches all configuration sources passed to the Collector through --config flags passed to the command invocation.

NOTE on the SIGHUP signal for restarts: SIGHUP is not supported on Windows, and the collector will error on startup if the capability and feature gate are enabled (until the collector can also handle a cross-platform signal like SIGUSR2).

Please note: an invalid config will cause the Collector to error out and stay down until it is manually restarted using some other mechanism (since the OpAMP extension won't be active). Regular healthchecks and using the Collector's validate subcommand to validate config before applying it are highly recommended when using this functionality to prevent data loss due to config issues.

Status

This OpenTelemetry OpAMP agent extension is intended to support the OpAMP Supervisor.

Documentation

Index

• func NewFactory() extension.Factory
• type AgentDescription
• type Capabilities
• type Config
  • func (cfg *Config) Validate() error
• type OpAMPServer
  • func (s OpAMPServer) GetAuthExtensionID() component.ID
  • func (s OpAMPServer) GetClient(logger *zap.Logger) client.OpAMPClient
  • func (s OpAMPServer) GetEndpoint() string
  • func (s OpAMPServer) GetHeaders() map[string]configopaque.String
  • func (s OpAMPServer) GetPollingInterval() time.Duration
  • func (s OpAMPServer) GetTLSConfig(ctx context.Context) (*tls.Config, error)

Functions

func NewFactory

func NewFactory() extension.Factory

Types

type AgentDescription

type AgentDescription struct {
	// NonIdentifyingAttributes are a map of key-value pairs that may be specified to provide
	// extra information about the agent to the OpAMP server.
	NonIdentifyingAttributes map[string]string `mapstructure:"non_identifying_attributes"`
	// IncludeResourceAttributes determines whether the agent should copy its resource attributes
	// to the non identifying attributes. (default: false)
	IncludeResourceAttributes bool `mapstructure:"include_resource_attributes"`
}

type Capabilities

type Capabilities struct {
	// ReportsEffectiveConfig enables the OpAMP ReportsEffectiveConfig Capability. (default: true)
	ReportsEffectiveConfig bool `mapstructure:"reports_effective_config"`
	// ReportsHealth enables the OpAMP ReportsHealth Capability. (default: true)
	ReportsHealth bool `mapstructure:"reports_health"`
	// ReportsAvailableComponents enables the OpAMP ReportsAvailableComponents Capability (default: true)
	ReportsAvailableComponents bool `mapstructure:"reports_available_components"`
	// AcceptsRestartCommand enables the OpAMP AcceptsRestartCommand Capability (default: false)
	AcceptsRestartCommand bool `mapstructure:"accepts_restart_command"`
}

type Config

type Config struct {
	Server *OpAMPServer `mapstructure:"server"`

	// InstanceUID is a UUID formatted as a 36 character string in canonical
	// representation. Auto-generated on start if missing.
	InstanceUID string `mapstructure:"instance_uid"`

	// Capabilities contains options to enable a particular OpAMP capability
	Capabilities Capabilities `mapstructure:"capabilities"`

	// Agent descriptions contains options to modify the AgentDescription message
	AgentDescription AgentDescription `mapstructure:"agent_description"`

	// PPID is the process ID of the parent for the collector. If the PPID is specified,
	// the extension will continuously poll for the status of the parent process, and emit a fatal error
	// when the parent process is no longer running.
	// If unspecified, the orphan detection logic does not run.
	PPID int32 `mapstructure:"ppid"`

	// PPIDPollInterval is the time between polling for whether PPID is running.
	PPIDPollInterval time.Duration `mapstructure:"ppid_poll_interval"`
}

Config contains the configuration for the opamp extension. Trying to mirror the OpAMP supervisor config for some consistency.

func (*Config) Validate

func (cfg *Config) Validate() error

Validate checks if the extension configuration is valid

type OpAMPServer

type OpAMPServer struct {
	WS   *commonFields `mapstructure:"ws,omitempty"`
	HTTP *httpFields   `mapstructure:"http,omitempty"`
}

OpAMPServer contains the OpAMP transport configuration.

func (OpAMPServer) GetAuthExtensionID

func (s OpAMPServer) GetAuthExtensionID() component.ID

func (OpAMPServer) GetClient

func (s OpAMPServer) GetClient(logger *zap.Logger) client.OpAMPClient

func (OpAMPServer) GetEndpoint

func (s OpAMPServer) GetEndpoint() string

func (OpAMPServer) GetHeaders

func (s OpAMPServer) GetHeaders() map[string]configopaque.String

func (OpAMPServer) GetPollingInterval

func (s OpAMPServer) GetPollingInterval() time.Duration

func (OpAMPServer) GetTLSConfig

func (s OpAMPServer) GetTLSConfig(ctx context.Context) (*tls.Config, error)

GetTLSConfig returns a TLS config if the endpoint is secure (wss or https)