Disable the channel metrics by default. Add an option to disable the …

…flood limiter

Readme.md

@@ -16,18 +16,40 @@ go build
 ``` 
 # ./ts3exporter -h
 Usage of ./ts3exporter:
+  -enablechannelmetrics
+    	Enables the channel collector.
+  -ignorefloodlimits
+    	Disable the server query flood limiter. Use this only if your exporter is whitelisted in the query_ip_whitelist.txt file.
   -listen string
-        listen address of the exporter (default ":9189")
+    	listen address of the exporter (default ":9189")
   -password string
-        the serverquery password of the ts3exporter
+    	the serverquery password of the ts3exporter
   -passwordfile string
-        file containing the password. Only read if -password not set. Must have 0600 permission. (default "/etc/ts3exporter/password")
+    	file containing the password. Only read if -password not set. Must have 0600 permission. (default "/etc/ts3exporter/password")
   -remote string
-        remote address of server query port (default "localhost:10011")
+    	remote address of server query port (default "localhost:10011")
   -user string
-        the serverquery user of the ts3exporter (default "serveradmin")
+    	the serverquery user of the ts3exporter (default "serveradmin")
+```
 
+## Channel Metrics
+The exporter can produce per channel metrics. The channel metrics are disabled by default, since the channel metrics produce a high number of 
+server query commands. The current formular is `(2 + NumberOfChannels) * NumberOfVServer` server query commands. The default server
+query flood limit is 10 commands per 3 seconds. To not run into that limit, the exporter reads the limit at login time and 
+throttles itself below that. The default results in one server query command every 300ms.
+Using the default flood limit and a vServer with 10 channels we get the following scrape time:
+```text
+(2 * 10)*1 * 300ms = 6s
 ```
+The `serverinfo` metrics collector produces `1 + NumberOfVServer*2` 
+serverquery commands. In our example that adds additional 900ms.
+Since we update the metrics if the prometheus server calls the `/metrics`
+endpoint, the scrape timeout must be at least 7 seconds. 
+
+### Workarounds
+To speed up the scraping you can increase the server query flood limits or add the IP of your exporter to the
+`query_ip_whitelist.txt` file. If your exporter IP is added to the whitelist file, set the option `-ignorefloodlimits` to 
+disable the limiter.
 
 ## Examples:
 ```bash

main.go

@@ -22,25 +22,24 @@ func main() {
 	user := flag.String("user", "serveradmin", "the serverquery user of the ts3exporter")
 	password := flag.String("password", "", "the serverquery password of the ts3exporter")
 	passwordFile := flag.String("passwordfile", "/etc/ts3exporter/password", "file containing the password. Only read if -password not set. Must have 0600 permission.")
-	disableChannel := flag.Bool("disablechannel", false, "disables the channel collector. Disable the channel collector if it produces a too high label cardinality.")
+	enableChannelMetrics := flag.Bool("enablechannelmetrics", false, "Enables the channel collector.")
+	ignoreFloodLimits := flag.Bool("ignorefloodlimits", false, "Disable the server query flood limiter. Use this only if your exporter is whitelisted in the query_ip_whitelist.txt file.")
 
 	flag.Parse()
-	c, err := serverquery.NewClient(*remote, *user, mustReadPassword(*password, *passwordFile))
+	c, err := serverquery.NewClient(*remote, *user, mustReadPassword(*password, *passwordFile), *ignoreFloodLimits)
 	if err != nil {
 		log.Fatalf("failed to init client %v\n", err)
 	}
 	sqInfo := serverquery.NewVirtualServer(c)
 	sInfo := collector.NewServerInfo(sqInfo)
 	mc := collector.NewMultiCollector(sInfo)
 
-	if !*disableChannel {
+	if *enableChannelMetrics {
 		cqInfo := serverquery.NewChannelView(c, sqInfo)
 		cInfo := collector.NewChannel(cqInfo)
 		mc.Add(cInfo)
 	}
 
-	prometheus.MustRegister(mc)
-
 	prometheus.MustRegister(mc, collector.NewClient(c))
 	// The Handler function provides a default handler to expose metrics
 	// via an HTTP server. "/metrics" is the usual endpoint for that.

pkg/serverquery/client.go

@@ -15,6 +15,7 @@ type Client struct {
 	user               string
 	password           string
 	remote             string
+	respectLimits      bool
 	serverQueryOptions []options
 	virtualServerID    int
 	metrics            ClientMetrics
@@ -24,11 +25,12 @@ type options func() func(client *ts3.Client) error
 
 // NewClient instantiate a new client to the given remote. If the function returns successfully the client is already
 // logged in.
-func NewClient(remote, user, password string, serverQueryOptions ...options) (*Client, error) {
+func NewClient(remote, user, password string, ignoreLimits bool, serverQueryOptions ...options) (*Client, error) {
 	c := &Client{
 		user:               user,
 		password:           password,
 		remote:             remote,
+		respectLimits:      !ignoreLimits,
 		serverQueryOptions: serverQueryOptions,
 	}
 	return c, c.reconnect()
@@ -38,8 +40,10 @@ func (c *Client) reconnect() error {
 	if err := c.login(c.remote, c.serverQueryOptions...); err != nil {
 		return fmt.Errorf("failed to login: %w", err)
 	}
-	if err := c.setupLimiter(); err != nil {
-		return fmt.Errorf("failed to setup limiter: %w", err)
+	if c.respectLimits {
+		if err := c.setupLimiter(); err != nil {
+			return fmt.Errorf("failed to setup limiter: %w", err)
+		}
 	}
 	return nil
 }