config: document telemetry options

agent/config/runtime.go

@@ -83,28 +83,169 @@ type RuntimeConfig struct {
 	HTTPBlockEndpoints  []string
 	HTTPResponseHeaders map[string]string
 
-	TelemetryCirconusAPIApp                     string
+	// TelemetryCirconus*: see https://github.com/circonus-labs/circonus-gometrics
-	TelemetryCirconusAPIToken                   string
+	// for more details on the various configuration options.
-	TelemetryCirconusAPIURL                     string
+	// Valid configuration combinations:
-	TelemetryCirconusBrokerID                   string
+	//    - CirconusAPIToken
-	TelemetryCirconusBrokerSelectTag            string
+	//      metric management enabled (search for existing check or create a new one)
-	TelemetryCirconusCheckDisplayName           string
+	//    - CirconusSubmissionUrl
+	//      metric management disabled (use check with specified submission_url,
+	//      broker must be using a public SSL certificate)
+	//    - CirconusAPIToken + CirconusCheckSubmissionURL
+	//      metric management enabled (use check with specified submission_url)
+	//    - CirconusAPIToken + CirconusCheckID
+	//      metric management enabled (use check with specified id)
+
+	// TelemetryCirconusAPIApp is an app name associated with API token.
+	// Default: "consul"
+	//
+	// hcl: telemetry { circonus_api_app = string }
+	TelemetryCirconusAPIApp string
+
+	// TelemetryCirconusAPIToken is a valid API Token used to create/manage check. If provided,
+	// metric management is enabled.
+	// Default: none
+	//
+	// hcl: telemetry { circonous_api_token = string }
+	TelemetryCirconusAPIToken string
+
+	// TelemetryCirconusAPIURL is the base URL to use for contacting the Circonus API.
+	// Default: "https://api.circonus.com/v2"
+	//
+	// hcl: telemetry { circonus_api_url = string }
+	TelemetryCirconusAPIURL string
+
+	// TelemetryCirconusBrokerID is an explicit broker to use when creating a new check. The numeric portion
+	// of broker._cid. If metric management is enabled and neither a Submission URL nor Check ID
+	// is provided, an attempt will be made to search for an existing check using Instance ID and
+	// Search Tag. If one is not found, a new HTTPTRAP check will be created.
+	// Default: use Select Tag if provided, otherwise, a random Enterprise Broker associated
+	// with the specified API token or the default Circonus Broker.
+	// Default: none
+	//
+	// hcl: telemetry { circonus_broker_id = string }
+	TelemetryCirconusBrokerID string
+
+	// TelemetryCirconusBrokerSelectTag is a special tag which will be used to select a broker when
+	// a Broker ID is not provided. The best use of this is to as a hint for which broker
+	// should be used based on *where* this particular instance is running.
+	// (e.g. a specific geo location or datacenter, dc:sfo)
+	// Default: none
+	//
+	// hcl: telemetry { circonus_broker_select_tag = string }
+	TelemetryCirconusBrokerSelectTag string
+
+	// TelemetryCirconusCheckDisplayName is the name for the check which will be displayed in the Circonus UI.
+	// Default: value of CirconusCheckInstanceID
+	//
+	// hcl: telemetry { circonus_check_display_name = string }
+	TelemetryCirconusCheckDisplayName string
+
+	// TelemetryCirconusCheckForceMetricActivation will force enabling metrics, as they are encountered,
+	// if the metric already exists and is NOT active. If check management is enabled, the default
+	// behavior is to add new metrics as they are encoutered. If the metric already exists in the
+	// check, it will *NOT* be activated. This setting overrides that behavior.
+	// Default: "false"
+	//
+	// hcl: telemetry { circonus_check_metrics_activation = (true|false)
 	TelemetryCirconusCheckForceMetricActivation string
-	TelemetryCirconusCheckID                    string
+
-	TelemetryCirconusCheckInstanceID            string
+	// TelemetryCirconusCheckID is the check id (not check bundle id) from a previously created
-	TelemetryCirconusCheckSearchTag             string
+	// HTTPTRAP check. The numeric portion of the check._cid field.
-	TelemetryCirconusCheckTags                  string
+	// Default: none
-	TelemetryCirconusSubmissionInterval         string
+	//
-	TelemetryCirconusSubmissionURL              string
+	// hcl: telemetry { circonus_check_id = string }
-	TelemetryDisableHostname                    bool
+	TelemetryCirconusCheckID string
-	TelemetryDogstatsdAddr                      string
+
-	TelemetryDogstatsdTags                      []string
+	// TelemetryCirconusCheckInstanceID serves to uniquely identify the metrics coming from this "instance".
-	TelemetryFilterDefault                      bool
+	// It can be used to maintain metric continuity with transient or ephemeral instances as
-	TelemetryAllowedPrefixes                    []string
+	// they move around within an infrastructure.
-	TelemetryBlockedPrefixes                    []string
+	// Default: hostname:app
-	TelemetryMetricsPrefix                      string
+	//
-	TelemetryStatsdAddr                         string
+	// hcl: telemetry { circonus_check_instance_id = string }
-	TelemetryStatsiteAddr                       string
+	TelemetryCirconusCheckInstanceID string
+
+	// TelemetryCirconusCheckSearchTag is a special tag which, when coupled with the instance id, helps to
+	// narrow down the search results when neither a Submission URL or Check ID is provided.
+	// Default: service:app (e.g. service:consul)
+	//
+	// hcl: telemetry { circonus_check_search_tag = string }
+	TelemetryCirconusCheckSearchTag string
+
+	// TelemetryCirconusCheckSearchTag is a special tag which, when coupled with the instance id, helps to
+	// narrow down the search results when neither a Submission URL or Check ID is provided.
+	// Default: service:app (e.g. service:consul)
+	//
+	// hcl: telemetry { circonus_check_tags = string }
+	TelemetryCirconusCheckTags string
+
+	// TelemetryCirconusSubmissionInterval is the interval at which metrics are submitted to Circonus.
+	// Default: 10s
+	//
+	// hcl: telemetry { circonus_submission_interval = "duration" }
+	TelemetryCirconusSubmissionInterval string
+
+	// TelemetryCirconusCheckSubmissionURL is the check.config.submission_url field from a
+	// previously created HTTPTRAP check.
+	// Default: none
+	//
+	// hcl: telemetry { circonus_submission_url = string }
+	TelemetryCirconusSubmissionURL string
+
+	// DisableHostname will disable hostname prefixing for all metrics.
+	//
+	// hcl: telemetry { disable_hostname = (true|false)
+	TelemetryDisableHostname bool
+
+	// TelemetryDogStatsdAddr is the address of a dogstatsd instance. If provided,
+	// metrics will be sent to that instance
+	//
+	// hcl: telemetry { dogstatsd_addr = string }
+	TelemetryDogstatsdAddr string
+
+	// TelemetryDogStatsdTags are the global tags that should be sent with each packet to dogstatsd
+	// It is a list of strings, where each string looks like "my_tag_name:my_tag_value"
+	//
+	// hcl: telemetry { dogstatsd_tags = []string }
+	TelemetryDogstatsdTags []string
+
+	// TelemetryFilterDefault is the default for whether to allow a metric that's not
+	// covered by the filter.
+	//
+	// hcl: telemetry { filter_default = (true|false) }
+	TelemetryFilterDefault bool
+
+	// TelemetryAllowedPrefixes is a list of filter rules to apply for allowing metrics
+	// by prefix. Use the 'prefix_filter' option and prefix rules with '+' to be
+	// included.
+	//
+	// hcl: telemetry { prefix_filter = []string{"+<expr>", "+<expr>", ...} }
+	TelemetryAllowedPrefixes []string
+
+	// TelemetryBlockedPrefixes is a list of filter rules to apply for blocking metrics
+	// by prefix. Use the 'prefix_filter' option and prefix rules with '-' to be
+	// excluded.
+	//
+	// hcl: telemetry { prefix_filter = []string{"-<expr>", "-<expr>", ...} }
+	TelemetryBlockedPrefixes []string
+
+	// TelemetryMetricsPrefix is the prefix used to write stats values to.
+	// Default: "consul."
+	//
+	// hcl: telemetry { metrics_prefix = string }
+	TelemetryMetricsPrefix string
+
+	// TelemetryStatsdAddr is the address of a statsd instance. If provided,
+	// metrics will be sent to that instance.
+	//
+	// hcl: telemetry { statsd_addr = string }
+	TelemetryStatsdAddr string
+
+	// TelemetryStatsiteAddr is the address of a statsite instance. If provided,
+	// metrics will be streamed to that instance.
+	//
+	// hcl: telemetry { statsite_addr = string }
+	TelemetryStatsiteAddr string
 
 	// Datacenter and NodeName are exposed via /v1/agent/self from here and
 	// used in lots of places like CLI commands. Treat this as an interface