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

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

    Variables

    This section is empty.

    Functions

    func Flush

    func Flush(c context.Context) error

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

      func Initialize

      func Initialize(c context.Context, m monitor.Monitor, s store.Store)

        Initialize configures the tsmon library with the given monitor and store.

        func InitializeFromFlags

        func InitializeFromFlags(c 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 Monitor

          func Monitor(c context.Context) monitor.Monitor

            Monitor returns the global monitor that sends metrics to monitoring endpoints. Defaults to a nil monitor, but changed by InitializeFromFlags.

            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(c context.Context)

                      ResetCumulativeMetrics resets only cumulative metrics.

                      func SetStore

                      func SetStore(c context.Context, s store.Store)

                        SetStore changes the global metric store. All metrics that were registered with the old store will be re-registered on the new store.

                        func Shutdown

                        func Shutdown(c 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(c 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) 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) 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) SetStore

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

                                                                              SetStore changes the metric store. All metrics that were registered with the old store will be re-registered on the new store.

                                                                              func (*State) Store

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

                                                                                Store returns the State's store.

                                                                                Directories

                                                                                Path Synopsis
                                                                                Package distribution contains distribution metrics, fixed width and geometric bucketers.
                                                                                Package distribution contains distribution metrics, fixed width and geometric bucketers.
                                                                                examples
                                                                                beep
                                                                                package dummy_project implements a demo application that populates monitoring data for a dummy_project.
                                                                                package dummy_project implements a demo application that populates monitoring data for a dummy_project.
                                                                                beep/dummy_project
                                                                                dummy_project implements a monitoring target interface for DummyProject.
                                                                                dummy_project implements a monitoring target interface for DummyProject.
                                                                                Package field contains constructors for metric field definitions.
                                                                                Package field contains constructors for metric field definitions.
                                                                                Package metric is the API for defining metrics and updating their values.
                                                                                Package metric is the API for defining metrics and updating their values.
                                                                                Package monitor contains the code for sending metric data to monitoring endpoints.
                                                                                Package monitor contains the code for sending metric data to monitoring endpoints.
                                                                                Package registry holds a map of all metrics registered by the process.
                                                                                Package registry holds a map of all metrics registered by the process.
                                                                                Package runtimestats exposes metrics related to the Go runtime.
                                                                                Package runtimestats exposes metrics related to the Go runtime.
                                                                                Package store contains code for storing and retrieving metrics.
                                                                                Package store contains code for storing and retrieving metrics.
                                                                                storetest
                                                                                Package storetest is imported exclusively by tests for Store implementations.
                                                                                Package storetest is imported exclusively by tests for Store implementations.
                                                                                Package target contains information about the thing that is sending metrics - either a NetworkDevice (a machine) or a Task (a service).
                                                                                Package target contains information about the thing that is sending metrics - either a NetworkDevice (a machine) or a Task (a service).
                                                                                Package ts_mon_proto contains ts_mon protobuf source and generated protobuf data.
                                                                                Package ts_mon_proto contains ts_mon protobuf source and generated protobuf data.
                                                                                Package types contains miscellaneous structs and interfaces used throughout tsmon.
                                                                                Package types contains miscellaneous structs and interfaces used throughout tsmon.
                                                                                Package versions allows processes to report string-valued metrics with versions of various libraries they link with.
                                                                                Package versions allows processes to report string-valued metrics with versions of various libraries they link with.