telemetry

package module
v0.0.0-...-889c202 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 9, 2024 License: BSD-3-Clause Imports: 13 Imported by: 3

README

Go Telemetry

This repository holds the Go Telemetry server code and libraries, used for hosting telemetry.go.dev and instrumenting Go toolchain programs with opt-in telemetry.

Warning: this repository is intended for use only in tools maintained by the Go team, including tools in the Go distribution and auxiliary tools like gopls or govulncheck. There are no compatibility guarantees for any of the packages here: public APIs will change in breaking ways as the telemetry integration is refined.

Notable Packages

  • The x/telemetry/counter package provides a library for instrumenting programs with counters and stack reports.
  • The x/telemetry/upload package provides a hook for Go toolchain programs to upload telemetry data, if the user has opted in to telemetry uploading.
  • The x/telemetry/cmd/gotelemetry command is used for managing telemetry data and configuration.
  • The x/telemetry/config package defines the subset of telemetry data that has been approved for uploading by the telemetry proposal process.
  • The x/telemetry/godev directory defines the services running at telemetry.go.dev.

Contributing

This repository uses Gerrit for code changes. To learn how to submit changes to this repository, see https://golang.org/doc/contribute.html.

The main issue tracker for the time repository is located at https://github.com/golang/go/issues. Prefix your issue with "x/telemetry:" in the subject line, so it is easy to find.

Linting & Formatting

This repository uses eslint to format TS files, stylelint to format CSS files, and prettier to format TS, CSS, Markdown, and YAML files.

See the style guides:

It is encouraged that all TS and CSS code be run through formatters before submitting a change. However, it is not a strict requirement enforced by CI.

Installing npm Dependencies:
  1. Install docker
  2. Run ./npm install
Run ESLint, Stylelint, & Prettier
./npm run all

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Mode

func Mode() string

Mode returns the current telemetry mode.

The telemetry mode is a global value that controls both the local collection and uploading of telemetry data. Possible mode values are:

  • "on": both collection and uploading is enabled
  • "local": collection is enabled, but uploading is disabled
  • "off": both collection and uploading are disabled

When mode is "on", or "local", telemetry data is written to the local file system and may be inspected with the gotelemetry command.

If an error occurs while reading the telemetry mode from the file system, Mode returns the default value "local".

func SetMode

func SetMode(mode string) error

SetMode sets the global telemetry mode to the given value.

See the documentation of Mode for a description of the supported mode values.

An error is returned if the provided mode value is invalid, or if an error occurs while persisting the mode value to the file system.

Types

type Config

type Config struct {
	// ReportCrashes, if set, will enable crash reporting.
	// ReportCrashes uses the [debug.SetCrashOutput] mechanism, which is a
	// process-wide resource.
	// Do not make other calls to that function within your application.
	// ReportCrashes is a non-functional unless the program is built with go1.23+.
	ReportCrashes bool

	// Upload causes this program to periodically upload approved counters
	// from the local telemetry database to telemetry.go.dev.
	//
	// This option has no effect unless the user has given consent
	// to enable data collection, for example by running
	// cmd/gotelemetry or affirming the gopls dialog.
	//
	// (This feature is expected to be used only by gopls.
	// Longer term, the go command may become the sole program
	// responsible for uploading.)
	Upload bool

	// TelemetryDir, if set, will specify an alternate telemetry
	// directory to write data to. If not set, it uses the default
	// directory.
	// This field is intended to be used for isolating testing environments.
	TelemetryDir string

	// UploadStartTime, if set, overrides the time used as the upload start time,
	// which is the time used by the upload logic to determine whether counter
	// file data should be uploaded. Only counter files that have expired before
	// the start time are considered for upload.
	//
	// This field can be used to simulate a future upload that collects recently
	// modified counters.
	UploadStartTime time.Time

	// UploadURL, if set, overrides the URL used to receive uploaded reports. If
	// unset, this URL defaults to https://telemetry.go.dev/upload.
	UploadURL string
}

Config controls the behavior of Start.

type CounterConfig

type CounterConfig = telemetry.CounterConfig

type ProgramConfig

type ProgramConfig = telemetry.ProgramConfig

type ProgramReport

type ProgramReport = telemetry.ProgramReport

type Report

type Report = telemetry.Report

A Report is what's uploaded (or saved locally)

type StartResult

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

A StartResult is a handle to the result of a call to Start. Call StartResult.Wait to wait for the completion of all work done on behalf of Start.

func Start

func Start(config Config) *StartResult

Start initializes telemetry using the specified configuration.

Start opens the local telemetry database so that counter increment operations are durably recorded in the local file system.

If [Config.Upload] is set, and the user has opted in to telemetry uploading, this process may attempt to upload approved counters to telemetry.go.dev.

If [Config.ReportCrashes] is set, any fatal crash will be recorded by incrementing a counter named for the stack of the first running goroutine in the traceback.

If either of these flags is set, Start re-executes the current executable as a child process, in a special mode in which it acts as a telemetry sidecar for the parent process (the application). In that mode, the call to Start will never return, so Start must be called immediately within main, even before such things as inspecting the command line. The application should avoid expensive steps or external side effects in init functions, as they will be executed twice (parent and child).

Start returns a StartResult, which may be awaited via StartResult.Wait to wait for all work done by Start to complete.

func (*StartResult) Wait

func (res *StartResult) Wait()

Wait waits for the completion of all work initiated by Start.

type UploadConfig

type UploadConfig = telemetry.UploadConfig

An UploadConfig controls what data is uploaded.

Directories

Path Synopsis
cmd
gotelemetry
Gotelemetry is a tool for managing Go telemetry data and settings.
Gotelemetry is a tool for managing Go telemetry data and settings.
gotelemetry/internal/browser
Package browser provides utilities for interacting with users' browsers.
Package browser provides utilities for interacting with users' browsers.
gotelemetry/internal/csv
csv dumps all the active counters.
csv dumps all the active counters.
gotelemetry/internal/view
The view command is a server intended to be run on a user's machine to display the local counters and time series charts of counters.
The view command is a server intended to be run on a user's machine to display the local counters and time series charts of counters.
config module
Package counter implements a simple counter system for collecting totally public telemetry data.
Package counter implements a simple counter system for collecting totally public telemetry data.
countertest
countertest provides testing utilities for counters.
countertest provides testing utilities for counters.
godev module
internal
chartconfig
The chartconfig package defines the ChartConfig type, representing telemetry chart configuration, as well as utilities for parsing and validating this configuration.
The chartconfig package defines the ChartConfig type, representing telemetry chart configuration, as well as utilities for parsing and validating this configuration.
config
package config provides methods for loading and querying a telemetry upload config file.
package config provides methods for loading and querying a telemetry upload config file.
configgen
Package configgen generates the upload config file stored in the config.json file of golang.org/x/telemetry/config based on the chartconfig stored in config.txt.
Package configgen generates the upload config file stored in the config.json file of golang.org/x/telemetry/config based on the chartconfig stored in config.txt.
configstore
Package configstore abstracts interaction with the telemetry config server.
Package configstore abstracts interaction with the telemetry config server.
configtest
Package configtest provides a helper for testing using a local proxy containing a fake upload config.
Package configtest provides a helper for testing using a local proxy containing a fake upload config.
counter
Package internal/counter implements the internals of the public counter package.
Package internal/counter implements the internals of the public counter package.
mmap
The mmap package provides an abstraction for memory mapping files on different platforms.
The mmap package provides an abstraction for memory mapping files on different platforms.
proxy
Package proxy provides functions for writing module data to a directory in proxy format, so that it can be used as a module proxy by setting GOPROXY="file://<dir>".
Package proxy provides functions for writing module data to a directory in proxy format, so that it can be used as a module proxy by setting GOPROXY="file://<dir>".
regtest
Package regtest provides helpers for end-to-end testing involving counter and upload packages.
Package regtest provides helpers for end-to-end testing involving counter and upload packages.
telemetry
Package telemetry manages the telemetry mode file.
Package telemetry manages the telemetry mode file.
testenv
Package testenv contains helper functions for skipping tests based on which tools are present in the environment.
Package testenv contains helper functions for skipping tests based on which tools are present in the environment.
unionfs
Package unionfs allows multiple file systems to be read as a union.
Package unionfs allows multiple file systems to be read as a union.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL