metriton

Documentation

Overview

Package metriton implements submitting telemetry data to the Metriton database.

Metriton replaced Scout, and was originally going to have its own telemetry API and a Scout-compatibility endpoint during the migration. But now the Scout-compatible API is the only thing we use.

See also: The old scout.py package <https://pypi.org/project/scout.py/> / <https://github.com/datawire/scout.py>.

Things that are in scout.py, but are intentionally left of this package:

• automatically setting the HTTP client user-agent string
• an InstallIDFromConfigMap getter

Index

• Variables
• func InstallIDFromFilesystem(reporter *Reporter) (string, error)
• func IsDisabledByUser() bool
• func StaticInstallID(id string) func(*Reporter) (string, error)
• type AppInfo
• type Notice
• type Report
  • func (r Report) Send(ctx context.Context, httpClient *http.Client, endpoint string) (*Response, error)
• type Reporter
  • func (r *Reporter) InstallID() string
  • func (r *Reporter) Report(ctx context.Context, metadata map[string]interface{}) (*Response, error)
• type Response

Variables

var (
	// The endpoint you should use by default
	DefaultEndpoint = "https://metriton.datawire.io/scout"
	// Use BetaEndpoint for testing purposes without polluting production data
	BetaEndpoint = "https://metriton.datawire.io/beta/scout"
	// ScoutPyEndpoint is the default endpoint used by scout.py; it obeys the
	// SCOUT_HOST and SCOUT_HTTPS environment variables.  I'm not sure when you should
	// use it instead of DefaultEndpoint, but I'm putting it in Go so that I never
	// have to look at scout.py again.
	ScoutPyEndpoint = endpointFromEnv()
)

Functions

func InstallIDFromFilesystem

func InstallIDFromFilesystem(reporter *Reporter) (string, error)

InstallIDFromFilesystem is an install-ID-getter that tracks the install ID in the filesystem (à la `telepresence` or `edgectl`).

func IsDisabledByUser

func IsDisabledByUser() bool

IsDisabledByUser returns whether telemetry reporting is disabled by the user.

func StaticInstallID

func StaticInstallID(id string) func(*Reporter) (string, error)

StaticInstallID is returns an install-ID-getter that always returns a fixed install ID.

Types

type AppInfo

type AppInfo struct {
	Application   string   `json:"application"`
	LatestVersion string   `json:"latest_version"`
	Notices       []Notice `json:"notices"`
}

AppInfo is the information that Metriton knows about an application.

There isn't really an otherwise fixed schema for this; Metriton returns whatever it reads from f"s3://scout-datawire-io/{report.application}/app.json". However, looking at all of the existing app.json files, they all agree on the schema

type Notice

type Notice interface{}

Notice is a notice that should be displayed to the user.

I have no idea what the schema for Notice is, there are none currently, and reverse-engineering it from what diagd.py consumes isn't worth the effort at this time.

type Report

type Report struct {
	Application string                 `json:"application"` // (required) The name of the application reporting the event
	InstallID   string                 `json:"install_id"`  // (required) Application installation ID (usually a UUID, but technically an opaque string)
	Version     string                 `json:"version"`     // (required) Application version number
	Metadata    map[string]interface{} `json:"metadata"`    // (optional) Additional metadata about the application
}

Report is a telemetry report to submit to Metriton.

See: https://github.com/datawire/metriton/blob/master/metriton/scout/jsonschema.py

func (Report) Send

func (r Report) Send(ctx context.Context, httpClient *http.Client, endpoint string) (*Response, error)

Send the report to the given Metriton endpoint using the given httpClient.

The returned *Response may be nil even if there is no error, if Metriton has not yet been configured to know about the Report's `.Application`; i.e. a Response is only returned for known applications.

type Reporter

type Reporter struct {
	// Information about the application submitting telemetry.
	Application string
	Version     string
	// GetInstallID is a function, instead of a fixed 'InstallID' string, in order to
	// facilitate getting it lazily; and possibly updating the BaseMetadata based on
	// the journey to getting the install ID.  See StaticInstallID and
	// InstallIDFromFilesystem.
	GetInstallID func(*Reporter) (string, error)
	// BaseMetadata will be merged in to the data passed to each call to .Report().
	// If the data passed to .Report() and BaseMetadata have a key in common, the
	// value passed as an argument to .Report() wins.
	BaseMetadata map[string]interface{}

	// The HTTP client used to to submit the request; if this is nil, then
	// http.DefaultClient is used.
	Client *http.Client
	// The endpoint URL to submit to; if this is empty, then DefaultEndpoint is used.
	Endpoint string
	// contains filtered or unexported fields
}

Reporter is a client to

func (*Reporter) InstallID

func (r *Reporter) InstallID() string

func (*Reporter) Report

func (r *Reporter) Report(ctx context.Context, metadata map[string]interface{}) (*Response, error)

Report submits a telemetry report to Metriton. It is safe to call .Report() from different goroutines. It is NOT safe to mutate the public fields in the Reporter while .Report() is being called.

type Response

type Response struct {
	AppInfo

	// Only set for .Application=="aes"
	HardLimit bool `json:"hard_limit"`

	// Disable submitting any more telemetry for the remaining
	// lifetime of this process.
	//
	// This way, if we ever make another release that turns out to
	// effectively DDoS Metriton, we can adjust the Metriton
	// server's `api.py:handle_report()` to be able to tell the
	// offending processes to shut up.
	DisableScout bool `json:"disable_scout"`
}

Response is a response from Metriton, after submitting a Report to it.