telemetry

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://go.dev/doc/contribute.

The git repository is https://go.googlesource.com/telemetry.

The main issue tracker for the telemetry repository is located at https://go.dev/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:

• TypeScript
• CSS

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

• func Dir() string
• func MaybeChild(config Config)
• func Mode() string
• func SetMode(mode string) error
• type Config
• type CounterConfig
• type ProgramConfig
• type ProgramReport
• type Report
• type StartResult
  • func Start(config Config) *StartResult
  • func (res *StartResult) Wait()
• type UploadConfig

Functions

func Dir

func Dir() string

Dir returns the telemetry directory.

func MaybeChild

func MaybeChild(config Config)

MaybeChild executes the telemetry child logic if the calling program is the telemetry child process, and does nothing otherwise. It is meant to be called as the first thing in a program that uses telemetry.Start but cannot call telemetry.Start immediately when it starts.

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.