Document when a plugin uses tracking metrics and what that means

[danielnelson]

Feature Request

Opening a feature request kicks off a discussion.

Proposal:

Improve documentation of the tracking metric functionality. This is important to understand what will happen when an output goes down or messages are undelivered.

Current behavior:

No user facing documentation other than the max_undelivered_messages option, for example:

  ## Maximum messages to read from the broker that have not been written by an
  ## output.  For best throughput set based on the number of metrics within
  ## each message and the size of the output's metric_batch_size.
  ##
  ## For example, if each message from the queue contains 10 metrics and the
  ## output metric_batch_size is 1000, setting this to 100 will ensure that a
  ## full batch is collected and the write is triggered immediately without
  ## waiting until the next flush_interval.
  # max_undelivered_messages = 1000

Affected plugins:

$ ack WithTracking -l plugins/inputs/
plugins/inputs/nsq_consumer/nsq_consumer.go
plugins/inputs/kinesis_consumer/kinesis_consumer.go
plugins/inputs/cloud_pubsub/pubsub.go
plugins/inputs/nats_consumer/nats_consumer.go
plugins/inputs/mqtt_consumer/mqtt_consumer.go
plugins/inputs/kafka_consumer/kafka_consumer.go
plugins/inputs/amqp_consumer/amqp_consumer.go
plugins/inputs/cloud_pubsub_push/pubsub_push.go
plugins/inputs/cloud_pubsub_push/pubsub_push_test.go

Desired behavior:

Document that the plugin uses this feature and how it uses it to acknowledge or reject messages.

Use case:

[powersj]

next steps: land #9858 with final wording and then update the remaining plugins listed above.