From 625713dd723983d243c9e2902866c0773dd12a8b Mon Sep 17 00:00:00 2001 From: Frank Schroeder Date: Wed, 18 Oct 2017 12:19:54 +0200 Subject: [PATCH] config: document telemetry options --- agent/config/runtime.go | 183 +++++++++++++++++++++++++++++++++++----- 1 file changed, 162 insertions(+), 21 deletions(-) diff --git a/agent/config/runtime.go b/agent/config/runtime.go index e3ef7ad2b7..25b89c44ee 100644 --- a/agent/config/runtime.go +++ b/agent/config/runtime.go @@ -83,28 +83,169 @@ type RuntimeConfig struct { HTTPBlockEndpoints []string HTTPResponseHeaders map[string]string - TelemetryCirconusAPIApp string - TelemetryCirconusAPIToken string - TelemetryCirconusAPIURL string - TelemetryCirconusBrokerID string - TelemetryCirconusBrokerSelectTag string - TelemetryCirconusCheckDisplayName string + // TelemetryCirconus*: see https://github.com/circonus-labs/circonus-gometrics + // for more details on the various configuration options. + // Valid configuration combinations: + // - CirconusAPIToken + // metric management enabled (search for existing check or create a new one) + // - 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 - TelemetryCirconusCheckSearchTag string - TelemetryCirconusCheckTags string - TelemetryCirconusSubmissionInterval string - TelemetryCirconusSubmissionURL string - TelemetryDisableHostname bool - TelemetryDogstatsdAddr string - TelemetryDogstatsdTags []string - TelemetryFilterDefault bool - TelemetryAllowedPrefixes []string - TelemetryBlockedPrefixes []string - TelemetryMetricsPrefix string - TelemetryStatsdAddr string - TelemetryStatsiteAddr string + + // TelemetryCirconusCheckID is the check id (not check bundle id) from a previously created + // HTTPTRAP check. The numeric portion of the check._cid field. + // Default: none + // + // hcl: telemetry { circonus_check_id = string } + TelemetryCirconusCheckID string + + // TelemetryCirconusCheckInstanceID serves to uniquely identify the metrics coming from this "instance". + // It can be used to maintain metric continuity with transient or ephemeral instances as + // they move around within an infrastructure. + // Default: hostname:app + // + // hcl: telemetry { circonus_check_instance_id = 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{"+", "+", ...} } + 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{"-", "-", ...} } + 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