metric

Documentation

Overview

Package metric implements routines for generating and saving metrics associated with servers and clients.

Index

• Constants
• func NewSpan(name errors.Op) (*Metric, *Span)
• func RegisterSaver(saver Saver)
• type Kind
• type Metric
  • func New(name errors.Op) *Metric
  • func (m *Metric) Done()
  • func (m *Metric) Spans() []*Span
  • func (m *Metric) StartSpan(name errors.Op) *Span
• type Saver
• type Span
  • func (s *Span) End() *Metric
  • func (s *Span) Metric() *Metric
  • func (s *Span) SetAnnotation(annotation string) *Span
  • func (s *Span) SetKind(kind Kind) *Span
  • func (s *Span) StartSpan(name errors.Op) *Span

Examples

• Metric

Constants

const SaveQueueLength = 1024

SaveQueueLength is the size of the queue of metrics to be saved. Too large a queue might be wasteful and too little means metrics start to take time in the critical path of instrumented services.

Functions

func NewSpan

func NewSpan(name errors.Op) (*Metric, *Span)

NewSpan creates a new unamed metric with a newly-started named span.

func RegisterSaver

func RegisterSaver(saver Saver)

RegisterSaver registers a Saver for storing Metrics onto a backend. Only one Saver may exist or it panics.

Types

type Kind

type Kind int

Kind represents where the trace was taken: Server, Client or Other.

const (
	Server Kind = iota
	Client
	Other
)

Kinds of metrics.

type Metric

type Metric struct {
	Name errors.Op
	// contains filtered or unexported fields
}

Metric is a named collection of spans. A span measures time from the beginning of an event (for example, an RPC request) until its completion.

Example

package main

import (
	"upspin.io/metric"
)

func main() {
	// In method Lookup:
	m := metric.New("Dirserver")
	s := m.StartSpan("Lookup")
	defer m.Done()
	// do some work ...
	// ... and call getRoot, passing s to it:
	ss := s.StartSpan("getRoot")
	defer ss.End()
	// do work ...
	// return

	// Should log metric DirServer.Lookup
	// with a sub-span for getRoot covering part of the Lookup span.
}

func New

func New(name errors.Op) *Metric

New creates a new named metric. If name is non-empty, it will prefix every descendant's Span name.

func (*Metric) Done

func (m *Metric) Done()

Done ends the metric and any not-yet-ended span and saves it to stable storage. Further use of the metric or any of its spans or subspans are invalid and may produce erroneous results or be silently dropped.

func (*Metric) Spans

func (m *Metric) Spans() []*Span

Spans returns the Spans recorded under this Metric. The returned slice must not be modified.

func (*Metric) StartSpan

func (m *Metric) StartSpan(name errors.Op) *Span

StartSpan starts a new span of the metric with implicit start time being the current time and Kind being Server. Spans need not be contiguous and may or may not overlap.

type Saver

type Saver interface {
	// Register informs the Saver that new Metrics will be added to queue.
	Register(queue chan *Metric)
}

Saver is the common interface that all implementation-specific backends must implement for saving a Metric to a backend. A Saver must continuously process Metrics sent over a channel, set during registration.

type Span

type Span struct {
	Name       errors.Op
	StartTime  time.Time
	EndTime    time.Time
	Kind       Kind    // Server, Client or Other kind of metric span.
	Parent     *Metric // parent of this span; may be nil.
	ParentSpan *Span   // may be nil.
	Annotation string  // optional.
}

A Span measures time from the beginning of an event (for example, an RPC request) until its completion.

func (*Span) End

func (s *Span) End() *Metric

End marks the end time of the span as the current time. It returns the parent metric for convenience which may be nil if the metric is Done.

func (*Span) Metric

func (s *Span) Metric() *Metric

Metric returns the parent metric of the span. It may be nil if the metric is Done.

func (*Span) SetAnnotation

func (s *Span) SetAnnotation(annotation string) *Span

SetAnnotation sets a custom annotation to the span s and returns it. If multiple annotations are set, the last one wins.

func (*Span) SetKind

func (s *Span) SetKind(kind Kind) *Span

SetKind sets the kind of the span s and returns it.

func (*Span) StartSpan

func (s *Span) StartSpan(name errors.Op) *Span

StartSpan starts a new span as a child of s with start time set to the current time. It may return nil if the parent Metric of s is Done.