opampextension

README

OpAMP Agent Extension

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

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 websocket 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.
• 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.

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"`
}

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)