Documentation

Overview

Package metrics defines a set of primitives for declaring and managing metrics within Bigslice. Users declare metrics (such as a counter) using the registration mechanisms provided by this package (e.g., NewCounter). These return handles that are used for metric operations (e.g., incrementing a counter).

Every operation on a metric is performed in a Scope. Scopes are provided by the Bigslice runtime and represent an operational scope in which the metric is aggregated. For example, Bigslice defines a Scope that is attached to each task scheduled by the system. Scopes are merged by the Bigslice runtime to provide aggregated metrics across larger operations (e.g., a single session.Run).

User functions called by Bigslice are supplied a scope through the optional context.Context argument. The user must retrieve this Scope using the ContextScope func.

Metrics cannot be declared concurrently.

Index

• func ScopedContext(ctx context.Context, scope *Scope) context.Context
• type Counter
  • func NewCounter() Counter
  • func (c Counter) Incr(scope *Scope, n int64)
  • func (c Counter) Value(scope *Scope) int64
• type Metric
• type Scope
  • func ContextScope(ctx context.Context) *Scope
  • func (s *Scope) GobDecode(p []byte) error
  • func (s *Scope) GobEncode() ([]byte, error)
  • func (s *Scope) Merge(u *Scope)
  • func (s *Scope) Reset(u *Scope)

Examples

• Counter

Constants

This section is empty.

Variables

This section is empty.

Functions

func ScopedContext

func ScopedContext(ctx context.Context, scope *Scope) context.Context

ScopedContext returns a context with the provided scope attached. The scope may be retrieved by ContextScope.

Types

type Counter

type Counter struct {
	// contains filtered or unexported fields
}

Counter is a simple counter metric. Counters implement atomic addition and subtraction on top of an int64.

Example

package main import ( "context" "fmt" "log" "github.com/grailbio/bigslice" "github.com/grailbio/bigslice/exec" "github.com/grailbio/bigslice/metrics" ) func main() { filterCount := metrics.NewCounter() filterFunc := bigslice.Func(func() (slice bigslice.Slice) { slice = bigslice.Const(1, []int{1, 2, 3, 4, 5, 6}) slice = bigslice.Filter(slice, func(ctx context.Context, i int) bool { scope := metrics.ContextScope(ctx) if i%2 == 0 { filterCount.Incr(scope, 1) return false } return true }) return }) sess := exec.Start(exec.Local) res, err := sess.Run(context.Background(), filterFunc) if err != nil { log.Fatal(err) } fmt.Println("filtered:", filterCount.Value(res.Scope())) }

Output:

filtered: 3

func NewCounter

func NewCounter() Counter

NewCounter creates, registers, and returns a new Counter metric.

func (Counter) Incr

func (c Counter) Incr(scope *Scope, n int64)

Incr increments this counter's value in the provided scope by n.

func (Counter) Value

func (c Counter) Value(scope *Scope) int64

Value retrieves the current value of this metric in the provided scope.

type Metric

type Metric interface {
	// contains filtered or unexported methods
}

Metric is the abstract type of a metric. Each metric type must implement a set of generic operations; the metric-specific operations are provided by the metric types themselves.

TODO(marius): eventually consider opening up this interface to allow users to provide their own metrics implementations.

type Scope

type Scope struct {
	// contains filtered or unexported fields
}

Scope is a collection of metric instances.

func ContextScope

func ContextScope(ctx context.Context) *Scope

ContextScope returns the scope attached to the provided context. ContextScope panics if the context does not have an attached scope.

func (*Scope) GobDecode

func (s *Scope) GobDecode(p []byte) error

GobDecode implements a custom gob decoder for scopes.

func (*Scope) GobEncode

func (s *Scope) GobEncode() ([]byte, error)

GobEncode implements a custom gob encoder for scopes.

func (*Scope) Merge

func (s *Scope) Merge(u *Scope)

Merge merges instances from Scope u into Scope s.

func (*Scope) Reset

func (s *Scope) Reset(u *Scope)

Reset resets the scope s to u. It is reset to its initial (zero) state if u is nil.