tsmon

Documentation

Overview

Package tsmon contains global state and utility functions for configuring and interacting with tsmon. This has a similar API to the infra-python ts_mon module.

If your application accepts command line flags, then call InitializeFromFlags from your main function.

If you use tsmon on AppEngine, then see appengine/tsmon package doc.

Index

• Constants
• func Flush(ctx context.Context) error
• func InitializeFromFlags(ctx context.Context, fl *Flags) error
• func RegisterCallback(f Callback)
• func RegisterCallbackIn(ctx context.Context, f Callback)
• func RegisterGlobalCallback(f Callback, metrics ...types.Metric)
• func RegisterGlobalCallbackIn(ctx context.Context, f Callback, metrics ...types.Metric)
• func ResetCumulativeMetrics(ctx context.Context)
• func Shutdown(ctx context.Context)
• func Store(ctx context.Context) store.Store
• func WithDummyInMemory(ctx context.Context) (context.Context, *monitor.Fake)
• func WithFakes(ctx context.Context) (context.Context, *store.Fake, *monitor.Fake)
• func WithState(ctx context.Context, s *State) context.Context
• type Callback
• type Flags
  • func NewFlags() Flags
  • func (fl *Flags) Register(f *flag.FlagSet)
• type FlushType
  • func (ft *FlushType) Set(v string) error
  • func (ft *FlushType) String() string
• type GlobalCallback
• type State
  • func GetState(ctx context.Context) *State
  • func NewState() *State
  • func (s *State) Callbacks() []Callback
  • func (s *State) Flush(ctx context.Context, mon monitor.Monitor) error
  • func (s *State) GlobalCallbacks() []GlobalCallback
  • func (s *State) InhibitGlobalCallbacksOnFlush()
  • func (s *State) InvokeGlobalCallbacksOnFlush()
  • func (s *State) Monitor() monitor.Monitor
  • func (s *State) ParallelFlush(ctx context.Context, mon monitor.Monitor, workers int) error
  • func (s *State) RegisterCallbacks(f ...Callback)
  • func (s *State) RegisterGlobalCallbacks(f ...GlobalCallback)
  • func (s *State) Registry() *registry.Registry
  • func (s *State) ResetCumulativeMetrics(ctx context.Context)
  • func (s *State) RunGlobalCallbacks(ctx context.Context)
  • func (s *State) SetMonitor(m monitor.Monitor)
  • func (s *State) SetRegistry(r *registry.Registry)
  • func (s *State) SetStore(st store.Store)
  • func (s *State) Store() store.Store

Constants

const (
	// FlushManual requires the user to flush manually.
	FlushManual = FlushType("manual")
	// FlushAuto automatically flushes at a periodic flush interval.
	FlushAuto = FlushType("auto")
)

Functions

func Flush

func Flush(ctx context.Context) error

Flush sends all the metrics that are registered in the application.

func InitializeFromFlags

func InitializeFromFlags(ctx context.Context, fl *Flags) error

InitializeFromFlags configures the tsmon library from flag values.

This will set a Target (information about what's reporting metrics) and a Monitor (where to send the metrics to).

func RegisterCallback

func RegisterCallback(f Callback)

RegisterCallback registers a callback function that will be run at metric collection time to set the values of one or more metrics. RegisterCallback should be called from an init() function in your module.

func RegisterCallbackIn

func RegisterCallbackIn(ctx context.Context, f Callback)

RegisterCallbackIn is like RegisterCallback but registers in a given context.

func RegisterGlobalCallback

func RegisterGlobalCallback(f Callback, metrics ...types.Metric)

RegisterGlobalCallback registers a callback function that will be run once per minute on *one* instance of your application. It is supported primarily on GAE.

You must specify the list of metrics that your callback affects - these metrics will be reset after flushing to ensure they are not sent by multiple instances.

RegisterGlobalCallback should be called from an init() function in your module.

func RegisterGlobalCallbackIn

func RegisterGlobalCallbackIn(ctx context.Context, f Callback, metrics ...types.Metric)

RegisterGlobalCallbackIn is like RegisterGlobalCallback but registers in a given context.

func ResetCumulativeMetrics

func ResetCumulativeMetrics(ctx context.Context)

ResetCumulativeMetrics resets only cumulative metrics.

func Shutdown

func Shutdown(ctx context.Context)

Shutdown gracefully terminates the tsmon by doing the final flush and disabling auto flush (if it was enabled).

It resets Monitor and Store.

Logs error to standard logger. Does nothing if tsmon wasn't initialized.

func Store

func Store(ctx context.Context) store.Store

Store returns the global metric store that contains all the metric values for this process. Applications shouldn't need to access this directly - instead use the metric objects which provide type-safe accessors.

func WithDummyInMemory

func WithDummyInMemory(ctx context.Context) (context.Context, *monitor.Fake)

WithDummyInMemory returns a new context holding a new State with a new in- memory store and a fake monitor.

func WithFakes

func WithFakes(ctx context.Context) (context.Context, *store.Fake, *monitor.Fake)

WithFakes returns a new context holding a new State with a fake store and a fake monitor.

func WithState

func WithState(ctx context.Context, s *State) context.Context

WithState returns a new context holding the given State instance.

Types

type Callback

type Callback func(ctx context.Context)

Callback is a function that is run at metric collection time to set the values of one or more metrics. A callback can be registered with RegisterCallback.

type Flags

type Flags struct {
	ConfigFile    string
	Endpoint      string
	Credentials   string
	ActAs         string
	Flush         FlushType
	FlushInterval time.Duration

	Target target.Flags
}

Flags defines command line flags related to tsmon. Use NewFlags() to get a Flags struct with sensible default values.

func NewFlags

func NewFlags() Flags

NewFlags returns a Flags struct with sensible default values.

func (*Flags) Register

func (fl *Flags) Register(f *flag.FlagSet)

Register adds tsmon related flags to a FlagSet.

type FlushType

type FlushType string

FlushType is a flush type enumeration.

func (*FlushType) Set

func (ft *FlushType) Set(v string) error

Set implements flag.Value.

func (*FlushType) String

func (ft *FlushType) String() string

type GlobalCallback

type GlobalCallback struct {
	Callback
	// contains filtered or unexported fields
}

A GlobalCallback is a Callback with the list of metrics it affects, so those metrics can be reset after they are flushed.

type State

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

State holds the configuration of the tsmon library. There is one global instance of State, but it can be overridden in a Context by tests.

func GetState

func GetState(ctx context.Context) *State

GetState returns the State instance held in the context (if set) or else returns the global State.

func NewState

func NewState() *State

NewState returns a new State instance, configured with a nil store and nil monitor. By default, global callbacks that are registered will be invoked when flushing registered metrics.

func (*State) Callbacks

func (s *State) Callbacks() []Callback

Callbacks returns all registered Callbacks.

func (*State) Flush

func (s *State) Flush(ctx context.Context, mon monitor.Monitor) error

Flush sends all the metrics that are registered in the application.

Uses given monitor if not nil, otherwise the State's current monitor.

func (*State) GlobalCallbacks

func (s *State) GlobalCallbacks() []GlobalCallback

GlobalCallbacks returns all registered GlobalCallbacks.

func (*State) InhibitGlobalCallbacksOnFlush

func (s *State) InhibitGlobalCallbacksOnFlush()

InhibitGlobalCallbacksOnFlush signals that the registered global callbacks are not to be executed upon flushing registered metrics.

func (*State) InvokeGlobalCallbacksOnFlush

func (s *State) InvokeGlobalCallbacksOnFlush()

InvokeGlobalCallbacksOnFlush signals that the registered global callbacks are to be be executed upon flushing registered metrics.

func (*State) Monitor

func (s *State) Monitor() monitor.Monitor

Monitor returns the State's monitor.

func (*State) ParallelFlush

func (s *State) ParallelFlush(ctx context.Context, mon monitor.Monitor, workers int) error

ParallelFlush is similar to Flush, but sends multiple requests in parallel.

This can be useful to optimize the total duration of flushing for an excessive number of cells.

Panics if workers < 1.

func (*State) RegisterCallbacks

func (s *State) RegisterCallbacks(f ...Callback)

RegisterCallbacks registers the given Callback(s) with State.

func (*State) RegisterGlobalCallbacks

func (s *State) RegisterGlobalCallbacks(f ...GlobalCallback)

RegisterGlobalCallbacks registers the given GlobalCallback(s) with State.

func (*State) Registry

func (s *State) Registry() *registry.Registry

Registry returns the State's registry.

func (*State) ResetCumulativeMetrics

func (s *State) ResetCumulativeMetrics(ctx context.Context)

ResetCumulativeMetrics resets only cumulative metrics.

func (*State) RunGlobalCallbacks

func (s *State) RunGlobalCallbacks(ctx context.Context)

RunGlobalCallbacks runs all registered global callbacks that produce global metrics.

See RegisterGlobalCallback for more info.

func (*State) SetMonitor

func (s *State) SetMonitor(m monitor.Monitor)

SetMonitor sets the Store's monitor.

func (*State) SetRegistry

func (s *State) SetRegistry(r *registry.Registry)

SetRegistry changes the metric registry.

func (*State) SetStore

func (s *State) SetStore(st store.Store)

SetStore changes the metric store.

func (*State) Store

func (s *State) Store() store.Store

Store returns the State's store.