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 Open() func()
• func Read(c *Counter) (uint64, 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 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 Open

func Open() 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 ReadStack

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

ReadStack reads the given stack counter. This is the implementation of cuelang.org/go/internal/golangorgx/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.