counter

Documentation

Overview

Package internal/counter implements the internals of the public counter package. In addition to the public API, this package also includes APIs to parse and manage the counter files, needed by the upload package.

Index

• Constants
• Variables
• func DecodeStack(ename string) string
• func EncodeStack(pcs []uintptr, prefix string) string
• func IsStackCounter(name string) bool
• func Open(rotate bool) func()
• func Read(c *Counter) (uint64, error)
• func ReadFile(name string) (counters, stackCounters map[string]uint64, _ error)
• func ReadMapped(name string) ([]byte, error)
• func ReadStack(c *StackCounter) (map[string]uint64, error)
• type Counter
  • func New(name string) *Counter
  • func (c *Counter) Add(n int64)
  • func (c *Counter) Inc()
  • func (c *Counter) Name() string
• type File
  • func Parse(filename string, data []byte) (*File, error)
• type StackCounter
  • func NewStack(name string, depth int) *StackCounter
  • func (c *StackCounter) Counters() []*Counter
  • func (c *StackCounter) Inc()
  • func (c *StackCounter) Names() []string

Constants

const (
	FileVersion = "v1"
)

Variables

var CounterTime = func() time.Time {
	return time.Now().UTC()
}

CounterTime returns the current UTC time. Mutable for testing.

var (
	CrashOnBugs = false // for testing; if set, exit on fatal log messages
)

var ErrDisabled = errors.New("counter: disabled as Go telemetry is off")

ErrDisabled is the error returned when telemetry is disabled.

Functions

func DecodeStack

func DecodeStack(ename string) string

DecodeStack expands the (compressed) stack encoded in the counter name.

func EncodeStack

func EncodeStack(pcs []uintptr, prefix string) string

EncodeStack returns the name of the counter to use for the given stack of program counters. The name encodes the stack.

func IsStackCounter

func IsStackCounter(name string) bool

IsStackCounter reports whether the counter name is for a stack counter.

func Open

func Open(rotate bool) func()

Open associates counting with the defaultFile. The returned function is for testing only, and should be called after all Inc()s are finished, but before any reports are generated. (Otherwise expired count files will not be deleted on Windows.)

func Read

func Read(c *Counter) (uint64, error)

Read reads the given counter. This is the implementation of x/telemetry/counter/countertest.ReadCounter.

func ReadFile

func ReadFile(name string) (counters, stackCounters map[string]uint64, _ error)

ReadFile reads the counters and stack counters from the given file. This is the implementation of x/telemetry/counter/countertest.ReadFile.

func ReadMapped

func ReadMapped(name string) ([]byte, error)

ReadMapped reads the contents of the given file by memory mapping.

This avoids file synchronization issues.

func ReadStack

func ReadStack(c *StackCounter) (map[string]uint64, error)

ReadStack reads the given stack counter. This is the implementation of golang.org/x/telemetry/counter/countertest.ReadStackCounter.

Types

type Counter

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

A Counter is a single named event counter. A Counter is safe for use by multiple goroutines simultaneously.

Counters should typically be created using New and stored as global variables, like:

package mypackage
var errorCount = counter.New("mypackage/errors")

(The initialization of errorCount in this example is handled entirely by the compiler and linker; this line executes no code at program startup.)

Then code can call Add to increment the counter each time the corresponding event is observed.

Although it is possible to use New to create a Counter each time a particular event needs to be recorded, that usage fails to amortize the construction cost over multiple calls to Add, so it is more expensive and not recommended.

func New

func New(name string) *Counter

New returns a counter with the given name. New can be called in global initializers and will be compiled down to linker-initialized data. That is, calling New to initialize a global has no cost at program startup.

func (*Counter) Add

func (c *Counter) Add(n int64)

Add adds n to the counter. n cannot be negative, as counts cannot decrease.

func (*Counter) Inc

func (c *Counter) Inc()

Inc adds 1 to the counter.

func (*Counter) Name

func (c *Counter) Name() string

type File

type File struct {
	Meta  map[string]string
	Count map[string]uint64
}

func Parse

func Parse(filename string, data []byte) (*File, error)

type StackCounter

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

a StackCounter is the in-memory knowledge about a stack counter. StackCounters are more expensive to use than regular Counters, requiring, at a minimum, a call to runtime.Callers.

func NewStack

func NewStack(name string, depth int) *StackCounter

func (*StackCounter) Counters

func (c *StackCounter) Counters() []*Counter

Counters returns the known Counters for a StackCounter. There may be more in the count file.

func (*StackCounter) Inc

func (c *StackCounter) Inc()

Inc increments a stack counter. It computes the caller's stack and looks up the corresponding counter. It then increments that counter, creating it if necessary.

func (*StackCounter) Names

func (c *StackCounter) Names() []string

Names reports all the counter names associated with a StackCounter.