fix(inputs.gnmi): update configuration documentation (#12415)

plugins/inputs/gnmi/README.md

@@ -56,7 +56,7 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details.
   # prefix = ""
   # target = ""
 
-  ## Define additional aliases to map telemetry encoding paths to simple measurement names
+  ## Define additional aliases to map encoding paths to measurement names
   # [inputs.gnmi.aliases]
   #   ifcounters = "openconfig:/interfaces/interface/state/counters"
 
@@ -68,12 +68,13 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details.
     ## See: https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-specification.md#222-paths
     ##
     ## origin usually refers to a (YANG) data model implemented by the device
-    ## and path to a specific substructure inside it that should be subscribed to (similar to an XPath)
-    ## YANG models can be found e.g. here: https://github.com/YangModels/yang/tree/master/vendor/cisco/xr
+    ## and path to a specific substructure inside it that should be subscribed
+    ## to (similar to an XPath). YANG models can be found e.g. here:
+    ## https://github.com/YangModels/yang/tree/master/vendor/cisco/xr
     origin = "openconfig-interfaces"
     path = "/interfaces/interface/state/counters"
 
-    # Subscription mode (one of: "target_defined", "sample", "on_change") and interval
+    ## Subscription mode ("target_defined", "sample", "on_change") and interval
     subscription_mode = "sample"
     sample_interval = "10s"
 
@@ -83,17 +84,18 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details.
     ## If suppression is enabled, send updates at least every X seconds anyway
     # heartbeat_interval = "60s"
 
-  #[[inputs.gnmi.subscription]]
-    # name = "descr"
-    # origin = "openconfig-interfaces"
-    # path = "/interfaces/interface/state/description"
-    # subscription_mode = "on_change"
-
-    ## If tag_only is set, the subscription in question will be utilized to maintain a map of
-    ## tags to apply to other measurements emitted by the plugin, by matching path keys
-    ## All fields from the tag-only subscription will be applied as tags to other readings,
-    ## in the format <name>_<fieldBase>.
-    # tag_only = true
+  ## Tag subscriptions are applied as tags to other subscriptions.
+  # [[inputs.gnmi.tag_subscription]]
+  #  ## When applying this value as a tag to other metrics, use this tag name
+  #  name = "descr"
+  #  ## All other subscription fields are as normal
+  #  origin = "openconfig-interfaces"
+  #  path = "/interfaces/interface/state"
+  #  subscription_mode = "on_change"
+  #  ## At least one path element name must be supplied that contains at least
+  #  ## one key to match on. Multiple element names can be specified in any
+  #  ## order. In this case all element names must be present.
+  #  elements = ["description", "interface"]
 ```
 
 ## Metrics

plugins/inputs/gnmi/gnmi.go

@@ -116,7 +116,7 @@ type Subscription struct {
 	HeartbeatInterval config.Duration `toml:"heartbeat_interval"`
 
 	// Mark this subscription as a tag-only lookup source, not emitting any metric
-	TagOnly bool `toml:"tag_only"`
+	TagOnly bool `toml:"tag_only" deprecated:"1.25.0;2.0.0;please use 'tag_subscription's instead"`
 }
 
 // Tag Subscription for a gNMI client
@@ -364,6 +364,7 @@ func (c *GNMI) handleSubscribeResponseUpdate(worker *Worker, response *gnmiLib.S
 		fullPath := pathWithPrefix(response.Update.Prefix, update.Path)
 		for _, tagSub := range c.TagSubscriptions {
 			if equalPathNoKeys(fullPath, tagSub.fullPath) {
+				c.Log.Debugf("Tag-subscription update for %q: %+v", tagSub.Name, update)
 				worker.storeTags(update, tagSub)
 				response.Update.Update = append(response.Update.Update[:i], response.Update.Update[i+1:]...)
 			}

plugins/inputs/gnmi/sample.conf

@@ -31,7 +31,7 @@
   # prefix = ""
   # target = ""
 
-  ## Define additional aliases to map telemetry encoding paths to simple measurement names
+  ## Define additional aliases to map encoding paths to measurement names
   # [inputs.gnmi.aliases]
   #   ifcounters = "openconfig:/interfaces/interface/state/counters"
 
@@ -43,12 +43,13 @@
     ## See: https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-specification.md#222-paths
     ##
     ## origin usually refers to a (YANG) data model implemented by the device
-    ## and path to a specific substructure inside it that should be subscribed to (similar to an XPath)
-    ## YANG models can be found e.g. here: https://github.com/YangModels/yang/tree/master/vendor/cisco/xr
+    ## and path to a specific substructure inside it that should be subscribed
+    ## to (similar to an XPath). YANG models can be found e.g. here:
+    ## https://github.com/YangModels/yang/tree/master/vendor/cisco/xr
     origin = "openconfig-interfaces"
     path = "/interfaces/interface/state/counters"
 
-    # Subscription mode (one of: "target_defined", "sample", "on_change") and interval
+    ## Subscription mode ("target_defined", "sample", "on_change") and interval
     subscription_mode = "sample"
     sample_interval = "10s"
 
@@ -58,14 +59,15 @@
     ## If suppression is enabled, send updates at least every X seconds anyway
     # heartbeat_interval = "60s"
 
-  #[[inputs.gnmi.subscription]]
-    # name = "descr"
-    # origin = "openconfig-interfaces"
-    # path = "/interfaces/interface/state/description"
-    # subscription_mode = "on_change"
-
-    ## If tag_only is set, the subscription in question will be utilized to maintain a map of
-    ## tags to apply to other measurements emitted by the plugin, by matching path keys
-    ## All fields from the tag-only subscription will be applied as tags to other readings,
-    ## in the format <name>_<fieldBase>.
-    # tag_only = true
+  ## Tag subscriptions are applied as tags to other subscriptions.
+  # [[inputs.gnmi.tag_subscription]]
+  #  ## When applying this value as a tag to other metrics, use this tag name
+  #  name = "descr"
+  #  ## All other subscription fields are as normal
+  #  origin = "openconfig-interfaces"
+  #  path = "/interfaces/interface/state"
+  #  subscription_mode = "on_change"
+  #  ## At least one path element name must be supplied that contains at least
+  #  ## one key to match on. Multiple element names can be specified in any
+  #  ## order. In this case all element names must be present.
+  #  elements = ["description", "interface"]