Add usage reporter to track feature flags

CHANGELOG.md

@@ -36,6 +36,9 @@ Main (unreleased)
 
 - Introduce ebpf exporter v2 integration. (@tpaschalis)
 
+- Add ability to configure agent to report to grafana.com the usage of feature flags (@marctc)
+
+
 ### Enhancements
 
 - integrations-next: Integrations using autoscrape will now autoscrape metrics

cmd/agent/entrypoint.go

@@ -17,6 +17,7 @@ import (
 	"github.com/grafana/agent/pkg/metrics/instance"
 	"github.com/grafana/agent/pkg/server"
 	"github.com/grafana/agent/pkg/traces"
+	"github.com/grafana/agent/pkg/usagestats"
 	"github.com/oklog/run"
 	"google.golang.org/grpc"
 	"gopkg.in/yaml.v2"
@@ -42,6 +43,7 @@ type Entrypoint struct {
 	lokiLogs     *logs.Logs
 	tempoTraces  *traces.Traces
 	integrations config.Integrations
+	reporter     *usagestats.Reporter
 
 	reloadListener net.Listener
 	reloadServer   *http.Server
@@ -84,11 +86,17 @@ func NewEntrypoint(logger *server.Logger, cfg *config.Config, reloader Reloader)
 	if err != nil {
 		return nil, err
 	}
+
 	ep.integrations, err = config.NewIntegrations(logger, &cfg.Integrations, integrationGlobals)
 	if err != nil {
 		return nil, err
 	}
 
+	ep.reporter, err = usagestats.NewReporter(logger, cfg)
+	if err != nil {
+		return nil, err
+	}
+
 	ep.wire(ep.srv.HTTP, ep.srv.GRPC)
 
 	// Mostly everything should be up to date except for the server, which hasn't
@@ -258,6 +266,7 @@ func (ep *Entrypoint) Stop() {
 	ep.mut.Lock()
 	defer ep.mut.Unlock()
 
+	ep.reporter.Service.StopAsync()
 	ep.integrations.Stop()
 	ep.lokiLogs.Stop()
 	ep.promMetrics.Stop()

docs/user/configuration/flags.md

@@ -32,6 +32,11 @@ Valid feature names are:
 * `dynamic-config`: Enable support for [dynamic configuration]({{< relref "./dynamic-config" >}})
 * `extra-scrape-metrics`: When enabled, additional time series  are exposed for each metrics instance scrape. See [Extra scrape metrics](https://prometheus.io/docs/prometheus/latest/feature_flags/#extra-scrape-metrics).
 
+### Report usage of feature flags
+
+Grafana Agent provides the flag `-usage-report` to report the usage of feature flags to grafana.com.
+This helps to understand which enabled features are being used of your running Agent instance (all data sent is anonymous).
+
 ## Configuration file
 
 * `-config.file`: Path to the configuration file to load. May be an HTTP(s) URL when the `remote-configs` feature is enabled

pkg/config/config.go

@@ -55,6 +55,7 @@ var DefaultConfig = Config{
 	Metrics:               metrics.DefaultConfig,
 	Integrations:          DefaultVersionedIntegrations,
 	EnableConfigEndpoints: false,
+	EnableUsageReport:     false,
 }
 
 // Config contains underlying configurations for the agent
@@ -74,6 +75,10 @@ type Config struct {
 
 	// Toggle for config endpoint(s)
 	EnableConfigEndpoints bool `yaml:"-"`
+
+	// Report enabled features options
+	EnableUsageReport bool     `yaml:"-"`
+	EnabledFeatures   []string `yaml:"-"`
 }
 
 // UnmarshalYAML implements yaml.Unmarshaler.
@@ -334,7 +339,6 @@ func Load(fs *flag.FlagSet, args []string) (*Config, error) {
 			} else if expandArgs {
 				return fmt.Errorf("-config.expand-env can not be used with file type %s", fileTypeDynamic)
 			}
-
 			return LoadDynamicConfiguration(path, expandArgs, c)
 		default:
 			return fmt.Errorf("unknown file type %q. accepted values: %s", fileType, strings.Join(fileTypes, ", "))
@@ -354,13 +358,16 @@ func load(fs *flag.FlagSet, args []string, loader loaderFunc) (*Config, error) {
 		file            string
 		fileType        string
 		configExpandEnv bool
+		usageStats      bool
 	)
 
 	fs.StringVar(&file, "config.file", "", "configuration file to load")
 	fs.StringVar(&fileType, "config.file.type", "yaml", fmt.Sprintf("Type of file pointed to by -config.file flag. Supported values: %s. %s requires dynamic-config and integrations-next features to be enabled.", strings.Join(fileTypes, ", "), fileTypeDynamic))
 	fs.BoolVar(&printVersion, "version", false, "Print this build's version information")
 	fs.BoolVar(&configExpandEnv, "config.expand-env", false, "Expands ${var} in config according to the values of the environment variables.")
+	fs.BoolVar(&usageStats, "usage-report", false, "When enabled sends usage info of enabled feature flags to Grafana")
 	cfg.RegisterFlags(fs)
+
 	features.Register(fs, allFeatures)
 
 	if err := fs.Parse(args); err != nil {
@@ -399,6 +406,11 @@ func load(fs *flag.FlagSet, args []string, loader loaderFunc) (*Config, error) {
 		cfg.Metrics.Global.ExtraMetrics = true
 	}
 
+	if usageStats {
+		cfg.EnableUsageReport = true
+		cfg.EnabledFeatures = features.GetAllEnabled(fs, allFeatures)
+	}
+
 	// Finally, apply defaults to config that wasn't specified by file or flag
 	if err := cfg.Validate(fs); err != nil {
 		return nil, fmt.Errorf("error in config file: %w", err)

pkg/config/features/features.go

@@ -41,7 +41,7 @@ func normalize(f Feature) Feature {
 	return Feature(strings.ToLower(string(f)))
 }
 
-// Enabled retruns true if a feature is enabled. Enable will panic if fs has
+// Enabled returns true if a feature is enabled. Enable will panic if fs has
 // not been passed to Register or name is an unknown feature.
 func Enabled(fs *flag.FlagSet, name Feature) bool {
 	name = normalize(name)
@@ -113,6 +113,23 @@ func Validate(fs *flag.FlagSet, deps []Dependency) error {
 	return err
 }
 
+// GetAllEnabled returns the list of all enabled features
+func GetAllEnabled(fs *flag.FlagSet, ff []Feature) []string {
+	f := fs.Lookup(setFlagName)
+	if f == nil {
+		panic("feature flag not registered to fs")
+	}
+	s, ok := f.Value.(*set)
+	if !ok {
+		panic("registered feature flag not appropriate type")
+	}
+	var enabled []string
+	for feature := range s.enabled {
+		enabled = append(enabled, string(feature))
+	}
+	return enabled
+}
+
 // set implements flag.Value and holds the set of enabled features.
 // set should be provided to a flag.FlagSet with:
 //

pkg/usagestats/reporter.go

@@ -0,0 +1,174 @@
+package usagestats
+
+import (
+	"context"
+	"errors"
+	"io/ioutil"
+	"math"
+	"os"
+	"time"
+
+	"github.com/go-kit/log"
+	"github.com/go-kit/log/level"
+	"github.com/google/uuid"
+	"github.com/grafana/agent/pkg/config"
+	"github.com/grafana/dskit/backoff"
+	"github.com/grafana/dskit/multierror"
+	"github.com/grafana/dskit/services"
+	"github.com/grafana/loki/pkg/util/build"
+)
+
+const (
+	// File name for the cluster seed file.
+	clusterSeedFileName = "cluster_seed.json"
+)
+
+var (
+	reportCheckInterval = time.Minute
+	reportInterval      = 1 * time.Hour
+)
+
+// Reporter holds the cluster information and sends report of usage
+type Reporter struct {
+	logger log.Logger
+	cfg    *config.Config
+	services.Service
+
+	cluster    *ClusterSeed
+	lastReport time.Time
+}
+
+// NewReporter creates a Reporter that will send periodically reports to grafana.com
+func NewReporter(logger log.Logger, cfg *config.Config) (*Reporter, error) {
+	r := &Reporter{
+		logger: logger,
+		cfg:    cfg,
+	}
+
+	if cfg.EnableUsageReport {
+		r.Service = services.NewBasicService(nil, r.start, nil)
+		err := r.Service.StartAsync(context.Background())
+		if err != nil {
+			return nil, err
+		}
+	} else {
+		// builds an empty service
+		r.Service = services.NewBasicService(nil, nil, nil)
+	}
+	return r, nil
+}
+
+func (rep *Reporter) init(ctx context.Context) error {
+	if fileExists(clusterSeedFileName) {
+		seed, err := rep.readSeedFile()
+		rep.cluster = seed
+		return err
+	} else {
+		rep.cluster = &ClusterSeed{
+			UID:               uuid.NewString(),
+			PrometheusVersion: build.GetVersion(),
+			CreatedAt:         time.Now(),
+		}
+		return rep.writeSeedFile(*rep.cluster)
+	}
+}
+
+func fileExists(path string) bool {
+	_, err := os.Stat(path)
+	return !errors.Is(err, os.ErrNotExist)
+}
+
+// readSeedFile reads the cluster seed file
+func (rep *Reporter) readSeedFile() (*ClusterSeed, error) {
+	data, err := ioutil.ReadFile(clusterSeedFileName)
+	if err != nil {
+		return nil, err
+	}
+	seed, err := JSONCodec.Decode(data)
+	if err != nil {
+		return nil, err
+	}
+	return seed.(*ClusterSeed), nil
+}
+
+// writeSeedFile writes the cluster seed file
+func (rep *Reporter) writeSeedFile(seed ClusterSeed) error {
+	data, err := JSONCodec.Encode(seed)
+	if err != nil {
+		return err
+	}
+	return ioutil.WriteFile(clusterSeedFileName, data, 0644)
+}
+
+// start inits the reporter seed and start sending report for every interval
+func (rep *Reporter) start(ctx context.Context) error {
+	level.Info(rep.logger).Log("msg", "running usage stats reporter")
+	err := rep.init(ctx)
+	if err != nil {
+		level.Info(rep.logger).Log("msg", "failed to init seed", "err", err)
+		return err
+	}
+
+	// check every minute if we should report.
+	ticker := time.NewTicker(reportCheckInterval)
+	defer ticker.Stop()
+
+	// find  when to send the next report.
+	next := nextReport(reportInterval, rep.cluster.CreatedAt, time.Now())
+	if rep.lastReport.IsZero() {
+		// if we never reported assumed it was the last interval.
+		rep.lastReport = next.Add(-reportInterval)
+	}
+	for {
+		select {
+		case <-ticker.C:
+			now := time.Now()
+			if !next.Equal(now) && now.Sub(rep.lastReport) < reportInterval {
+				continue
+			}
+			level.Info(rep.logger).Log("msg", "reporting cluster stats", "date", time.Now())
+			if err := rep.reportUsage(ctx, next); err != nil {
+				level.Info(rep.logger).Log("msg", "failed to report usage", "err", err)
+				continue
+			}
+			rep.lastReport = next
+			next = next.Add(reportInterval)
+		case <-ctx.Done():
+			return ctx.Err()
+		}
+	}
+}
+
+// reportUsage reports the usage to grafana.com.
+func (rep *Reporter) reportUsage(ctx context.Context, interval time.Time) error {
+	backoff := backoff.New(ctx, backoff.Config{
+		MinBackoff: time.Second,
+		MaxBackoff: 30 * time.Second,
+		MaxRetries: 5,
+	})
+	var errs multierror.MultiError
+	for backoff.Ongoing() {
+		if err := sendReport(ctx, rep.cluster, interval, rep.getMetrics()); err != nil {
+			level.Info(rep.logger).Log("msg", "failed to send usage report", "retries", backoff.NumRetries(), "err", err)
+			errs.Add(err)
+			backoff.Wait()
+			continue
+		}
+		level.Info(rep.logger).Log("msg", "usage report sent with success")
+		return nil
+	}
+	return errs.Err()
+}
+
+func (rep *Reporter) getMetrics() map[string]interface{} {
+	return map[string]interface{}{
+		"enabled-features": rep.cfg.EnabledFeatures,
+	}
+}
+
+// nextReport compute the next report time based on the interval.
+// The interval is based off the creation of the cluster seed to avoid all cluster reporting at the same time.
+func nextReport(interval time.Duration, createdAt, now time.Time) time.Time {
+	// createdAt * (x * interval ) >= now
+	return createdAt.Add(time.Duration(math.Ceil(float64(now.Sub(createdAt))/float64(interval))) * interval)
+}