package telemetry

import "golang.org/x/telemetry/internal/telemetry"

Package telemetry manages the telemetry mode file.

Index ¶

• Constants
• func IsToolchainProgram(progPath string) bool
• func ProgramInfo(info *debug.BuildInfo) (goVers, progPath, progVers string)
• type CounterConfig
• type Dir
• func NewDir(dir string) Dir
• func (d Dir) DebugDir() string
• func (d Dir) Dir() string
• func (d Dir) LocalDir() string
• func (d Dir) Mode() (string, time.Time)
• func (d Dir) ModeFile() string
• func (d Dir) SetMode(mode string) error
• func (d Dir) SetModeAsOf(mode string, asofTime time.Time) error
• func (d Dir) UploadDir() string
• type ProgramConfig
• type ProgramReport
• type Report
• type UploadConfig

Constants ¶

const DateOnly = "2006-01-02"

TODO(rfindley): replace uses of DateOnly with time.DateOnly once we no longer support building gopls with go 1.19.

const DisabledOnPlatform = false ||

	runtime.GOOS == "openbsd" ||
	runtime.GOOS == "solaris" ||
	runtime.GOOS == "android" ||
	runtime.GOOS == "illumos" ||

	runtime.GOOS == "js" ||
	runtime.GOOS == "wasip1" ||
	runtime.GOOS == "plan9" ||
	runtime.GOARCH == "mips" || runtime.GOARCH == "mipsle" // mips lacks cross-process 64-bit atomics

DisabledOnPlatform indicates whether telemetry is disabled due to bugs in the current platform.

TODO(rfindley): move to a more appropriate file.

Functions ¶

func IsToolchainProgram ¶

func IsToolchainProgram(progPath string) bool

IsToolchainProgram reports whether a program with the given path is a Go toolchain program.

func ProgramInfo ¶

func ProgramInfo(info *debug.BuildInfo) (goVers, progPath, progVers string)

ProgramInfo extracts the go version, program package path, and program version to use for counter files.

For programs in the Go toolchain, the program version will be the same as the Go version, and will typically be of the form "go1.2.3", not a semantic version of the form "v1.2.3". Go versions may also include spaces and special characters.

Types ¶

type CounterConfig ¶

type CounterConfig struct {
	Name  string  // The "collapsed" counter: <chart>:{<bucket1>,<bucket2>,...}
	Rate  float64 // If X <= Rate, report this counter
	Depth int     `json:",omitempty"` // for stack counters
}

type Dir ¶

type Dir struct {
	// contains filtered or unexported fields
}

A Dir holds paths to telemetry data inside a directory.

var Default Dir

Default is the default directory containing Go telemetry configuration and data.

If Default is uninitialized, Default.Mode will be "off". As a consequence, no data should be written to the directory, and so the path values of LocalDir, UploadDir, etc. must not matter.

Default is a global for convenience and testing, but should not be mutated outside of tests.

TODO(rfindley): it would be nice to completely eliminate this global state, or at least push it in the golang.org/x/telemetry package

func NewDir ¶

func NewDir(dir string) Dir

NewDir creates a new Dir encapsulating paths in the given dir.

NewDir does not create any new directories or files--it merely encapsulates the telemetry directory layout.

func (Dir) DebugDir ¶

func (d Dir) DebugDir() string

func (Dir) Dir ¶

func (d Dir) Dir() string

func (Dir) LocalDir ¶

func (d Dir) LocalDir() string

func (Dir) Mode ¶

func (d Dir) Mode() (string, time.Time)

Mode returns the current telemetry mode, as well as the time that the mode was effective.

If there is no effective time, the second result is the zero time.

If Mode is "off", no data should be written to the telemetry directory, and the other paths values referenced by Dir should be considered undefined. This accounts for the case where initializing Default fails, and therefore local telemetry paths are unknown.

func (Dir) ModeFile ¶

func (d Dir) ModeFile() string

func (Dir) SetMode ¶

func (d Dir) SetMode(mode string) error

SetMode updates the telemetry mode with the given mode. Acceptable values for mode are "on", "off", or "local".

SetMode always writes the mode file, and explicitly records the date at which the modefile was updated. This means that calling SetMode with "on" effectively resets the timeout before the next telemetry report is uploaded.

func (Dir) SetModeAsOf ¶

func (d Dir) SetModeAsOf(mode string, asofTime time.Time) error

SetModeAsOf is like SetMode, but accepts an explicit time to use to back-date the mode state. This exists only for testing purposes.

func (Dir) UploadDir ¶

func (d Dir) UploadDir() string

type ProgramConfig ¶

type ProgramConfig struct {
	// the counter names may have to be
	// repeated for each program. (e.g., if the counters are in a package
	// that is used in more than one program.)
	Name     string
	Versions []string        // versions present in a counterconfig
	Counters []CounterConfig `json:",omitempty"`
	Stacks   []CounterConfig `json:",omitempty"`
}

type ProgramReport ¶

type ProgramReport struct {
	Program   string // Package path of the program.
	Version   string // Program version. Go version if the program is part of the go distribution. Module version, otherwise.
	GoVersion string // Go version used to build the program.
	GOOS      string
	GOARCH    string
	Counters  map[string]int64
	Stacks    map[string]int64
}

type Report ¶

type Report struct {
	Week     string  // End day this report covers (YYYY-MM-DD)
	LastWeek string  // Week field from latest previous report uploaded
	X        float64 // A random probability used to determine which counters are uploaded
	Programs []*ProgramReport
	Config   string // version of UploadConfig used
}

A Report is the weekly aggregate of counters.

type UploadConfig ¶

type UploadConfig struct {
	GOOS       []string
	GOARCH     []string
	GoVersion  []string
	SampleRate float64
	Programs   []*ProgramConfig
}

An UploadConfig controls what data is uploaded.

Source Files ¶

dateonly.go dir.go proginfo.go types.go