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 State
  • 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 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 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.
	InstanceID func(c context.Context) string

	// TaskNumAllocator knows how to dynamically map task ID to a task number.
	TaskNumAllocator TaskNumAllocator

	// IsDevMode should be set to true when running locally.
	IsDevMode bool
	// 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) 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.