Documentation
¶
Overview ¶
The chartconfig package defines the ChartConfig type, representing telemetry chart configuration, as well as utilities for parsing and validating this configuration.
Chart configuration defines the set of aggregations active on the telemetry server, and are used to derive which data needs to be uploaded by users. See the original blog post for more details:
https://research.swtch.com/telemetry-design#configuration
The record format defined in this package differs slightly from that of the blog post. This format is still experimental, and subject to change.
Configuration records consist of fields, comments, and whitespace. A field is defined by a line starting with a valid key, followed immediately by ":", and then a textual value, which cannot include the comment separator '#'.
Comments start with '#', and extend to the end of the line.
The following keys are supported. Any entry not marked as (optional) must be provided.
- title: the chart title.
- description: (optional) a longer description of the chart.
- issue: a go issue tracker URL proposing the chart configuration. Multiple issues may be provided by including additional 'issue:' lines. All proposals must be in the 'accepted' state.
- type: the chart type: currently only partition, histogram, and stack are supported.
- program: the package path of the program for which this chart applies.
- version: (optional) the first version for which this chart applies. Must be a valid semver value.
- counter: the primary counter this chart illustrates, including buckets for histogram and partition charts.
- depth: (optional) stack counters only; the maximum stack depth to collect
- error: (optional) the desired error rate for this chart, which determines collection rate
Multiple records are separated by "---" lines.
For example:
# This config defines an ordinary counter.
counter: gopls/editor:{emacs,vim,vscode,other} # TODO(golang/go#34567): add more editors
title: Editor Distribution
description: measure editor distribution for gopls users.
type: partition
issue: https://go.dev/issue/12345
program: golang.org/x/tools/gopls
version: v1.0.0
version: [v2.0.0, v2.3.4]
version: [v3.0.0, ]
---
# This config defines a stack counter.
counter: gopls/bug
title: Gopls bug reports.
description: Stacks of bugs encountered on the gopls server.
issue: https://go.dev/12345
issue: https://go.dev/23456 # increase stack depth
type: stack
program: golang.org/x/tools/gopls
depth: 10
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Validate ¶
func Validate(cfg ChartConfig) error
Validate checks that a ChartConfig is complete and coherent, returning an error describing all problems encountered, or nil.
Types ¶
type ChartConfig ¶
type ChartConfig struct {
Title string
Description string
Issue []string
Type string
Program string
Counter string
Depth int
Error float64 // TODO(rfindley) is Error still useful?
Version string
}
A ChartConfig defines the configuration for a single chart/collection on the telemetry server.
See the package documentation for field definitions.
func Parse ¶
func Parse(data []byte) ([]ChartConfig, error)
Parse parses ChartConfig records from the provided raw data, returning an error if the config has invalid syntax. See the package documentation for a description of the record syntax.
Even with correct syntax, the resulting chart config may not meet all the requirements described in the package doc. Call Validate to check whether the config data is coherent.
Source Files