telemetry

Documentation

Overview

Example

Example is an example of a receiver and sender.

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

var group errgroup.Group

receiver, err := telemetry.Listen("127.0.0.1:0")
if err != nil {
	log.Println(err)
	return
}

// receiver
group.Go(func() (err error) {
	defer func() { err = errs.Combine(err, receiver.Close()) }()
	err = receiver.Serve(ctx, telemetry.HandlerFunc(
		func(application, instance string, key []byte, val float64) {
			fmt.Printf("receive %s %s %s %v\n", application, instance, string(key), val)
		},
	))
	if errors.Is(err, context.Canceled) {
		err = nil
	}
	return err
})

// sender
group.Go(func() error {
	client, err := telemetry.NewClient(receiver.Addr(), telemetry.ClientOpts{
		Interval:      time.Second,
		Application:   "example",
		Instance:      telemetry.DefaultInstanceID(),
		Registry:      monkit.Default,
		FloatEncoding: admproto.Float32Encoding,
	})
	if err != nil {
		return err
	}

	client.Run(ctx)
	return nil
})

if err := group.Wait(); err != nil {
	fmt.Println(err)
}

Index

• Constants
• Variables
• func DefaultInstanceID() string
• func ListenAndServe(ctx context.Context, addr string, h Handler) error
• func Send(ctx context.Context, opts Options, ...) (err error)
• type Client
  • func NewClient(remoteAddr string, opts ClientOpts) (rv *Client, err error)
  • func (c *Client) Report(ctx context.Context) (err error)
  • func (c *Client) Run(ctx context.Context)
• type ClientOpts
• type Handler
• type HandlerFunc
  • func (f HandlerFunc) Metric(a, i string, k []byte, v float64)
• type Options
• type Reporter
  • func NewReporter(interval time.Duration, send func(ctx context.Context) error) (rv *Reporter, err error)
  • func (c *Reporter) Publish(ctx context.Context) (err error)
  • func (c *Reporter) Run(ctx context.Context)
• type Server
  • func Listen(addr string) (*Server, error)
  • func (s *Server) Addr() string
  • func (s *Server) Close() error
  • func (s *Server) Serve(ctx context.Context, h Handler) error

Examples

• Package

Constants

const (
	// DefaultInterval is the default amount of time between metric payload sends.
	DefaultInterval = time.Minute

	// DefaultPacketSize sets the target packet size. MTUs are often 1500,
	// though a good argument could be made for 512.
	DefaultPacketSize = 1000

	// DefaultApplication is the default values for application name. Should be used
	// when value in ClientOpts.Application is not set and len(os.Args) == 0.
	DefaultApplication = "unknown"
)

const UnknownInstanceID = "unknown"

UnknownInstanceID is returned when no instance ID can be returned.

Variables

var Error = errs.Class("telemetry")

Error is the default telemetry errs class.

Functions

func DefaultInstanceID

func DefaultInstanceID() string

DefaultInstanceID will return the first non-nil mac address if possible, unknown otherwise.

func ListenAndServe

func ListenAndServe(ctx context.Context, addr string, h Handler) error

ListenAndServe combines Listen and Serve.

func Send

func Send(ctx context.Context, opts Options, forEachValue func(func(key string, value float64))) (err error)

Send sends out telemetry via UDP as key/value pairs. forEachValue will be called with a callback to get all the key/values to send out.

Types

type Client

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

Client is a telemetry client for sending UDP packets at a regular interval from a monkit.Registry.

func NewClient

func NewClient(remoteAddr string, opts ClientOpts) (rv *Client, err error)

NewClient constructs a telemetry client that sends packets to remoteAddr over UDP.

func (*Client) Report

func (c *Client) Report(ctx context.Context) (err error)

Report bundles up all the current stats and writes them out as UDP packets.

func (*Client) Run

func (c *Client) Run(ctx context.Context)

Run calls Report roughly every Interval.

type ClientOpts

type ClientOpts struct {
	// Interval is how frequently stats from the provided Registry will be
	// sent up. Note that this interval is "jittered", so the actual interval
	// is taken from a normal distribution with a mean of Interval and a
	// variance of Interval/4. Defaults to DefaultInterval.
	Interval time.Duration

	// Application is the application name, usually prepended to metric names.
	// By default it will be os.Args[0].
	Application string

	// Instance is a string that identifies this particular server. Could be a
	// node id, but defaults to the result of DefaultInstanceId().
	Instance string

	// PacketSize controls how we fragment the data as it goes out in UDP
	// packets. Defaults to DefaultPacketSize.
	PacketSize int

	// Registry is where to get stats from. Defaults to monkit.Default.
	Registry *monkit.Registry

	// FloatEncoding is how floats should be encoded on the wire.
	// Default is float16.
	FloatEncoding admproto.FloatEncoding

	// Headers allow you to set arbitrary key/value tags to be included in
	// each packet send.
	Headers map[string]string
}

ClientOpts allows you to set Client Options.

type Handler

type Handler interface {
	Metric(application, instance string, key []byte, val float64)
}

Handler is called every time a new metric comes in.

type HandlerFunc

type HandlerFunc func(application, instance string, key []byte, val float64)

HandlerFunc turns a func into a Handler.

func (HandlerFunc) Metric

func (f HandlerFunc) Metric(a, i string, k []byte, v float64)

Metric implements the Handler interface.

type Options

type Options struct {
	// Application to send with
	Application string

	// Instance Id to send with
	InstanceID []byte

	// Address to send packets to
	Address string

	// PacketSize controls maximum packet size. If zero, 1024 is used.
	PacketSize int

	// ProtoOps allows you to set protocol options.
	ProtoOpts admproto.Options

	// Headers allow you to set arbitrary key/value pairs to be included in each packet send
	Headers map[string]string
}

Options define all the required parameters to send out UDP telemetry packages.

type Reporter

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

Reporter calls a function to report metrics periodically.

func NewReporter

func NewReporter(interval time.Duration, send func(ctx context.Context) error) (rv *Reporter, err error)

NewReporter creates a reporter which calls send function once in each interval.

func (*Reporter) Publish

func (c *Reporter) Publish(ctx context.Context) (err error)

Publish bundles up all the current stats and writes them out as UDP packets.

func (*Reporter) Run

func (c *Reporter) Run(ctx context.Context)

Run calls Report roughly every Interval.

type Server

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

Server listens for incoming metrics.

func Listen

func Listen(addr string) (*Server, error)

Listen will start listening on addr for metrics.

func (*Server) Addr

func (s *Server) Addr() string

Addr returns the address the server is serving on.

func (*Server) Close

func (s *Server) Close() error

Close will stop listening.

func (*Server) Serve

func (s *Server) Serve(ctx context.Context, h Handler) error

Serve will wait for metrics and call Handler h as they come in.