govppmux

package
v2.0.0+incompatible Latest Latest
Warning

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

Go to latest
Published: Apr 2, 2019 License: Apache-2.0 Imports: 23 Imported by: 0

README

GoVPP Mux

The govppmux is a Core Agent Plugin which allows other plugins to access VPP independently on each other by means of connection multiplexing.

Any plugin (core or external) that interacts with VPP can ask govppmux to get its own, potentially customized, communication channel to running VPP instance. Behind the scenes, all channels share the same connection created during the plugin initialization using govpp core.

API

Connection

By default, GoVPP connects to that instance of VPP which uses the default shared memory segment prefix. This is because it is assumed that there is only a single VPP running in a sand-boxed environment together with the agent (e.g. through containerization). In case VPP runs with customized SHM prefix, or there are several VPP instances running, GoVPP needs to know the prefix in order to connect to the correct VPP instance - the prefix has to be put in the govppmux configuration file (govpp.conf) with key shm-prefix and value matching VPP shared memory prefix.

Multiplexing

NewAPIChannel returns a new API channel for communication with VPP via govpp core. It uses default buffer sizes for the request and reply Go channels (by default both are 100 messages long).

If it is expected that the VPP may get overloaded at peak loads, for example if the user plugin sends configuration requests in bulks, then it is recommended to use NewAPIChannelBuffered and increase the buffer size for requests appropriately. Similarly, NewAPIChannelBuffered allows to configure the size of the buffer for responses. This is also useful since the buffer for responses is also used to carry VPP notifications and statistics which may temporarily rapidly grow in size and frequency. By increasing the reply channel size, the probability of dropping messages from VPP decreases at the cost of increased memory footprint.

Example

The following example shows how to dump VPP interfaces using a multi-response request:

// Create a new VPP channel with the default configuration.
plugin.vppCh, err = govppmux.NewAPIChannel()
if err != nil {
    // Handle error condition...
}
// Close VPP channel.
defer safeclose.Close(plugin.vppCh)

req := &interfaces.SwInterfaceDump{}
reqCtx := plugin.vppCh.SendMultiRequest(req)

for {
    msg := &interfaces.SwInterfaceDetails{}
    stop, err := reqCtx.ReceiveReply(msg)
    if err != nil {
        // Handle error condition...
    }

    // Break out of the loop in case there are no more messages.
    if stop {
        break
    }

    log.Info("Found interface with sw_if_index=", msg.SwIfIndex)
    // Process the message...
}

Configuration

The plugin allows to configure parameters of vpp health-check probe. The items that can be configured are:

  • health check probe interval - time between health check probes
  • health check reply timeout - if the reply doesn't arrive until timeout elapses probe is considered failed
  • health check threshold - number of consequent failed health checks until an error is reported
  • reply timeout - if the reply from channel doesn't arrive until timeout elapses, the request fails
  • shm-prefix - used for connection to a VPP instance which is not using default shared memory prefix
  • resync-after-reconnect - allows to run resync after recoonection

Trace

Duration of the VPP binary api call can be measured using trace feature. These data are logged after every event(any resync, interfaces, bridge domains, fib entries etc.). Enable trace in govpp.conf:

trace-enabled: true or trace-enabled: false

Trace is disabled by default (if there is no config available).

Documentation

Overview

Package govppmux implements the GoVPPMux plugin that allows multiple plugins to share a single connection to VPP.

Index

Constants

This section is empty.

Variables

View Source
var DefaultPlugin = *NewPlugin()

DefaultPlugin is default instance of Plugin

View Source
var (
	UseSocketClient = os.Getenv("GOVPPMUX_NOSOCK") == ""
)

Functions

func NewStatsAdapter added in v1.8.1

func NewStatsAdapter(socketName string) adapter.StatsAPI

NewStatsAdapter returns stats vpp api adapter, used for reading statistics with vppapiclient library.

func NewVppAdapter added in v1.4.0

func NewVppAdapter(shmPrefix string) adapter.VppAPI

NewVppAdapter returns real vpp api adapter, used for building with vppapiclient library.

Types

type API added in v1.0.4

type API interface {
	// NewAPIChannel returns a new API channel for communication with VPP via govpp core.
	// It uses default buffer sizes for the request and reply Go channels.
	//
	// Example of binary API call from some plugin using GOVPP:
	//      ch, _ := govpp_mux.NewAPIChannel()
	//      ch.SendRequest(req).ReceiveReply
	NewAPIChannel() (govppapi.Channel, error)

	// NewAPIChannelBuffered returns a new API channel for communication with VPP via govpp core.
	// It allows to specify custom buffer sizes for the request and reply Go channels.
	//
	// Example of binary API call from some plugin using GOVPP:
	//      ch, _ := govpp_mux.NewAPIChannelBuffered(100, 100)
	//      ch.SendRequest(req).ReceiveReply
	NewAPIChannelBuffered(reqChanBufSize, replyChanBufSize int) (govppapi.Channel, error)
}

API for other plugins to get connectivity to VPP.

type Config added in v1.0.5

type Config struct {
	TraceEnabled             bool          `json:"trace-enabled"`
	ReconnectResync          bool          `json:"resync-after-reconnect"`
	HealthCheckProbeInterval time.Duration `json:"health-check-probe-interval"`
	HealthCheckReplyTimeout  time.Duration `json:"health-check-reply-timeout"`
	HealthCheckThreshold     int           `json:"health-check-threshold"`
	ReplyTimeout             time.Duration `json:"reply-timeout"`
	// The prefix prepended to the name used for shared memory (SHM) segments. If not set,
	// shared memory segments are created directly in the SHM directory /dev/shm.
	ShmPrefix       string `json:"shm-prefix"`
	StatsSocketName string `json:"stats-socket-name"`
	// How many times can be request resent in case vpp is suddenly disconnected.
	RetryRequestCount int `json:"retry-request-count"`
	// Time between request resend attempts. Default is 500ms.
	RetryRequestTimeout time.Duration `json:"retry-request-timeout"`
}

Config groups the configurable parameter of GoVpp.

type Deps added in v1.0.2

type Deps struct {
	infra.PluginDeps
	StatusCheck statuscheck.PluginStatusWriter
	Resync      *resync.Plugin
}

Deps groups injected dependencies of plugin so that they do not mix with other plugin fields.

type Option added in v1.8.1

type Option func(*Plugin)

Option is a function that acts on a Plugin to inject Dependencies or configuration

func UseDeps added in v1.8.1

func UseDeps(cb func(*Deps)) Option

UseDeps returns Option that can inject custom dependencies.

type Plugin added in v1.8.1

type Plugin struct {
	Deps
	// contains filtered or unexported fields
}

Plugin implements the govppmux plugin interface.

func NewPlugin added in v1.8.1

func NewPlugin(opts ...Option) *Plugin

NewPlugin creates a new Plugin with the provides Options

func (*Plugin) Close added in v1.8.1

func (p *Plugin) Close() error

Close cleans up the resources allocated by the govppmux plugin.

func (*Plugin) DumpStats added in v1.8.1

func (p *Plugin) DumpStats(prefixes ...string) ([]*adapter.StatEntry, error)

DumpStats returns all stats with name, type and value

func (*Plugin) GetErrorStats added in v1.8.1

func (p *Plugin) GetErrorStats(names ...string) (*govppapi.ErrorStats, error)

GetErrorStats retrieves VPP error counters

func (*Plugin) GetInterfaceStats added in v1.8.1

func (p *Plugin) GetInterfaceStats() (*govppapi.InterfaceStats, error)

GetInterfaceStats retrieves all counters related to the VPP interfaces

func (*Plugin) GetNodeStats added in v1.8.1

func (p *Plugin) GetNodeStats() (*govppapi.NodeStats, error)

GetNodeStats retrieves a list of Node VPP counters (vectors, clocks, ...)

func (*Plugin) GetSystemStats added in v1.8.1

func (p *Plugin) GetSystemStats() (*govppapi.SystemStats, error)

GetSystemStats retrieves system statistics of the connected VPP instance like Vector rate, Input rate, etc.

func (*Plugin) GetTrace added in v1.8.1

func (p *Plugin) GetTrace() *apitrace.Trace

GetTrace returns all trace entries measured so far

func (*Plugin) Init added in v1.8.1

func (p *Plugin) Init() error

Init is the entry point called by Agent Core. A single binary-API connection to VPP is established.

func (*Plugin) ListStats added in v1.8.1

func (p *Plugin) ListStats(prefixes ...string) ([]string, error)

ListStats returns all stats names

func (*Plugin) NewAPIChannel added in v1.8.1

func (p *Plugin) NewAPIChannel() (govppapi.Channel, error)

NewAPIChannel returns a new API channel for communication with VPP via govpp core. It uses default buffer sizes for the request and reply Go channels.

Example of binary API call from some plugin using GOVPP:

ch, _ := govpp_mux.NewAPIChannel()
ch.SendRequest(req).ReceiveReply

func (*Plugin) NewAPIChannelBuffered added in v1.8.1

func (p *Plugin) NewAPIChannelBuffered(reqChanBufSize, replyChanBufSize int) (govppapi.Channel, error)

NewAPIChannelBuffered returns a new API channel for communication with VPP via govpp core. It allows to specify custom buffer sizes for the request and reply Go channels.

Example of binary API call from some plugin using GOVPP:

ch, _ := govpp_mux.NewAPIChannelBuffered(100, 100)
ch.SendRequest(req).ReceiveReply

type Stats

type Stats struct {
	ChannelsCreated uint64
	ChannelsOpen    uint64
	RequestsSent    uint64
	RequestsFailed  uint64
	AllMessages     metrics.CallStats
	Messages        metrics.Calls
}

func GetStats

func GetStats() *Stats

type StatsAPI added in v1.8.1

type StatsAPI interface {
	API

	// ListStats returns all stats names present on the VPP. Patterns can be used as a prefix
	// to filter the output
	ListStats(patterns ...string) ([]string, error)

	// ListStats returns all stats names, types and values from the VPP. Patterns can be used as a prefix
	// to filter the output. Stats are divided between workers. Example:
	//
	// stats values: {{0, 20, 30}{0, 0, 10}}
	//
	// It means there are three interfaces on two workers (inner arrays, array index == sw_if_index),
	// and statistics are like following:
	//
	// 0 for sw_if_index 0
	// 20 for sw_if_index 1
	// 40 for sw_if_index 2 (sum of stats from all workers)
	//
	DumpStats(patterns ...string) ([]*adapter.StatEntry, error)

	// GetSystemStats retrieves system statistics of the connected VPP instance like Vector rate, Input rate, etc.
	GetSystemStats() (*govppapi.SystemStats, error)

	// GetNodeStats retrieves a list of Node VPP counters (vectors, clocks, ...)
	GetNodeStats() (*govppapi.NodeStats, error)

	// GetInterfaceStats retrieves all counters related to the VPP interfaces
	GetInterfaceStats() (*govppapi.InterfaceStats, error)

	// GetErrorStats retrieves VPP error counters
	GetErrorStats(names ...string) (*govppapi.ErrorStats, error)
}

StatsAPI is extended API with ability to get VPP stats data

type TraceAPI added in v1.8.1

type TraceAPI interface {
	API

	// GetTrace serves to obtain measured binary API calls
	GetTrace() *apitrace.Trace
}

TraceAPI is extended API with ability to get traced VPP binary API calls

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL