counter

Documentation

Overview

Package counter implements a simple counter system for collecting totally public telemetry data.

There are two kinds of counters, simple counters and stack counters. Simple counters are created by New(<counter-name>). Stack counters are created by NewStack(<counter-name>, depth). Both are incremented by calling Inc().

Counter files are stored in LocalDir(). Their content can be accessed by Parse().

Simple counters are very cheap. Stack counters are more expensive, as they require parsing the stack. (Stack counters are implemented as a set of regular counters whose names are the concatenation of the name and the stack trace. There is an upper limit on the size of this name, about 4K bytes. If the name is too long the stack will be truncated and "truncated" appended.)

When counter files expire they are turned into reports by the upload package. The first time any counter file is created for a user, a random day of the week is selected on which counter files will expire. For the first week, that day is more than 7 days (but not more than two weeks) in the future. After that the counter files expire weekly on the same day of the week.

Index

• func Add(name string, n int64)
• func CountFlags(prefix string, fs flag.FlagSet)
• func Inc(name string)
• func Open()
• type Counter
  • func New(name string) *Counter
• type StackCounter
  • func NewStack(name string, depth int) *StackCounter

Functions

func Add

func Add(name string, n int64)

Add adds n to the counter with the given name.

func CountFlags

func CountFlags(prefix string, fs flag.FlagSet)

CountFlags creates a counter for every flag that is set and increments the counter. The name of the counter is the concatenation of prefix and the flag name.

For instance, CountFlags("gopls:flag-", flag.CommandLine)

func Inc

func Inc(name string)

Inc increments the counter with the given name.

func Open

func Open()

Open prepares telemetry counters for recording to the file system.

If the telemetry mode is "off", Open is a no-op. Otherwise, it opens the counter file on disk and starts to mmap telemetry counters to the file. Open also persists any counters already created in the current process.

Programs using telemetry should call Open exactly once.

Types

type Counter

type Counter = counter.Counter

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.

type StackCounter

type StackCounter = counter.StackCounter

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

NewStack returns a new stack counter with the given name and depth.