services

Documentation

Overview

Package services has service endpoint types. An endpoint is a single port on a single instance of a service/application. The two most important attributes of an endpoint are the host and port. Host can be either an IP address or a DNS name. Endpoints are created by observers.

Most of the core logic for endpoints is on the EndpointCore type, which all endpoints must embed.

There is the notion of a "self-configured" endpoint, which means that it specifies what monitor type to use to monitor it as well as the configuration for that monitor.

Index

• func DoesServiceMatchRule(si Endpoint, ruleText string) bool
• func EndpointAsMap(endpoint Endpoint) map[string]interface{}
• func ValidateDiscoveryRule(rule string) error
• type ConfigEndpointMapping
  • func (cem *ConfigEndpointMapping) ExtraConfig() (map[string]interface{}, error)
• type Container
  • func (c *Container) PrimaryName() string
  • func (c *Container) String() string
• type ContainerEndpoint
  • func (ce *ContainerEndpoint) DerivedFields() map[string]interface{}
  • func (ce *ContainerEndpoint) Dimensions() map[string]string
  • func (ce *ContainerEndpoint) PrivatePort() uint16
  • func (ce *ContainerEndpoint) PublicPort() uint16
• type Endpoint
• type EndpointCore
  • func NewEndpointCore(id string, name string, discoveredBy string, dims map[string]string) *EndpointCore
  • func (e *EndpointCore) AddDimension(k string, v string)
  • func (e *EndpointCore) Core() *EndpointCore
  • func (e *EndpointCore) DerivedFields() map[string]interface{}
  • func (e *EndpointCore) Dimensions() map[string]string
  • func (e *EndpointCore) ExtraConfig() (map[string]interface{}, error)
  • func (e *EndpointCore) IsSelfConfigured() bool
  • func (e *EndpointCore) RemoveDimension(k string)
• type HasDerivedFields
• type ID
• type Orchestration
  • func NewOrchestration(id string, orchType OrchestrationType, portPref PortPreference) *Orchestration
  • func (o *Orchestration) String() string
• type OrchestrationType
• type PortPreference
• type PortType

Functions

func DoesServiceMatchRule

func DoesServiceMatchRule(si Endpoint, ruleText string) bool

DoesServiceMatchRule returns true if service endpoint satisfies the rule given

func EndpointAsMap

func EndpointAsMap(endpoint Endpoint) map[string]interface{}

EndpointAsMap converts an endpoint to a map that contains all of the information about the endpoint. This makes it easy to use endpoints in evaluating rules as well as in collectd templates.

func ValidateDiscoveryRule

func ValidateDiscoveryRule(rule string) error

ValidateDiscoveryRule takes a discovery rule string and returns false if it can be determined to be invalid. It does not guarantee validity but can be used to give upfront feedback to the user if there are syntax errors in the rule.

Types

type ConfigEndpointMapping

type ConfigEndpointMapping struct {
	Endpoint  Endpoint
	ConfigKey string
	Rule      string
}

ConfigEndpointMapping creates a mapping between a config key and a value that is derived from fields on the endpoint. It implements the CustomConfigurable interface.

func (*ConfigEndpointMapping) ExtraConfig

func (cem *ConfigEndpointMapping) ExtraConfig() (map[string]interface{}, error)

ExtraConfig evaluates the rule and returns a map that can be merged into the final monitor config

type Container

type Container struct {
	// The ID of the container exposing the endpoint
	ID string `yaml:"container_id"`
	// A list of container names of the container exposing the endpoint
	Names []string `yaml:"container_names"`
	// The image name of the container exposing the endpoint
	Image string `yaml:"container_image"`
	// The command used when running the container exposing the endpoint
	Command string `yaml:"container_command"`
	// The container state, will usually be "running" since otherwise the
	// container wouldn't have a port exposed to be discovered.
	State string `yaml:"container_state"`
	// A map that contains container label key/value pairs. You can use the
	// `Contains` and `Get` helper functions in discovery rules to make use of
	// this. See [Endpoint Discovery](../auto-discovery.md#additional-functions).
	Labels map[string]string `yaml:"container_labels"`
}

Container information

func (*Container) PrimaryName

func (c *Container) PrimaryName() string

PrimaryName is the first container name, with all slashes stripped from the beginning.

func (*Container) String

func (c *Container) String() string

type ContainerEndpoint

type ContainerEndpoint struct {
	EndpointCore `yaml:",inline"`
	// Used for services that are accessed through some kind of
	// NAT redirection as Docker does.  This could be either the public port
	// or the private one.
	AltPort       uint16        `yaml:"alternate_port"`
	Container     Container     `yaml:",inline"`
	Orchestration Orchestration `yaml:",inline"`
	// A map of labels on the container port. You can use the
	// `Contains` and `Get` helper functions in discovery rules to make use of
	// this. See [Endpoint Discovery](../auto-discovery.md#additional-functions).
	PortLabels map[string]string `yaml:"port_labels"`
}

ContainerEndpoint contains information for single network endpoint of a discovered containerized service. A single real-world service could have multiple distinct instances if it exposes multiple ports or is discovered by more than one observer.

func (*ContainerEndpoint) DerivedFields

func (ce *ContainerEndpoint) DerivedFields() map[string]interface{}

DerivedFields returns aliased and computed variable fields for this endpoint

func (*ContainerEndpoint) Dimensions

func (ce *ContainerEndpoint) Dimensions() map[string]string

Dimensions returns the dimensions associated with this endpoint

func (*ContainerEndpoint) PrivatePort

func (ce *ContainerEndpoint) PrivatePort() uint16

PrivatePort is the port that the service is configured to listen on

func (*ContainerEndpoint) PublicPort

func (ce *ContainerEndpoint) PublicPort() uint16

PublicPort is the port that the endpoint is accessed on externally. It may be different from the PrivatePort.

type Endpoint

type Endpoint interface {
	config.CustomConfigurable

	// Core returns the EndpointCore that all endpoints are required to have
	Core() *EndpointCore

	// Dimensions that are specific to this endpoint (e.g. container name)
	Dimensions() map[string]string
	// AddDimension adds a single dimension to the endpoint
	AddDimension(string, string)
	// RemoveDimension removes a single dimension from the endpoint
	RemoveDimension(string)
}

Endpoint is the generic interface that all types of service instances should implement. All consumers of services should use this interface only.

type EndpointCore

type EndpointCore struct {
	ID ID `yaml:"id"`
	// A observer assigned name of the endpoint
	Name string `yaml:"name"`
	// The hostname/IP address of the endpoint
	Host string `yaml:"host"`
	// TCP or UDP
	PortType PortType `yaml:"port_type"`
	// The TCP/UDP port number of the endpoint
	Port uint16 `yaml:"port"`
	// The observer that discovered this endpoint
	DiscoveredBy  string                 `yaml:"discovered_by"`
	Configuration map[string]interface{} `yaml:"-"`
	// The type of monitor that this endpoint has requested.  This is populated
	// by observers that pull configuration directly from the platform they are
	// observing.
	MonitorType string `yaml:"-"`
	// contains filtered or unexported fields
}

EndpointCore represents an exposed network port

func NewEndpointCore

func NewEndpointCore(id string, name string, discoveredBy string, dims map[string]string) *EndpointCore

NewEndpointCore returns a new initialized endpoint core struct

func (*EndpointCore) AddDimension

func (e *EndpointCore) AddDimension(k string, v string)

AddDimension adds a dimension to this endpoint

func (*EndpointCore) Core

func (e *EndpointCore) Core() *EndpointCore

Core returns the EndpointCore since it will be embedded in an Endpoint instance

func (*EndpointCore) DerivedFields

func (e *EndpointCore) DerivedFields() map[string]interface{}

DerivedFields returns aliased and computed variable fields for this endpoint

func (*EndpointCore) Dimensions

func (e *EndpointCore) Dimensions() map[string]string

Dimensions returns a map of dimensions set on this endpoint

func (*EndpointCore) ExtraConfig

func (e *EndpointCore) ExtraConfig() (map[string]interface{}, error)

ExtraConfig returns a map of values to be considered when configuring a monitor

func (*EndpointCore) IsSelfConfigured

func (e *EndpointCore) IsSelfConfigured() bool

IsSelfConfigured tells whether this endpoint comes with enough configuration to run without being configured further. This ultimately just means whether it specifies what type of monitor to use to monitor it.

func (*EndpointCore) RemoveDimension

func (e *EndpointCore) RemoveDimension(k string)

RemoveDimension removes a dimension from this endpoint

type HasDerivedFields

type HasDerivedFields interface {
	DerivedFields() map[string]interface{}
}

HasDerivedFields is an interface with a single method that can be called to get fields that are derived from a service. This is useful for things like aliased fields or computed fields.

type ID

type ID string

ID uniquely identifies a service instance

type Orchestration

type Orchestration struct {
	ID       string            `yaml:"-"`
	Type     OrchestrationType `yaml:"orchestrator"`
	PortPref PortPreference    `yaml:"-"`
}

Orchestration contains information about the orchestrator that the service is deployed on (see OrchestrationType)

func NewOrchestration

func NewOrchestration(id string, orchType OrchestrationType, portPref PortPreference) *Orchestration

NewOrchestration constructor

func (*Orchestration) String

func (o *Orchestration) String() string

type OrchestrationType

type OrchestrationType int

OrchestrationType represents the type of orchestration the service is deployed under.

const (
	// KUBERNETES orchestrator
	KUBERNETES OrchestrationType = 1 + iota
	// MESOS orchestrator
	MESOS
	// SWARM orchestrator
	SWARM
	// DOCKER orchestrator
	DOCKER
	// NONE orchestrator
	NONE
)

type PortPreference

type PortPreference int

PortPreference describes whether the public or private port should be preferred when connecting to the service

const (
	// PRIVATE means that the internal port (e.g. what the service is
	// configured to listen on directly) should be used when connecting
	PRIVATE PortPreference = 1 + iota
	// PUBLIC means that the port that is exposed through some network mapping
	// should be used (e.g. via Docker's -p flag)
	PUBLIC
)

type PortType

type PortType string

PortType represents the transport protocol used to communicate with this port

const (
	// UDP port type
	UDP PortType = "UDP"
	// TCP port type
	TCP PortType = "TCP"
)