Add more info about filters to docs and rename struct fields

Signed-off-by: Kyle Eckhart <kgeckhart@users.noreply.github.com>
prometheus-community · Jan 31, 2023 · 68f0b54 · 68f0b54
1 parent b6dd5f6
commit 68f0b54
Show file tree

Hide file tree

Showing 4 changed files with 37 additions and 16 deletions.
diff --git a/README.md b/README.md
@@ -71,12 +71,12 @@ If you are still using the legacy [Access scopes][access-scopes], the `https://w
 | --------------------------------- | -------- |---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `google.project-id`               | No       | GCloud SDK auto-discovery | Comma seperated list of Google Project IDs                                                                                                                                                        |
 | `monitoring.metrics-ingest-delay` | No       |                           | Offsets metric collection by a delay appropriate for each metric type, e.g. because bigquery metrics are slow to appear                                                                           |
-| `monitoring.metrics-type-prefixes` | Yes      |                           | Comma separated Google Stackdriver Monitoring Metric Type prefixes (see [example][metrics-prefix-example] and [available metrics][metrics-list])                                                  |
+| `monitoring.metrics-type-prefixes` | Yes      |                           | Comma separated Google Stackdriver Monitoring Metric Type prefixes (see [example](#example) and [available metrics][metrics-list]                                                                 |
 | `monitoring.metrics-interval`     | No       | `5m`                      | Metric's timestamp interval to request from the Google Stackdriver Monitoring Metrics API. Only the most recent data point is used                                                                |
 | `monitoring.metrics-offset`       | No       | `0s`                      | Offset (into the past) for the metric's timestamp interval to request from the Google Stackdriver Monitoring Metrics API, to handle latency in published metrics                                  |
-| `monitoring.filters`              | No       |                           | Formatted string to allow filtering on certain metrics type                                                                                                                                       |
+| `monitoring.filters`              | No       |                           | Additonal filters to be sent on the Monitoring API call. Add multiple filters by providing this parameter multiple times. See [monitoring.filters](#using-filters) for more info.                 |
 | `monitoring.aggregate-deltas`     | No       |                           | If enabled will treat all DELTA metrics as an in-memory counter instead of a gauge. Be sure to read [what to know about aggregating DELTA metrics](#what-to-know-about-aggregating-delta-metrics) |
-| `monitoring.aggregate-deltas-ttl` | No       | `30m`                     | How long should a delta metric continue to be exported and stored after GCP stops producing it. Read [slow moving metrics](#slow-moving-metrics) to understand the problem this attempts to solve                                                                                                         |
+| `monitoring.aggregate-deltas-ttl` | No       | `30m`                     | How long should a delta metric continue to be exported and stored after GCP stops producing it. Read [slow moving metrics](#slow-moving-metrics) to understand the problem this attempts to solve |
 | `web.listen-address`              | No       | `:9255`                   | Address to listen on for web interface and telemetry                                                                                                                                              |
 | `web.telemetry-path`              | No       | `/metrics`                | Path under which to expose Prometheus metrics                                                                                                                                                     |
 
@@ -119,13 +119,33 @@ stackdriver_exporter \
   --monitoring.metrics-type-prefixes "compute.googleapis.com/instance/cpu,compute.googleapis.com/instance/disk"
 ```
 
-Using extra filters:
+### Using filters
 
+The structure for a filter is `<targeted_metric_prefix>:<filter_query>`
+
+The `targeted_metric_prefix` is used to ensure the filter is only applied to the metric_prefix(es) where it makes sense. 
+It does not explicitly have to match a value from `metric_prefixes` but the `targeted_metric_prefix` must be at least a prefix to one or more `metric_prefixes`
+
+Example: \
+ metrics_prefixes = pubsub.googleapis.com/snapshot, pubsub.googleapis.com/subscription/num_undelivered_messages \
+ targeted_metric_prefix options would be \ 
+   pubsub.googleapis.com (apply to all defined prefixes) \
+   pubsub.googleapis.com/snapshot (apply to only snapshot metrics) \
+   pubsub.googleapis.com/subscription (apply to only subscription metrics) \
+   pubsub.googleapis.com/subscription/num_undelivered_messages (apply to only the specific subscription metric) \
+
+The `filter_query` will be applied to a final metrics API query when querying for metric data. You can read more about the metric API filter options in GCPs documentation https://cloud.google.com/monitoring/api/v3/filters
+
+The final query sent to the metrics API already includes filters for project and metric type. Each applicable `filter_query` will be appended to the query with an AND
+
+Full example
 ```
 stackdriver_exporter \
  --google.project-id=my-test-project \
  --monitoring.metrics-type-prefixes='pubsub.googleapis.com/subscription' \
- --monitoring.filters='pubsub.googleapis.com/subscription:resource.labels.subscription_id=monitoring.regex.full_match("us-west4.*my-team-subs.*")'
+ --monitoring.metrics-type-prefixes='compute.googleapis.com/instance/cpu' \
+ --monitoring.filters='pubsub.googleapis.com/subscription:resource.labels.subscription_id=monitoring.regex.full_match("us-west4.*my-team-subs.*")' \
+ --monitoring.filters='compute.googleapis.com/instance/cpu:resource.labels.instance=monitoring.regex.full_match("us-west4.*my-team-subs.*")' 
 ```
 
 ### Filtering enabled collectors
@@ -185,7 +205,6 @@ Apache License 2.0, see [LICENSE][license].
 [golang]: https://golang.org/
 [license]: https://github.com/prometheus-community/stackdriver_exporter/blob/master/LICENSE
 [manifest]: https://github.com/prometheus-community/stackdriver_exporter/blob/master/manifest.yml
-[metrics-prefix-example]: https://github.com/prometheus-community/stackdriver_exporter#example
 [metrics-list]: https://cloud.google.com/monitoring/api/metrics
 [metrics-name]: https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels
 [monitored-resources]: https://cloud.google.com/monitoring/api/resources

diff --git a/collectors/monitoring_collector.go b/collectors/monitoring_collector.go
@@ -33,8 +33,8 @@ import (
 const namespace = "stackdriver"
 
 type MetricFilter struct {
-	Prefix   string
-	Modifier string
+	TargetedMetricPrefix string
+	FilterQuery          string
 }
 
 type MonitoringCollector struct {
@@ -259,8 +259,8 @@ func (c *MonitoringCollector) reportMonitoringMetrics(ch chan<- prometheus.Metri
 				}
 
 				for _, ef := range c.metricsFilters {
-					if strings.Contains(metricDescriptor.Type, ef.Prefix) {
-						filter = fmt.Sprintf("%s AND (%s)", filter, ef.Modifier)
+					if strings.Contains(metricDescriptor.Type, ef.TargetedMetricPrefix) {
+						filter = fmt.Sprintf("%s AND (%s)", filter, ef.FilterQuery)
 					}
 				}
 

diff --git a/stackdriver_exporter.go b/stackdriver_exporter.go
@@ -104,7 +104,9 @@ var (
 	).Default("false").Bool()
 
 	monitoringMetricsExtraFilter = kingpin.Flag(
-		"monitoring.filters", "Filters. i.e: pubsub.googleapis.com/subscription:resource.labels.subscription_id=monitoring.regex.full_match(\"my-subs-prefix.*\")").Strings()
+		"monitoring.filters",
+		"Filters. i.e: pubsub.googleapis.com/subscription:resource.labels.subscription_id=monitoring.regex.full_match(\"my-subs-prefix.*\")",
+	).Strings()
 
 	monitoringMetricsAggregateDeltas = kingpin.Flag(
 		"monitoring.aggregate-deltas", "If enabled will treat all DELTA metrics as an in-memory counter instead of a gauge",
@@ -307,11 +309,11 @@ func main() {
 func parseMetricExtraFilters() []collectors.MetricFilter {
 	var extraFilters []collectors.MetricFilter
 	for _, ef := range *monitoringMetricsExtraFilter {
-		efPrefix, efModifier := utils.GetExtraFilterModifiers(ef, ":")
-		if efPrefix != "" {
+		targetedMetricPrefix, filterQuery := utils.SplitExtraFilter(ef, ":")
+		if targetedMetricPrefix != "" {
 			extraFilter := collectors.MetricFilter{
-				Prefix:   efPrefix,
-				Modifier: efModifier,
+				TargetedMetricPrefix: targetedMetricPrefix,
+				FilterQuery:          filterQuery,
 			}
 			extraFilters = append(extraFilters, extraFilter)
 		}

diff --git a/utils/utils.go b/utils/utils.go
@@ -39,7 +39,7 @@ func NormalizeMetricName(metricName string) string {
 	return strings.Join(normalizedMetricName, "_")
 }
 
-func GetExtraFilterModifiers(extraFilter string, separator string) (string, string) {
+func SplitExtraFilter(extraFilter string, separator string) (string, string) {
 	mPrefix := strings.Split(extraFilter, separator)
 	if mPrefix[0] == extraFilter {
 		return "", ""