Documentation
¶
Overview ¶
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. `feature-area.specific-feature`.
Index ¶
- Constants
- func Bucket10(num int64) int64
- func Count(feature string)
- func CountBucketed(prefix string, value int64)
- func GetFeatureCounts(quantize QuantizeCounts, reset ResetCounters) map[string]int32
- func GetRawFeatureCounts() map[string]int32
- func Inc(c Counter)
- func Read(c Counter) int32
- func RecordError(err error)
- type Counter
- type CounterWithMetric
- func (c CounterWithMetric) GetHelp() string
- func (c CounterWithMetric) GetMeasurement() string
- func (c CounterWithMetric) GetMetadata() metric.Metadata
- func (c CounterWithMetric) GetName() string
- func (c CounterWithMetric) GetUnit() metric.Unit
- func (c CounterWithMetric) Inc()
- func (c CounterWithMetric) Inspect(f func(interface{}))
- type QuantizeCounts
- type ResetCounters
Constants ¶
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 )
Variables ¶
This section is empty.
Functions ¶
func Bucket10 ¶
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 ¶
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 ¶
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 "foo.bar" and value of 632 would be counted as "foo.bar.100".
func GetFeatureCounts ¶
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 ¶
GetRawFeatureCounts returns current raw, un-quanitzed feature counter values.
func RecordError ¶
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.
Types ¶
type Counter ¶
type Counter *int32
Counter represents the usage counter for a given 'feature'.
func GetCounter ¶
GetCounter returns a counter from the global registry.
func GetCounterOnce ¶
GetCounterOnce returns a counter from the global registry, and asserts it didn't exist previously.
type CounterWithMetric ¶
type CounterWithMetric struct {
// contains filtered or unexported fields
}
CounterWithMetric combines a telemetry and a metrics counter.
func NewCounterWithMetric ¶
func NewCounterWithMetric(metadata metric.Metadata) CounterWithMetric
NewCounterWithMetric creates a CounterWithMetric.
func (CounterWithMetric) GetHelp ¶
func (c CounterWithMetric) GetHelp() string
GetHelp implements metric.Iterable
func (CounterWithMetric) GetMeasurement ¶
func (c CounterWithMetric) GetMeasurement() string
GetMeasurement implements metric.Iterable
func (CounterWithMetric) GetMetadata ¶
func (c CounterWithMetric) GetMetadata() metric.Metadata
GetMetadata implements metric.Iterable
func (CounterWithMetric) GetName ¶
func (c CounterWithMetric) GetName() string
GetName implements metric.Iterable
func (CounterWithMetric) GetUnit ¶
func (c CounterWithMetric) GetUnit() metric.Unit
GetUnit implements metric.Iterable
func (CounterWithMetric) Inspect ¶
func (c CounterWithMetric) Inspect(f func(interface{}))
Inspect implements metric.Iterable
type QuantizeCounts ¶
type QuantizeCounts bool
QuantizeCounts controls if counts are quantized when fetched.
type ResetCounters ¶
type ResetCounters bool
ResetCounters controls if counts are reset when fetched.
Source Files