Docs: Document Promtail global rate limiting (#5737) (#5814)

* Docs: Document Promtail global rate limiting

* Update docs/sources/clients/promtail/configuration.md

Co-authored-by: Jennifer Villa <jvilla2013@gmail.com>

* Revise strings that explain the new configuration parameters

* For rate limiting, limit_config becomes limits_config

Co-authored-by: Jennifer Villa <jvilla2013@gmail.com>
(cherry picked from commit c860fc6)

Co-authored-by: Karen Miller <84039272+KMiller-Grafana@users.noreply.github.com>

clients/pkg/promtail/limit/config.go

@@ -12,8 +12,8 @@ type Config struct {
 }
 
 func (cfg *Config) RegisterFlagsWithPrefix(prefix string, f *flag.FlagSet) {
-	f.Float64Var(&cfg.ReadlineRate, prefix+"limit.readline-rate", 10000, "promtail readline Rate.")
-	f.IntVar(&cfg.ReadlineBurst, prefix+"limit.readline-burst", 10000, "promtail readline Burst.")
-	f.BoolVar(&cfg.ReadlineRateEnabled, prefix+"limit.readline-rate-enabled", false, "Set to false to disable readline rate limit.")
-	f.BoolVar(&cfg.ReadlineRateDrop, prefix+"limit.readline-rate-drop", true, "Set to true to drop log when rate limit.")
+	f.Float64Var(&cfg.ReadlineRate, prefix+"limit.readline-rate", 10000, "The rate limit in log lines per second that this instance of Promtail may push to Loki.")
+	f.IntVar(&cfg.ReadlineBurst, prefix+"limit.readline-burst", 10000, "The cap in the quantity of burst lines that this instance of Promtail may push to Loki.")
+	f.BoolVar(&cfg.ReadlineRateEnabled, prefix+"limit.readline-rate-enabled", false, "When true, enforces rate limiting on this instance of Promtail.")
+	f.BoolVar(&cfg.ReadlineRateDrop, prefix+"limit.readline-rate-drop", true, "When true, exceeding the rate limit causes this instance of Promtail to discard log lines, rather than sending them to Loki.")
 }

docs/sources/clients/promtail/configuration.md

@@ -95,6 +95,9 @@ clients:
 scrape_configs:
   - [<scrape_config>]
 
+# Configures global limits for this instance of Promtail
+[limits_config: <limits_config>]
+
 # Configures how tailed targets will be watched.
 [target_config: <target_config>]
 ```
@@ -1759,6 +1762,26 @@ scrape_configs:
         target_label: 'container'
 ```
 
+## limits_config
+
+The optional `limits_config` block configures global limits for this instance of Promtail.
+
+```yaml
+# When true, enforces rate limiting on this instance of Promtail.
+[readline_rate_enabled: <bool> | default = false]
+
+# The rate limit in log lines per second that this instance of Promtail may push to Loki.
+[readline_rate: <int> | default = 10000]
+
+# The cap in the quantity of burst lines that this instance of Promtail may push
+# to Loki.
+[readline_burst: <int> | default = 10000]
+
+# When true, exceeding the rate limit causes this instance of Promtail to discard
+# log lines, rather than sending them to Loki. When false, exceeding the rate limit
+# causes this instance of Promtail to temporarily hold off on sending the log lines and retry later.
+[readline_rate_drop: <bool> | default = true]
+```
 
 ## target_config