Package tsmon adapts common/tsmon library to a server-side environment.

    It provides a bunch of useful things:

    * Hooks up tsmon library configuration to the server settings so it can
      be changed on the fly without restarts.
    * Provides a middleware that captures request metrics.
    * Periodically reports Go runtime memory stats and some other metrics.



    This section is empty.


    View Source
    var ErrNoTaskNumber = errors.New("no task number assigned yet")

      ErrNoTaskNumber is returned by NotifyTaskIsAlive if the task wasn't given a number yet.

      View Source
      var PortalPage interface {
      	// SetReadOnlySettings switches the portal page to always display the given
      	// settings instead of attempting to fetch them from the settings store.
      	SetReadOnlySettings(s *Settings, banner string)
      	// contains filtered or unexported methods
      } = &settingsPage{}

        Make some aspects of the UI configurable by external packages.


        This section is empty.


        type Settings

        type Settings struct {
        	// Enabled is false to completely shutoff the monitoring.
        	// Default is false.
        	Enabled portal.YesOrNo `json:"enabled"`
        	// ProdXAccount is a service account to use to send metrics to ProdX endpoint.
        	// If not set, metrics will be logged to local GAE log. Default is "".
        	ProdXAccount string `json:"prodx_account"`
        	// FlushIntervalSec defines how often to flush metrics to the pubsub topic.
        	// Default is 60 sec.
        	FlushIntervalSec int `json:"flush_interval_sec"`
        	// ReportRuntimeStats is true to enable reporting of Go RT stats on flush.
        	// Default is false.
        	ReportRuntimeStats portal.YesOrNo `json:"report_runtime_stats"`

          Settings contain global tsmon settings for the application.

          They are usually stored in settings store.

          type State

          type State struct {
          	// Target is lazily called to initialize default metrics target.
          	// The target identifies the collection of homogeneous processes that together
          	// implement the service. Each individual process in the collection is
          	// additionally identified by a task number, later (optionally) dynamically
          	// assigned via TaskNumAllocator based on unique InstanceID.
          	Target func(c context.Context) target.Task
          	// InstanceID returns a unique (within the scope of the service) identifier of
          	// this particular process.
          	// It will be used to assign a free task number via TaskNumAllocator.
          	// If nil, instance ID will be set to "". Useful when TaskNumAllocator is nil
          	// too (then instance ID is not important).
          	InstanceID func(c context.Context) string
          	// TaskNumAllocator knows how to dynamically map instance ID to a task number.
          	// If nil, 0 will be used as task number regardless of instance ID.
          	TaskNumAllocator TaskNumAllocator
          	// CustomMonitor, if not nil, is used to flush accumulated metrics instead of
          	// the default monitor (which is constructed on the fly based on current
          	// settings).
          	// Useful to override the default monitor in tests or when running locally in
          	// the debug mode.
          	CustomMonitor monitor.Monitor
          	// FlushInMiddleware is true to make Middleware(...) periodically
          	// synchronously send metrics to the backend after handling a request.
          	// This is useful on Standard GAE that doesn't support asynchronous flushes
          	// outside of a context of some request.
          	// If false, the user of the library *must* launch FlushPeriodically() in
          	// a background goroutine. Otherwise metrics won't be sent.
          	FlushInMiddleware bool
          	// Settings, if non nil, are static preset settings to use.
          	// If nil, settings will be loaded dynamically through 'settings' module.
          	Settings *Settings
          	// contains filtered or unexported fields

            State holds the state and configuration of the tsmon library.

            Define it as a global variable and inject it in the request contexts using State.Middleware().

            It will initialize itself from the tsmon state in the passed context on a first use, mutating it along the way. Assumes caller is consistently using contexts configured with exact same tsmon state (in a vast majority of cases it would be global tsmon state that corresponds to context.Background, but unit tests may provide its own state).

            Will panic if it detects that caller has changed tsmon state in the context between the requests.

            func (*State) Activate

            func (s *State) Activate(c context.Context)

              Activate updates the tsmon state in the context to use this config.

              Not needed if metrics are updated only from inside the middleware.

              func (*State) FlushPeriodically

              func (s *State) FlushPeriodically(c context.Context)

                FlushPeriodically runs a loop that periodically flushes metrics.

                Blocks until the context is canceled. Handles (and logs) errors internally.

                func (*State) Middleware

                func (s *State) Middleware(c *router.Context, next router.Handler)

                  Middleware is a middleware that collects request metrics and triggers metric flushes.

                  type TaskNumAllocator

                  type TaskNumAllocator interface {
                  	// NotifyTaskIsAlive is called periodically to make the allocator know the
                  	// given task is still up.
                  	// The particular task is identified by a 'task' target (which names a group
                  	// of homogeneous processes) and by 'instanceID' (which is a unique name of
                  	// the particular process within the group).
                  	// The allocator responds with the currently assigned task number or
                  	// ErrNoTaskNumber if not yet assigned. Any other error should be considered
                  	// transient.
                  	NotifyTaskIsAlive(c context.Context, task *target.Task, instanceID string) (int, error)

                    TaskNumAllocator is responsible for maintaining global mapping between instances of a service (tasks) and task numbers, used to identify metrics streams.

                    The mapping is dynamic. Once a task dies (i.e. stops periodically call NotifyTaskIsAlive), its task number may be reused by some other (new) task.