telemetry

Documentation

Overview

Package telemetry implements the client for server-side telemetry of the network. Functions in this package are synchronous and blocking unless otherwise specified. For convenience, most functions here do not return errors, but errors are logged to the standard logger.

To use this package, first call Init(). You can then call any of the collection/aggregation functions. Call StartEmitting() when you are ready to begin sending telemetry updates.

When collecting metrics (functions like Set, AppendUnique, or Increment), it may be desirable and even recommended to invoke them in a new goroutine in case there is lock contention; they are thread-safe (unless noted), and you may not want them to block the main thread of execution. However, sometimes blocking may be necessary too; for example, adding startup metrics to the buffer before the call to StartEmitting().

This package is designed to be as fast and space-efficient as reasonably possible, so that it does not disrupt the flow of execution.

Index

• func Add(key string, amount int)
• func Append(key string, value interface{})
• func AppendUnique(key string, value interface{})
• func FastHash(input []byte) string
• func Increment(key string)
• func Init(instanceID uuid.UUID, disabledMetricsKeys []string)
• func Reset()
• func Set(key string, val interface{})
• func SetNested(key, subkey string, val interface{})
• func StartEmitting()
• func StopEmitting()
• type Payload
  • func (p Payload) Int(key string) int
• type Response

Functions

func Add

func Add(key string, amount int)

Add adds amount to a value named key. If it does not exist, it is created with a value of 1. If key maps to a type that is not an integer, a panic is logged, and this is a no-op.

func Append

func Append(key string, value interface{})

Append appends value to a list named key. If key is new, a new list will be created. If key maps to a type that is not a list, a panic is logged, and this is a no-op.

func AppendUnique

func AppendUnique(key string, value interface{})

AppendUnique adds value to a set named key. Set items are unordered. Values in the set are unique, but how many times they are appended is counted. The value must be hashable.

If key is new, a new set will be created for values with that key. If key maps to a type that is not a counting set, a panic is logged, and this is a no-op.

func FastHash

func FastHash(input []byte) string

FastHash hashes input using a 32-bit hashing algorithm that is fast, and returns the hash as a hex-encoded string. Do not use this for cryptographic purposes.

func Increment

func Increment(key string)

Increment is a shortcut for Add(key, 1)

func Init

func Init(instanceID uuid.UUID, disabledMetricsKeys []string)

Init initializes this package so that it may be used. Do not call this function more than once. Init panics if it is called more than once or if the UUID value is empty. Once this function is called, the rest of the package may safely be used. If this function is not called, the collector functions may still be invoked, but they will be no-ops.

Any metrics keys that are passed in the second argument will be permanently disabled for the lifetime of the process.

func Reset

func Reset()

Reset empties the current payload buffer.

func Set

func Set(key string, val interface{})

Set puts a value in the buffer to be included in the next emission. It overwrites any previous value.

This function is safe for multiple goroutines, and it is recommended to call this using the go keyword after the call to SendHello so it doesn't block crucial code.

func SetNested

func SetNested(key, subkey string, val interface{})

SetNested puts a value in the buffer to be included in the next emission, nested under the top-level key as subkey. It overwrites any previous value.

This function is safe for multiple goroutines, and it is recommended to call this using the go keyword after the call to SendHello so it doesn't block crucial code.

func StartEmitting

func StartEmitting()

StartEmitting sends the current payload and begins the transmission cycle for updates. This is the first update sent, and future ones will be sent until StopEmitting is called.

This function is non-blocking (it spawns a new goroutine).

This function panics if it was called more than once. It is a no-op if this package was not initialized.

func StopEmitting

func StopEmitting()

StopEmitting sends the current payload and terminates the update cycle. No more updates will be sent.

It is a no-op if the package was never initialized or if emitting was never started.

NOTE: This function is blocking. Run in a goroutine if you want to guarantee no blocking at critical times like exiting the program.

Types

type Payload

type Payload struct {
	// The universally unique ID of the instance
	InstanceID string `json:"instance_id"`

	// The UTC timestamp of the transmission
	Timestamp time.Time `json:"timestamp"`

	// The timestamp before which the next update is expected
	// (NOT populated by client - the server fills this in
	// before it stores the data)
	ExpectNext time.Time `json:"expect_next,omitempty"`

	// The metrics
	Data map[string]interface{} `json:"data,omitempty"`
}

Payload is the data that gets sent to the telemetry server.

func (Payload) Int

func (p Payload) Int(key string) int

Int returns the value of the data keyed by key if it is an integer; otherwise it returns 0.

type Response

type Response struct {
	// NextUpdate is how long to wait before the next update.
	NextUpdate time.Duration `json:"next_update"`

	// Stop instructs the telemetry server to stop sending
	// telemetry. This would only be done under extenuating
	// circumstances, but we are prepared for it nonetheless.
	Stop bool `json:"stop,omitempty"`

	// Error will be populated with an error message, if any.
	// This field should be empty if the status code is < 400.
	Error string `json:"error,omitempty"`

	// DisableKeys will contain a list of keys/metrics that
	// should NOT be sent until further notice. The client
	// must NOT store these items in its buffer or send them
	// to the telemetry server while they are disabled. If
	// this list and EnableKeys have the same value (which is
	// not supposed to happen), this field should dominate.
	DisableKeys []string `json:"disable_keys,omitempty"`

	// EnableKeys will contain a list of keys/metrics that
	// MAY be sent until further notice.
	EnableKeys []string `json:"enable_keys,omitempty"`
}

Response contains the body of a response from the telemetry server.