telemetry.go

     1  // Copyright 2024 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  //go:build !cmd_go_bootstrap && !compiler_bootstrap
     6  
     7  // Package telemetry is a shim package around the golang.org/x/telemetry
     8  // and golang.org/x/telemetry/counter packages that has code build tagged
     9  // out for cmd_go_bootstrap so that the bootstrap Go command does not
    10  // depend on net (which is a dependency of golang.org/x/telemetry/counter
    11  // on Windows).
    12  package telemetry
    13  
    14  import (
    15  	"flag"
    16  	"os"
    17  
    18  	"golang.org/x/telemetry"
    19  	"golang.org/x/telemetry/counter"
    20  )
    21  
    22  // Start opens the counter files for writing if telemetry is supported
    23  // on the current platform (and does nothing otherwise).
    24  func Start() {
    25  	telemetry.Start(telemetry.Config{
    26  		TelemetryDir: os.Getenv("TEST_TELEMETRY_DIR"),
    27  	})
    28  }
    29  
    30  // StartWithUpload opens the counter files for writing if telemetry
    31  // is supported on the current platform and also enables a once a day
    32  // check to see if the weekly reports are ready to be uploaded.
    33  // It should only be called by cmd/go
    34  func StartWithUpload() {
    35  	telemetry.Start(telemetry.Config{
    36  		Upload:       true,
    37  		TelemetryDir: os.Getenv("TEST_TELEMETRY_DIR"),
    38  	})
    39  }
    40  
    41  // Inc increments the counter with the given name.
    42  func Inc(name string) {
    43  	counter.Inc(name)
    44  }
    45  
    46  // NewCounter returns a counter with the given name.
    47  func NewCounter(name string) *counter.Counter {
    48  	return counter.New(name)
    49  }
    50  
    51  // NewStack returns a new stack counter with the given name and depth.
    52  func NewStackCounter(name string, depth int) *counter.StackCounter {
    53  	return counter.NewStack(name, depth)
    54  }
    55  
    56  // CountFlags creates a counter for every flag that is set
    57  // and increments the counter. The name of the counter is
    58  // the concatenation of prefix and the flag name.
    59  func CountFlags(prefix string, flagSet flag.FlagSet) {
    60  	counter.CountFlags(prefix, flagSet)
    61  }
    62  
    63  // CountFlagValue creates a counter for the flag value
    64  // if it is set and increments the counter. The name of the
    65  // counter is the concatenation of prefix, the flagName, ":",
    66  // and value.String() for the flag's value.
    67  func CountFlagValue(prefix string, flagSet flag.FlagSet, flagName string) {
    68  	// TODO(matloob): Maybe pass in a list of flagNames if we end up counting
    69  	// values for more than one?
    70  	// TODO(matloob): Add this to x/telemetry?
    71  	flagSet.Visit(func(f *flag.Flag) {
    72  		if f.Name == flagName {
    73  			counter.New(prefix + f.Name + ":" + f.Value.String()).Inc()
    74  		}
    75  	})
    76  }
    77  
    78  // Mode returns the current telemetry mode.
    79  //
    80  // The telemetry mode is a global value that controls both the local collection
    81  // and uploading of telemetry data. Possible mode values are:
    82  //   - "on":    both collection and uploading is enabled
    83  //   - "local": collection is enabled, but uploading is disabled
    84  //   - "off":   both collection and uploading are disabled
    85  //
    86  // When mode is "on", or "local", telemetry data is written to the local file
    87  // system and may be inspected with the [gotelemetry] command.
    88  //
    89  // If an error occurs while reading the telemetry mode from the file system,
    90  // Mode returns the default value "local".
    91  //
    92  // [gotelemetry]: https://pkg.go.dev/golang.org/x/telemetry/cmd/gotelemetry
    93  func Mode() string {
    94  	return telemetry.Mode()
    95  }
    96  
    97  // SetMode sets the global telemetry mode to the given value.
    98  //
    99  // See the documentation of [Mode] for a description of the supported mode
   100  // values.
   101  //
   102  // An error is returned if the provided mode value is invalid, or if an error
   103  // occurs while persisting the mode value to the file system.
   104  func SetMode(mode string) error {
   105  	return telemetry.SetMode(mode)
   106  }
   107  
   108  // Dir returns the telemetry directory.
   109  func Dir() string {
   110  	return telemetry.Dir()
   111  }
   112
View as plain text