tsclient

Documentation

Overview

Package tsclient provides a common client for sending metrics to the DO timeseries system.

The timeseries system is a push-based system where metrics are submitted in batches via the SendMetrics method at fixed time intervals. Metrics are submitted to the wharf server.

Wharf responds with a rate-limit value which the client must wait that many seconds or longer before submitting the next batch of metrics -- this is exposed via the WaitDuration() method.

Index

• Variables
• func ConvertLFMMapToPrometheusEncodedName(lfm map[string]string) string
• func GetLFM(def *Definition, labels []string) (string, error)
• func ParseMetricDelimited(s string) (map[string]string, error)
• type Client
  • func New(opts ...ClientOptFn) Client
• type ClientOptFn
  • func WithDefaultLimits(maxBatchSize, maxMetricLength int) ClientOptFn
  • func WithMetadataEndpoint(endpoint string) ClientOptFn
  • func WithRadarEndpoint(endpoint string) ClientOptFn
  • func WithTimeout(timeout time.Duration) ClientOptFn
  • func WithTrustedAppKey(appName, appKey string) ClientOptFn
  • func WithUserAgent(s string) ClientOptFn
  • func WithWharfEndpoint(endpoint string) ClientOptFn
  • func WithWharfEndpointSSLHostname(hostname string) ClientOptFn
  • func WithWharfEndpoints(endpoints []string) ClientOptFn
• type ClientOptions
• type Definition
  • func NewDefinition(name string, opts ...DefinitionOpt) *Definition
  • func NewDefinitionFromMap(m map[string]string) *Definition
• type DefinitionOpt
  • func WithCommonLabels(labels map[string]string) DefinitionOpt
  • func WithMeasuredLabels(labelKeys ...string) DefinitionOpt
• type DefinitionOpts
• type HTTPClient
  • func (c *HTTPClient) AddMetric(def *Definition, value float64, labels ...string) error
  • func (c *HTTPClient) AddMetricWithTime(def *Definition, t time.Time, value float64, labels ...string) error
  • func (c *HTTPClient) Flush() error
  • func (c *HTTPClient) GetAppKey(authToken string) (string, error)
  • func (c *HTTPClient) GetAuthToken() (string, error)
  • func (c *HTTPClient) GetDropletID() (string, error)
  • func (c *HTTPClient) GetRegion() (string, error)
  • func (c *HTTPClient) GetWaitInterval() time.Duration
  • func (c *HTTPClient) MaxBatchSize() int
  • func (c *HTTPClient) MaxMetricLength() int
  • func (c *HTTPClient) ResetWaitTimer()
  • func (c *HTTPClient) WaitDuration() time.Duration
• type UnexpectedHTTPStatusError
  • func (e *UnexpectedHTTPStatusError) Error() string

Variables

var ErrCircuitBreaker = fmt.Errorf("circuit breaker is open; deliberately failing due to exponential backoff")

ErrCircuitBreaker happens when there are many back to back failures sending metrics, the client will deliberately fail in order to reduce network load on the server

var ErrFlushTooFrequent = fmt.Errorf("metrics sent faster than server requested")

ErrFlushTooFrequent happens if the client attempts to flush metrics faster than what the server requested

var ErrLabelMissmatch = fmt.Errorf("unexpected number of labels")

ErrLabelMissmatch happens if the number of supplied labels is incorrect

var ErrSendTooFrequent = fmt.Errorf("metrics sent faster than server requested")

ErrSendTooFrequent happens if the client attempts to send metrics faster than what the server requested

var ErrWriteFailure = fmt.Errorf("failed to write")

ErrWriteFailure happens when the writer fails to write to the remote

Functions

func ConvertLFMMapToPrometheusEncodedName

func ConvertLFMMapToPrometheusEncodedName(lfm map[string]string) string

ConvertLFMMapToPrometheusEncodedName converts a metric in the form map[string]string{"__name__":"sonar_cpu","__source__":"user", "cpu":"cpu0"} to sonar_cpu{__source__="user",cpu="cpu0",host_id="899669",mode="iowait",user_id="208897"}

func GetLFM

func GetLFM(def *Definition, labels []string) (string, error)

GetLFM returns an lfm corresponding to a definition

func ParseMetricDelimited

func ParseMetricDelimited(s string) (map[string]string, error)

ParseMetricDelimited parses a delimited message

Types

type Client

type Client interface {
	AddMetric(def *Definition, value float64, labels ...string) error
	AddMetricWithTime(def *Definition, t time.Time, value float64, labels ...string) error
	Flush() error
	WaitDuration() time.Duration
	MaxBatchSize() int
	MaxMetricLength() int
	ResetWaitTimer()
}

Client is an interface for sending batches of metrics

func New

func New(opts ...ClientOptFn) Client

New creates a new client

type ClientOptFn

type ClientOptFn func(*ClientOptions)

ClientOptFn allows for overriding options

func WithDefaultLimits

func WithDefaultLimits(maxBatchSize, maxMetricLength int) ClientOptFn

WithDefaultLimits set default metric limits. These will always be overridden by the server after first write

func WithMetadataEndpoint

func WithMetadataEndpoint(endpoint string) ClientOptFn

WithMetadataEndpoint overrides the default metadata endpoint, this option is only applicable to non-trusted clients (i.e. running on a customer droplet).

func WithRadarEndpoint

func WithRadarEndpoint(endpoint string) ClientOptFn

WithRadarEndpoint overrides the default radar endpoint, this option is only applicable to non-trusted clients (i.e. running on a customer droplet).

func WithTimeout

func WithTimeout(timeout time.Duration) ClientOptFn

WithTimeout overrides the default wharf endpoint

func WithTrustedAppKey

func WithTrustedAppKey(appName, appKey string) ClientOptFn

WithTrustedAppKey disables metadata authentication; trusted apps can override the host_id and user_id tags.

func WithUserAgent

func WithUserAgent(s string) ClientOptFn

WithUserAgent overrides the http user agent

func WithWharfEndpoint

func WithWharfEndpoint(endpoint string) ClientOptFn

WithWharfEndpoint overrides the default wharf endpoint, this option must be set when WithTrustedAppKey is used.

func WithWharfEndpointSSLHostname

func WithWharfEndpointSSLHostname(hostname string) ClientOptFn

WithWharfEndpointSSLHostname overrides the default wharf endpoint, this option must be set when WithTrustedAppKey is used.

func WithWharfEndpoints

func WithWharfEndpoints(endpoints []string) ClientOptFn

WithWharfEndpoints overrides the default wharf endpoint, this option must be set when WithTrustedAppKey is used.

type ClientOptions

type ClientOptions struct {
	UserAgent                string
	WharfEndpoints           []string
	WharfEndpointSSLHostname string
	AppName                  string
	AppKey                   string
	MetadataEndpoint         string
	RadarEndpoint            string
	Timeout                  time.Duration
	IsTrusted                bool
	MaxBatchSize             int
	MaxMetricLength          int
}

ClientOptions are client options

type Definition

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

Definition holds the description of a metric.

func NewDefinition

func NewDefinition(name string, opts ...DefinitionOpt) *Definition

NewDefinition returns a new definition

func NewDefinitionFromMap

func NewDefinitionFromMap(m map[string]string) *Definition

NewDefinitionFromMap returns a new definition with common labels for each given value, a "__name__" key must also be present

type DefinitionOpt

type DefinitionOpt func(*DefinitionOpts)

DefinitionOpt is an option initializer for metric registration.

func WithCommonLabels

func WithCommonLabels(labels map[string]string) DefinitionOpt

WithCommonLabels includes common labels

func WithMeasuredLabels

func WithMeasuredLabels(labelKeys ...string) DefinitionOpt

WithMeasuredLabels includes labels

type DefinitionOpts

type DefinitionOpts struct {
	// CommonLabels is a set of static key-value labels
	CommonLabels map[string]string

	// MeasuredLabelKeys is a list of label keys whose values will be specified
	// at run-time
	MeasuredLabelKeys []string
}

DefinitionOpts can be changed with opt setters

type HTTPClient

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

HTTPClient is used to send metrics via http

func (*HTTPClient) AddMetric

func (c *HTTPClient) AddMetric(def *Definition, value float64, labels ...string) error

AddMetric adds a metric to the batch

func (*HTTPClient) AddMetricWithTime

func (c *HTTPClient) AddMetricWithTime(def *Definition, t time.Time, value float64, labels ...string) error

AddMetricWithTime adds a metric to the batch

func (*HTTPClient) Flush

func (c *HTTPClient) Flush() error

Flush sends the batch of metrics to wharf

func (*HTTPClient) GetAppKey

func (c *HTTPClient) GetAppKey(authToken string) (string, error)

GetAppKey returns the appkey

func (*HTTPClient) GetAuthToken

func (c *HTTPClient) GetAuthToken() (string, error)

GetAuthToken returns an auth token

func (*HTTPClient) GetDropletID

func (c *HTTPClient) GetDropletID() (string, error)

GetDropletID returns the droplet ID

func (*HTTPClient) GetRegion

func (c *HTTPClient) GetRegion() (string, error)

GetRegion returns the region

func (*HTTPClient) GetWaitInterval

func (c *HTTPClient) GetWaitInterval() time.Duration

GetWaitInterval returns the wait interval between metrics

func (*HTTPClient) MaxBatchSize

func (c *HTTPClient) MaxBatchSize() int

MaxBatchSize returns the maximum amount of metrics that may be sent per batch

func (*HTTPClient) MaxMetricLength

func (c *HTTPClient) MaxMetricLength() int

MaxMetricLength is the maximum length of a metric that may be sent (all labels and values combined)

func (*HTTPClient) ResetWaitTimer

func (c *HTTPClient) ResetWaitTimer()

ResetWaitTimer causes the wait duration timer to reset

func (*HTTPClient) WaitDuration

func (c *HTTPClient) WaitDuration() time.Duration

WaitDuration returns the duration before the next batch of metrics will be accepted

type UnexpectedHTTPStatusError

type UnexpectedHTTPStatusError struct {
	StatusCode int
}

UnexpectedHTTPStatusError is returned when an unexpected HTTP status is returned when making a registry api call.

func (*UnexpectedHTTPStatusError) Error

func (e *UnexpectedHTTPStatusError) Error() string

Error returns the error string