denniswitt/ts3exporter repository overview

⁠ts3exporter

Prometheus exporter to scrape TeamSpeak 3 Server metrics.

The exporter uses the server query protocol to provide prometheus metrics.

⁠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:

(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 IGNORE_FLOOD_LIMITS to 1 to disable the limiter.

⁠Usage

Run against a locally running TeamSpeak server:

docker run --net=host -e SERVERQUERY_PASSWORD=<serveradmin_password> --name ts3exporter -d denniswitt/ts3exporter

Enable channel metrics:

docker run --net=host -e ENABLE_CHANNEL_METRICS=1 -e IGNORE_FLOOD_LIMITS=<0|1> -e SERVERQUERY_PASSWORD=<serveradmin_password> --name ts3exporter -d denniswitt/ts3exporter

As part of docker compose:

version: '3.8'
services:
  teamspeak:
    image: teamspeak:3.13.7
    restart: always
    ports:
      - 9987:9987/udp
      - 10011:10011
      - 30033:30033
    environment:
      TS3SERVER_LICENSE: accept

  exporter:
    image: denniswitt/ts3exporter:latest
    restart: always
    ports:
      - 9189
    environment:
      REMOTE: teamspeak:10011
      SERVERQUERY_PASSWORD: <serveradmin_password>

⁠Overview of environment variables

The following is a list of all available environment variables with their default values:

ENABLE_CHANNEL_METRICS=0        # set to 1 to enable channel metrics
IGNORE_FLOOD_LIMITS=0           # set to 1 to ignore server query flood limits (don't forget to add the exporter to the query_ip_whitelist.txt file)
LISTEN_ADDRESS="0.0.0.0:9189"   # address the exporter listens on
SERVERQUERY_USER="serveradmin"  # user that is used for the server query requests
SERVERQUERY_PASSWORD=""         # password for the SERVERQUERY_USER
REMOTE="localhost:10011"        # remote address of the teamspeak severquery