api

package
v1.20.0 Latest Latest
Warning

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

 Go to latest Published: Dec 13, 2024 License: Apache-2.0 Imports: 14 Imported by: 0

README

Geneos Inbound API

The api package abstracts the inbound API available through the XML-RPC and REST based Netprobe APIs. Both APIs offer different levels of functionality and not all features are available in both.

You can use the package to directly connect and send data to a Netprobe or you can build and use a plugin that imitates Geneos plugins in targetted features but these work at the level of Dataviews on one sampler and, because of the API requirements, cannot create Samplers directly.

This README will give examples of using the package in both forms.

Documentation

Index

Constants

View Source 
const (
	MISC_ERROR              = 100
	NUMBER_OUT_OF_RANGE     = 101
	HOST_NOT_TRUSTED        = 102
	NO_SUCH_METHOD          = 200
	WRONG_PARAM_COUNT       = 201
	NO_SUCH_SAMPLER         = 202
	GATEWAY_NOT_CONNECTED   = 203
	GATEWAY_NOT_SUPPORTED   = 204
	SAMPLER_PARAM_NOT_FOUND = 300
	VIEW_EXISTS             = 301
	NO_SUCH_VIEW            = 302
	NO_SUCH_STREAM          = 303
	VIEW_AND_GROUP_EQUAL    = 304
	SAMPLER_INACTIVE        = 305
	NO_SUCH_CELL            = 400
	ROW_EXISTS              = 401
	COLUMN_EXISTS           = 402
	NO_SUCH_HEADLINE        = 403
	HEADLINE_EXISTS         = 404
	NO_SUCH_ROW             = 405
	NO_SUCH_COLUMN          = 406
	COLUMN_MISMATCH         = 407
	NO_XML_SENT             = 500
	STREAM_BUFFER_FULL      = 600
)

Error codes

Variables

View Source 
var (
	ErrInvalidArgs = errors.New("invalid arguments")
)

Functions

func RegisterPlugin 

func RegisterPlugin(name string, plugin Sampler)

Types

type APIClient 

type APIClient interface {
	Healthy() bool

	CreateDataview(entity, sampler, name string) error
	UpdateDataview(entity, sampler, name string, values [][]string) error
	DeleteDataview(entity, sampler, name string) error

	CreateRow(entity, sampler, view, name string) error
	UpdateRow(entity, sampler, view, name string, values []string) error
	DeleteRow(entity, sampler, view, name string) error

	CreateColumn(entity, sampler, view, name string) error

	CreateHeadline(entity, sampler, view, name string) error
	UpdateHeadline(entity, sampler, view, name, value string) error
	DeleteHeadline(entity, sampler, view, name string) error

	CreateStream(entity, sampler, name string) error
	UpdateStream(entity, sampler, name string, message any) error

	ManagedEntityExists(entity string) (bool, error)
	SamplerExists(entity, sampler string) (bool, error)
	DataviewExists(entity, sampler, name string) (bool, error)
	ColumnExists(entity, sampler, view, name string) (bool, error)
	RowExists(entity, sampler, view, name string) (bool, error)
	HeadlineExists(entity, sampler, view, name string) (bool, error)
}

APIClient is the method set required for any API sending data into a Geneos Netprobe

func NewRESTClient 

func NewRESTClient(endpoint string, options ...rest.Options) (c APIClient, err error)

func NewXMLRPCClient 

func NewXMLRPCClient(endpoint string, options ...Options) (c APIClient, err error)

NewXMLRPCClient returns a new client that uses endpoint and with the features set by options. The endpoint would normally end in `/xmlrpc`

type Columns 

type Columns map[string]columndetails

Columns is a common type for the map of rows for output.

func ColumnInfo 

func ColumnInfo(rowdata interface{}) (cols Columns, columnnames []string, sorting string, err error)

ColumnInfo is a helper function that takes a (flat) struct as input and returns an ordered slice of column names ready to update a dataview. Normally called once per sampler during initialisation.

The column names are the display names in the struct tags or the field name otherwise. The internal method parsetags() is where the valid options are defined in detail. More docs to follow.

The input is a type or an zero-ed struct as this method only checks the struct tags and doesn't care about the data

type Dataview 

type Dataview struct {
	APIClient

	Entity  string
	Sampler string
	Name    string
	// contains filtered or unexported fields
}

func NewDataview 

func NewDataview(c APIClient, entity, sampler, typeName, groupHeading, viewName string) (view *Dataview, err error)

NewDataview returns a Dataview view. If the connection to the API fails then a nil pointer is returned. If the dataview does not exist in the Netprobe it is also created.

func (*Dataview) Exists 

func (view *Dataview) Exists() (exists bool, err error)

func (*Dataview) RowsFromMap 

func (view *Dataview) RowsFromMap(rowdata interface{}) (rows [][]string, err error)

The data passed should NOT include column heading slice as it will be regenerated from the Columns data

func (Dataview) RowsFromMapDelta 

func (view Dataview) RowsFromMapDelta(newrowdata, oldrowdata interface{},
	interval time.Duration) (rows [][]string, err error)

RowsFromMapDelta takes two sets of data and calculates the difference between them. Only numeric data is changed, any non-numeric fields are left unchanged and taken from newrowdata only. If an interval is supplied (non-zero) then that is used as a scaling value otherwise the straight numeric difference is calculated

This is for data like sets of counters that are absolute values over time

func (*Dataview) RowsFromSlice 

func (view *Dataview) RowsFromSlice(rowdata interface{}) (rows [][]string, err error)

RowsFromSlice - results are not resorted, they are assumed to be in the order required

func (*Dataview) Update 

func (view *Dataview) Update() (err error)

func (*Dataview) UpdateTableFromMap 

func (view *Dataview) UpdateTableFromMap(data interface{}) error

Sorting the data is only to define the "natural sort order" of the data as it appears in a Geneos Dataview without further client-side sorting.

func (*Dataview) UpdateTableFromMapDelta 

func (view *Dataview) UpdateTableFromMapDelta(newdata, olddata interface{}, interval time.Duration) error

UpdateTableFromMapDelta calculates the difference between the previous values and current, scaled by the interval

func (*Dataview) UpdateTableFromSlice 

func (view *Dataview) UpdateTableFromSlice(rowdata interface{}) error

UpdateTableFromSlice - Given an ordered slice of structs of data the method renders a simple table of data as defined in the Columns part of Samplers

type Options 

type Options func(*apiOptions)

func InsecureSkipVerify 

func InsecureSkipVerify() Options

InsecureSkipVerify

type Plugin 

type Plugin struct {
	APIClient
	Sampler

	Interval time.Duration
	// contains filtered or unexported fields
}

Plugin is an instance of a plugin

func NewSampler added in v1.8.1 

func NewSampler(c APIClient, name, entity, sampler string) (s *Plugin)

type RESTClient 

type RESTClient struct {
	*rest.Client
}

func (*RESTClient) ColumnExists added in v1.8.1 

func (c *RESTClient) ColumnExists(entity, sampler, view, name string) (bool, error)

func (*RESTClient) CreateColumn added in v1.8.1 

func (c *RESTClient) CreateColumn(entity, sampler, view, name string) (err error)

func (*RESTClient) CreateDataview 

func (c *RESTClient) CreateDataview(entity, sampler, name string) (err error)

func (*RESTClient) CreateHeadline added in v1.8.1 

func (c *RESTClient) CreateHeadline(entity, sampler, view, name string) (err error)

func (*RESTClient) CreateRow 

func (c *RESTClient) CreateRow(entity, sampler, view, name string) (err error)

func (*RESTClient) CreateStream 

func (c *RESTClient) CreateStream(entity, sampler, name string) (err error)

func (*RESTClient) DataviewExists 

func (c *RESTClient) DataviewExists(entity, sampler, name string) (bool, error)

func (*RESTClient) DeleteDataview 

func (c *RESTClient) DeleteDataview(entity, sampler, name string) (err error)

func (*RESTClient) DeleteHeadline added in v1.8.1 

func (c *RESTClient) DeleteHeadline(entity, sampler, view, name string) (err error)

func (*RESTClient) DeleteRow 

func (c *RESTClient) DeleteRow(entity, sampler, view, name string) (err error)

func (*RESTClient) HeadlineExists added in v1.8.1 

func (c *RESTClient) HeadlineExists(entity, sampler, view, name string) (bool, error)

func (*RESTClient) Healthy 

func (c *RESTClient) Healthy() bool

func (*RESTClient) ManagedEntityExists added in v1.8.1 

func (c *RESTClient) ManagedEntityExists(entity string) (bool, error)

func (*RESTClient) RowExists added in v1.8.1 

func (c *RESTClient) RowExists(entity, sampler, view, name string) (bool, error)

func (*RESTClient) SamplerExists added in v1.8.1 

func (c *RESTClient) SamplerExists(entity, sampler string) (bool, error)

func (*RESTClient) UpdateDataview 

func (c *RESTClient) UpdateDataview(entity, sampler, name string, values [][]string) (err error)

func (*RESTClient) UpdateHeadline added in v1.8.1 

func (c *RESTClient) UpdateHeadline(entity, sampler, view, name, value string) (err error)

func (*RESTClient) UpdateRow 

func (c *RESTClient) UpdateRow(entity, sampler, view, name string, values []string) (err error)

func (*RESTClient) UpdateStream 

func (c *RESTClient) UpdateStream(entity, sampler, name string, message any) (err error)

type Sampler added in v1.8.1 

type Sampler interface {
	// actions
	Open() error
	Start() error
	Pause() error
	Close() error
	SampleNow() error

	// info
	Interval() time.Duration
	SetInterval(time.Duration)
}

Sampler is the method set for a Plugin instance

func FindPlugin 

func FindPlugin(name string) (plugin Sampler)

type Stream added in v1.8.1 

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

func OpenStream added in v1.8.1 

func OpenStream(c APIClient, entity, sampler, stream string) (s *Stream, err error)

func (*Stream) Write added in v1.8.1 

func (s *Stream) Write(data []byte) (n int, err error)

type XMLRPCClient 

type XMLRPCClient struct {
	*xmlrpc.Client
}

XMLRPCClient is a client for the XML-RPC API. It can be used to connect to multiple entities and samplers on the same Netprobe and so does not hold details at that level.

func (*XMLRPCClient) AddHeadline 

func (c *XMLRPCClient) AddHeadline(entity, sampler, view, headline string) error

AddHeadline adds a headline variable to the view.

func (*XMLRPCClient) AddMessage 

func (c *XMLRPCClient) AddMessage(entity, sampler, stream, message string) error

AddMessage adds a new message to the end of the stream.

func (*XMLRPCClient) AddTableColumn 

func (c *XMLRPCClient) AddTableColumn(entity, sampler, view, column string) error

AddTableColumn adds another column to the table. Each column must be unique.

func (*XMLRPCClient) AddTableRow 

func (c *XMLRPCClient) AddTableRow(entity, sampler, view, row string) error

AddTableRow adds a new, blank table row to the specified view. The name of each row must be unique to that table. An attempt to create two rows with the same name will result in an error.

func (*XMLRPCClient) ColumnExists 

func (c *XMLRPCClient) ColumnExists(entity, sampler, view, column string) (exists bool, err error)

ColumnExists check if the column exists.

func (*XMLRPCClient) CreateColumn added in v1.8.1 

func (c *XMLRPCClient) CreateColumn(entity, sampler, view, name string) (err error)

func (*XMLRPCClient) CreateDataview 

func (c *XMLRPCClient) CreateDataview(entity, sampler, name string) error

func (*XMLRPCClient) CreateHeadline added in v1.8.1 

func (c *XMLRPCClient) CreateHeadline(entity, sampler, view, name string) (err error)

func (*XMLRPCClient) CreateRow 

func (c *XMLRPCClient) CreateRow(entity, sampler, view, name string) (err error)

func (*XMLRPCClient) CreateStream 

func (c *XMLRPCClient) CreateStream(entity, sampler, name string) (err error)

func (*XMLRPCClient) CreateView 

func (c *XMLRPCClient) CreateView(entity, sampler, viewName, groupHeading string) (err error)

CreateView creates a new, empty view in the specified sampler under the specified groupHeading. This view will appear in Active Console once it has been created, even if no information has been added to it. For historic reasons, the groupHeading must not be the same as the viewName.

func (*XMLRPCClient) DataviewExists 

func (c *XMLRPCClient) DataviewExists(entity, sampler, name string) (bool, error)

func (*XMLRPCClient) DeleteDataview 

func (c *XMLRPCClient) DeleteDataview(entity, sampler, name string) error

func (*XMLRPCClient) DeleteHeadline added in v1.8.1 

func (c *XMLRPCClient) DeleteHeadline(entity, sampler, view, name string) (err error)

func (*XMLRPCClient) DeleteRow 

func (c *XMLRPCClient) DeleteRow(entity, sampler, view, name string) (err error)

func (*XMLRPCClient) GatewayConnected 

func (c *XMLRPCClient) GatewayConnected() (connected bool, err error)

GatewayConnected checks whether the Gateway is connected to this NetProbe.

func (*XMLRPCClient) GetColumnCount 

func (c *XMLRPCClient) GetColumnCount(entity, sampler, view string) (count int, err error)

GetColumnCount returns the column count of the view.

func (*XMLRPCClient) GetColumnNames 

func (c *XMLRPCClient) GetColumnNames(entity, sampler, view string) (names []string, err error)

GetColumnNames returns the names of existing columns

func (*XMLRPCClient) GetHeadlineCount 

func (c *XMLRPCClient) GetHeadlineCount(entity, sampler, view string) (count int, err error)

GetHeadlineCount returns the headline count of the view.

func (*XMLRPCClient) GetHeadlineNames 

func (c *XMLRPCClient) GetHeadlineNames(entity, sampler, view string) (names []string, err error)

GetHeadlineNames returns the names of existing headlines

func (*XMLRPCClient) GetParameter 

func (c *XMLRPCClient) GetParameter(entity, sampler, parameter string) (param string, err error)

GetParameter retrieves the value of a sampler parameter that has been defined in the gateway configuration.

func (*XMLRPCClient) GetRowCount 

func (c *XMLRPCClient) GetRowCount(entity, sampler, view string) (count int, err error)

GetRowCount returns the row count of the view.

func (*XMLRPCClient) GetRowNames 

func (c *XMLRPCClient) GetRowNames(entity, sampler, view string) (names []string, err error)

GetRowNames returns the names of existing rows

func (*XMLRPCClient) GetRowNamesOlderThan 

func (c *XMLRPCClient) GetRowNamesOlderThan(entity, sampler, view string, unixtime int64) (names []string, err error)

GetRowNamesOlderThan returns the names of rows whose update time is older than the time provided. The timestamp, unixtime, should be provided as an int64 number of seconds elapsed since UNIX epoch, and not a time.Time - this is sent as a string to the API.

func (*XMLRPCClient) HeadlineExists 

func (c *XMLRPCClient) HeadlineExists(entity, sampler, view, headline string) (exists bool, err error)

HeadlineExists checks if the headline exists

func (*XMLRPCClient) Healthy 

func (c *XMLRPCClient) Healthy() bool

func (*XMLRPCClient) Heartbeat 

func (c *XMLRPCClient) Heartbeat(entity string, sampler string) (err error)

Heartbeat prevents the sampling status from becoming failed when no updates are needed to a sampler and the client is signed on. If this method is called when SignOn has not been called then it has no effect.

func (*XMLRPCClient) HeartbeatStream 

func (c *XMLRPCClient) HeartbeatStream(entity, sampler, stream string) (err error)

HeartbeatStream prevents the status from becoming failed when no updates are needed to a view and the client is signed on. If this method is called when SignOnStream has not been called then it has no effect.

func (*XMLRPCClient) ManagedEntityExists 

func (c *XMLRPCClient) ManagedEntityExists(entity string) (exists bool, err error)

ManagedEntityExists checks whether a particular Managed Entity exists on this NetProbe containing any API or API-Streams samplers.

func (*XMLRPCClient) RemoveHeadline 

func (c *XMLRPCClient) RemoveHeadline(entity, sampler, view, headline string) error

RemoveHeadline removes a headline from the view.

func (*XMLRPCClient) RemoveTableRow 

func (c *XMLRPCClient) RemoveTableRow(entity, sampler, view, row string) error

RemoveTableRow removes an existing row from the specified view.

func (*XMLRPCClient) RemoveView 

func (c *XMLRPCClient) RemoveView(entity, sampler, viewName, groupHeading string) error

RemoveView a view that has been created with CreateView

func (*XMLRPCClient) RowExists 

func (c *XMLRPCClient) RowExists(entity, sampler, view, row string) (exists bool, err error)

RowExists checks if the row exists

func (*XMLRPCClient) SamplerExists 

func (c *XMLRPCClient) SamplerExists(entity, sampler string) (exists bool, err error)

SamplerExists checks whether a particular API or API-Streams sampler exists on this NetProbe.

Note, it is unclear if there is an entity involved here, for now it joins the entity and sampler in the argument with a "."

func (*XMLRPCClient) SignOff 

func (c *XMLRPCClient) SignOff(entity string, sampler string) (err error)

SignOff cancels the commitment to provide updates to a sampler. If this method is called when SignOn has not been called then it has no effect.

func (*XMLRPCClient) SignOffStream 

func (c *XMLRPCClient) SignOffStream(entity, sampler, stream string) (err error)

SignOffStream cancels the commitment to provide updates to a stream. If this method is called when SignOnStream has not been called then it has no effect.

func (*XMLRPCClient) SignOn 

func (c *XMLRPCClient) SignOn(entity, sampler string, seconds int) (err error)

SignOn commits the API client to provide at least one heartbeat or update to the sampler within the time period specified. seconds should be at least 1 and no more than 86400 (24 hours). SignOn may be called again to change the time period without the need to sign off first.

func (*XMLRPCClient) SignOnStream 

func (c *XMLRPCClient) SignOnStream(entity, sampler, stream string, seconds int) (err error)

SignOnStream commits the API-STREAM client to provide at least one heartbeat or update to the stream within the time period specified. seconds should be at least 1 and no more than 86400 (24 hours). SignOnStream may be called again to change the time period without the need to sign off first.

func (*XMLRPCClient) UpdateDataview 

func (c *XMLRPCClient) UpdateDataview(entity, sampler, name string, values [][]string) error

func (*XMLRPCClient) UpdateEntireTable 

func (c *XMLRPCClient) UpdateEntireTable(entity, sampler, view string, values [][]string) error

UpdateEntireTable updates the entire table for a given view. This is useful if the entire table will change at once or the table is being created for the first time. The array passed should be two dimensional. The first row should be the column headings and the first column of each subsequent row should be the name of the row. The array should be at least 2 columns by 2 rows. Once table columns have been defined, they cannot be changed by this method.

func (*XMLRPCClient) UpdateHeadline 

func (c *XMLRPCClient) UpdateHeadline(entity, sampler, view, headline, value string) error

UpdateHeadline updates a headline variable. This performs the same action as updateVariable, but is fractionally faster as it is not necessary to determine the variable type.

func (*XMLRPCClient) UpdateRow 

func (c *XMLRPCClient) UpdateRow(entity, sampler, view, name string, values []string) (err error)

func (*XMLRPCClient) UpdateStream 

func (c *XMLRPCClient) UpdateStream(entity, sampler, name string, message any) (err error)

func (*XMLRPCClient) UpdateTableCell 

func (c *XMLRPCClient) UpdateTableCell(entity, sampler, view, cell, value string) error

UpdateTableCell updates a single cell in a table. The standard row.column format should be used to reference a cell. This performs the same action as updateVariable, but is fractionally faster as it is not necessary to determine the variable type.

func (*XMLRPCClient) UpdateTableRow 

func (c *XMLRPCClient) UpdateTableRow(entity, sampler, view, row string, values []string) error

UpdateTableRow updates an existing row from the specified view with the new values provided.

func (*XMLRPCClient) UpdateVariable 

func (c *XMLRPCClient) UpdateVariable(entity, sampler, view, variable, value string) error

UpdateVariable can be used to update either a headline variable or a table cell. If the variable name contains a period (.) then a cell is assumed, otherwise a headline variable is assumed.

func (*XMLRPCClient) ViewExists 

func (c *XMLRPCClient) ViewExists(entity, sampler, viewName string) (exists bool, err error)

ViewExists checks whether a particular view exists in this sampler. viewName should be in the form group-view. This method is useful if no updates are needed in a long period of time, to check whether the NetProbe has restarted. If this were the case then the sampler would exist, but the view would not.

Source Files

View all Source files

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.