doc.go (2769B)
1 // Copyright 2023 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 // Package counter implements a simple counter system for collecting 6 // totally public telemetry data. 7 // 8 // There are two kinds of counters, basic counters and stack counters. 9 // Basic counters are created by [New]. 10 // Stack counters are created by [NewStack]. 11 // Both are incremented by calling Inc(). 12 // 13 // Basic counters are very cheap. Stack counters are more expensive, as they 14 // require parsing the stack. (Stack counters are implemented as basic counters 15 // whose names are the concatenation of the name and the stack trace. There is 16 // an upper limit on the size of this name, about 4K bytes. If the name is too 17 // long the stack will be truncated and "truncated" appended.) 18 // 19 // When counter files expire they are turned into reports by the upload 20 // package. The first time any counter file is created for a user, a random day 21 // of the week is selected on which counter files will expire. For the first 22 // week, that day is more than 7 days (but not more than two weeks) in the 23 // future. After that the counter files expire weekly on the same day of the 24 // week. 25 // 26 // # Counter Naming 27 // 28 // Counter names passed to [New] and [NewStack] should follow these 29 // conventions: 30 // 31 // - Names cannot contain whitespace or newlines. 32 // 33 // - Names must be valid unicode, with no unprintable characters. 34 // 35 // - Names may contain at most one ':'. In the counter "foo:bar", we refer to 36 // "foo" as the "chart name" and "bar" as the "bucket name". 37 // 38 // - The '/' character should partition counter names into a hierarchy. The 39 // root of this hierarchy should identify the logical entity that "owns" 40 // the counter. This could be an application, such as "gopls" in the case 41 // of "gopls/client:vscode", or a shared library, such as "crash" in the 42 // case of the "crash/crash" counter owned by the crashmonitor library. If 43 // the entity name itself contains a '/', that's ok: "cmd/go/flag" is fine. 44 // 45 // - Words should be '-' separated, as in "gopls/completion/errors-latency" 46 // 47 // - Histograms should use bucket names identifying upper bounds with '<'. 48 // For example given two counters "gopls/completion/latency:<50ms" and 49 // "gopls/completion/latency:<100ms", the "<100ms" bucket counts events 50 // with latency in the half-open interval [50ms, 100ms). 51 // 52 // # Debugging 53 // 54 // The GODEBUG environment variable can enable printing of additional debug 55 // information for counters. Adding GODEBUG=countertrace=1 to the environment 56 // of a process using counters causes the x/telemetry/counter package to log 57 // counter information to stderr. 58 package counter