func Dir() string
Dir returns the telemetry directory.
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() 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:
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(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.
Config controls the behavior of Start.
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
}
type CounterConfig = telemetry.CounterConfig
type ProgramConfig = telemetry.ProgramConfig
type ProgramReport = telemetry.ProgramReport
A Report is what's uploaded (or saved locally)
type Report = telemetry.Report
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.
type StartResult struct {
// contains filtered or unexported fields
}
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 (res *StartResult) Wait()
Wait waits for the completion of all work initiated by Start.
An UploadConfig controls what data is uploaded.
type UploadConfig = telemetry.UploadConfig
| Name | Synopsis |
|---|---|
| .. | |