59 lines
2.7 KiB
Go
59 lines
2.7 KiB
Go
|
// Copyright 2023 The Go Authors. All rights reserved.
|
||
|
|
// Use of this source code is governed by a BSD-style
|
||
|
|
// license that can be found in the LICENSE file.
|
||
|
|
|
||
|
|
// Package counter implements a simple counter system for collecting
|
||
|
|
// totally public telemetry data.
|
||
|
|
//
|
||
|
|
// There are two kinds of counters, basic counters and stack counters.
|
||
|
|
// Basic counters are created by [New].
|
||
|
|
// Stack counters are created by [NewStack].
|
||
|
|
// Both are incremented by calling Inc().
|
||
|
|
//
|
||
|
|
// Basic counters are very cheap. Stack counters are more expensive, as they
|
||
|
|
// require parsing the stack. (Stack counters are implemented as basic 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.
|
||
|
|
//
|
||
|
|
// # Counter Naming
|
||
|
|
//
|
||
|
|
// Counter names passed to [New] and [NewStack] should follow these
|
||
|
|
// conventions:
|
||
|
|
//
|
||
|
|
// - Names cannot contain whitespace or newlines.
|
||
|
|
//
|
||
|
|
// - Names must be valid unicode, with no unprintable characters.
|
||
|
|
//
|
||
|
|
// - Names may contain at most one ':'. In the counter "foo:bar", we refer to
|
||
|
|
// "foo" as the "chart name" and "bar" as the "bucket name".
|
||
|
|
//
|
||
|
|
// - The '/' character should partition counter names into a hierarchy. The
|
||
|
|
// root of this hierarchy should identify the logical entity that "owns"
|
||
|
|
// the counter. This could be an application, such as "gopls" in the case
|
||
|
|
// of "gopls/client:vscode", or a shared library, such as "crash" in the
|
||
|
|
// case of the "crash/crash" counter owned by the crashmonitor library. If
|
||
|
|
// the entity name itself contains a '/', that's ok: "cmd/go/flag" is fine.
|
||
|
|
//
|
||
|
|
// - Words should be '-' separated, as in "gopls/completion/errors-latency"
|
||
|
|
//
|
||
|
|
// - Histograms should use bucket names identifying upper bounds with '<'.
|
||
|
|
// For example given two counters "gopls/completion/latency:<50ms" and
|
||
|
|
// "gopls/completion/latency:<100ms", the "<100ms" bucket counts events
|
||
|
|
// with latency in the half-open interval [50ms, 100ms).
|
||
|
|
//
|
||
|
|
// # Debugging
|
||
|
|
//
|
||
|
|
// The GODEBUG environment variable can enable printing of additional debug
|
||
|
|
// information for counters. Adding GODEBUG=countertrace=1 to the environment
|
||
|
|
// of a process using counters causes the x/telemetry/counter package to log
|
||
|
|
// counter information to stderr.
|
||
|
|
package counter
|