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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CountFlags ¶
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 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 ¶
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.
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.
Source Files