// Copyright 2023 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

// The chartconfig package defines configuration that specifies both the data
// that is uploaded to telemetry.go.dev, and the resulting charts that are
// rendered. Each record in [config.txt] defines the collection and aggregation
// of a group of related counters, in the custom format specified below. We
// refer to these records as "chart configs" (and represent them with the
// [ChartConfig] type), based on the principle that telemetry collection should
// be derived from views of the data that we want to see. For basic counters,
// this is indeed the case: chart configs correspond 1:1 with charts on
// telemetry.go.dev. For stack counters, we use the same format, but have no
// way to render them graphically.
//
// The format itself is based on the original telemetry blog post, though it
// has been modified slightly and may be subject to further change:
//
// https://research.swtch.com/telemetry-design#configuration
//
// # Chart records
//
// Chart config 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 for the record to pass validation.
//
//   - counter: an expression for the group of counters this chart aggregates.
//     More detail on the syntax of this expression is provided below.
//   - 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.
//   - type: the chart type. Currently only partition and stack are supported.
//   - program: the package path of the program for which this chart applies.
//   - module: the module path of the program for version lookup.
//   - version: (optional) the first program version for which this chart
//     applies. Must be a valid semver value. If not provided, the chart
//     applies to all versions.
//   - 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.
//
// # Counter expressions
//
// Each record must specify in its 'counter' field either a single counter, or
// a group of related counters.
//
// As described in the [counter documentation], we decompose counter names into
// two parts, separated by a ':'. The part before the ':' is referred to as the
// 'chart name', and the part after the ':' is the 'bucket'. So in the example
// gopls/gotoolchain:auto, gopls/gotoolchain is the chart name, and auto is the
// bucket name.
//
// In order to be grouped into a single chart, counters must share a common
// chart name, and so we specify the group of counters using the following
// compact syntax:
//
//	chartname:{bucket1,bucket2,bucket3}
//
// Which expands to the following group of counters:
//
//	chartname:bucket1
//	chartname:bucket2
//	chartname:bucket3
//
// # Chart types
//
// There are two supported chart types for the 'type' field:
//
//   - A 'partition' chart is a bar chart with one bar for each related counter.
//     The value of the bar is the aggregation of all counts for the program
//     over the applicable time period.
//   - A 'stack' chart is not a real chart. It just means that we want to
//     collect the given stack counter or group of stack counters.
//
// # Example
//
// Here is a fully worked example, including both partition and stack records:
//
//	# 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
//	module: golang.org/x/tools/gopls
//	version: v1.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
//	module: golang.org/x/tools/gopls
//	depth: 10
//
// [config.txt]: https://go.googlesource.com/telemetry/+/refs/heads/master/internal/chartconfig/config.txt
// [counter documentation]: https://go.dev/doc/telemetry#counters
package chartconfig

// A ChartConfig defines the configuration for a single chart/collection on the
// telemetry server.
//
// See the package documentation for field definitions.
type ChartConfig struct {
	Title       string
	Description string
	Issue       []string
	Type        string
	Program     string
	Module      string
	Counter     string
	Depth       int
	Error       float64 // TODO(rfindley) is Error still useful?
	Version     string
}