tsmon

Documentation

Overview

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.

Index

• Variables
• func NewProdXMonitor(ctx context.Context, chunkSize int, account string) (monitor.Monitor, error)
• type Settings
• type State
  • func (s *State) Activate(ctx context.Context)
  • func (s *State) FlushPeriodically(ctx context.Context)
  • func (s *State) Middleware(c *router.Context, next router.Handler)
• type TaskNumAllocator

Variables

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

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

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.

Functions

func NewProdXMonitor

func NewProdXMonitor(ctx context.Context, chunkSize int, account string) (monitor.Monitor, error)

NewProdXMonitor creates a monitor that flushes metrics to the ProdX endpoint.

It splits them into chunks of given size and impersonates the given service account to authenticate calls.

Types

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"`

	// FlushTimeoutSec defines how long to wait for the metrics to flush before
	// giving up.
	//
	// Default is 5 sec.
	FlushTimeoutSec int `json:"flush_timeout_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(ctx 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(ctx 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(ctx 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(ctx 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.