// 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