cockroach: Index | Files

package telemetry

import ""

Package telemetry contains helpers for capturing diagnostics information.

Telemetry is captured and shared with cockroach labs if enabled to help the team prioritize new and existing features or configurations. The docs include more information about this telemetry, what it includes and how to configure it.

When trying to measure the usage of a given feature, the existing reporting of "scrubbed" queries -- showing the structure but not the values -- can serve as a means to measure eg. how many clusters use BACKUP or window functions, etc. However many features cannot be easily measured just from these statements, either because they are cannot be reliably inferred from a scrubbed query or are simply not involved in a SQL statement execution at all.

For such features we also have light-weight `telemetry.Count("some.feature")` to track their usage. These increment in-memory counts that are then included with existing diagnostics reporting if enabled. Some notes on using these:

  - "some.feature" should always be a literal string constant -- it must not
    include any user-submitted data.
  - Contention-sensitive, high-volume callers should use an initial `GetCounter`
		to get a Counter they can then `Inc` repeatedly instead to avoid contention
		and map lookup over around the name resolution on each increment.
	-	When naming a counter, by convention we use dot-separated, dashed names, eg.


Package Files

doc.go features.go


const (
    // Quantized returns counts quantized to order of magnitude.
    Quantized QuantizeCounts = true
    // Raw returns the raw, unquantized counter values.
    Raw QuantizeCounts = false
    // ResetCounts resets the counter to zero after fetching its value.
    ResetCounts ResetCounters = true
    // ReadOnly leaves the counter value unchanged when reading it.
    ReadOnly ResetCounters = false

func Bucket10 Uses

func Bucket10(num int64) int64

Bucket10 buckets a number by order of magnitude base 10, eg 637 -> 100. This can be used in telemetry to get ballpark ideas of how users use a given feature, such as file sizes, qps, etc, without being as revealing as the raw numbers. The numbers 0-10 are reported unchanged.

func Count Uses

func Count(feature string)

Count retrieves and increments the usage counter for the passed feature. High-volume callers may want to instead use `GetCounter` and hold on to the returned Counter between calls to Inc, to avoid contention in the registry.

func CountBucketed Uses

func CountBucketed(prefix string, value int64)

CountBucketed counts the feature identified by prefix and the value, using the bucketed value to pick a feature bucket to increment, e.g. a prefix of "" and value of 632 would be counted as "".

func GetFeatureCounts Uses

func GetFeatureCounts(quantize QuantizeCounts, reset ResetCounters) map[string]int32

GetFeatureCounts returns the current feature usage counts.

It optionally quantizes quantizes the returned counts to just order of magnitude using the `Bucket10` helper, and optionally resets the counters to zero i.e. if flushing accumulated counts during a report.

func GetRawFeatureCounts Uses

func GetRawFeatureCounts() map[string]int32

GetRawFeatureCounts returns current raw, un-quanitzed feature counter values.

func Inc Uses

func Inc(c Counter)

Inc increments the counter.

func Read Uses

func Read(c Counter) int32

Read reads the current value of the counter.

func RecordError Uses

func RecordError(err error)

RecordError takes an error and increments the corresponding count for its error code, and, if it is an unimplemented or internal error, the count for that feature or the internal error's shortened stack trace.

type Counter Uses

type Counter *int32

Counter represents the usage counter for a given 'feature'.

func GetCounter Uses

func GetCounter(feature string) Counter

GetCounter returns a counter from the global registry.

func GetCounterOnce Uses

func GetCounterOnce(feature string) Counter

GetCounterOnce returns a counter from the global registry, and asserts it didn't exist previously.

type CounterWithMetric Uses

type CounterWithMetric struct {
    // contains filtered or unexported fields

CounterWithMetric combines a telemetry and a metrics counter.

func NewCounterWithMetric Uses

func NewCounterWithMetric(metadata metric.Metadata) CounterWithMetric

NewCounterWithMetric creates a CounterWithMetric.

func (CounterWithMetric) GetHelp Uses

func (c CounterWithMetric) GetHelp() string

GetHelp implements metric.Iterable

func (CounterWithMetric) GetMeasurement Uses

func (c CounterWithMetric) GetMeasurement() string

GetMeasurement implements metric.Iterable

func (CounterWithMetric) GetMetadata Uses

func (c CounterWithMetric) GetMetadata() metric.Metadata

GetMetadata implements metric.Iterable

func (CounterWithMetric) GetName Uses

func (c CounterWithMetric) GetName() string

GetName implements metric.Iterable

func (CounterWithMetric) GetUnit Uses

func (c CounterWithMetric) GetUnit() metric.Unit

GetUnit implements metric.Iterable

func (CounterWithMetric) Inc Uses

func (c CounterWithMetric) Inc()

Inc increments both counters.

func (CounterWithMetric) Inspect Uses

func (c CounterWithMetric) Inspect(f func(interface{}))

Inspect implements metric.Iterable

type QuantizeCounts Uses

type QuantizeCounts bool

QuantizeCounts controls if counts are quantized when fetched.

type ResetCounters Uses

type ResetCounters bool

ResetCounters controls if counts are reset when fetched.

Package telemetry imports 8 packages (graph) and is imported by 59 packages. Updated 2020-09-02. Refresh now. Tools for package owners.