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
• type Settings
• type State
  • func (s *State) FlushPeriodically(c 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.

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

	// 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

	// IsDevMode should be set to true when running locally.
	IsDevMode bool

	// 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) 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.