[pve-docs.git] / pve-external-metric-server.adoc

[[external_metric_server]]
External Metric Server
----------------------
ifdef::wiki[]
:pve-toplevel:
endif::wiki[]

[thumbnail="screenshot/gui-datacenter-metric-server-list.png"]

In {pve}, you can define external metric servers, which will periodically
receive various stats about your hosts, virtual guests and storages.

Currently supported are:

 * Graphite (see https://graphiteapp.org )
 * InfluxDB (see https://www.influxdata.com/time-series-platform/influxdb/ )

The external metric server definitions are saved in '/etc/pve/status.cfg', and
can be edited through the web interface.

[[metric_server_graphite]]
Graphite server configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[thumbnail="screenshot/gui-datacenter-metric-server-graphite.png"]

The default port is set to *2003* and the default graphite path is *proxmox*.

By default, {pve} sends the data over UDP, so the graphite server has to be
configured to accept this. Here the maximum transmission unit (MTU) can be
configured for environments not using the standard *1500* MTU.

You can also configure the plugin to use TCP. In order not to block the
important `pvestatd` statistic collection daemon, a timeout is required to cope
with network problems.

[[metric_server_influxdb]]
Influxdb plugin configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[thumbnail="screenshot/gui-datacenter-metric-server-influxdb.png"]

{pve} sends the data over UDP, so the influxdb server has to be configured for
this. The MTU can also be configured here, if necessary.

Here is an example configuration for influxdb (on your influxdb server):

----
[[udp]]
   enabled = true
   bind-address = "0.0.0.0:8089"
   database = "proxmox"
   batch-size = 1000
   batch-timeout = "1s"
----

With this configuration, your server listens on all IP addresses on port 8089,
and writes the data in the *proxmox* database

Alternatively, the plugin can be configured to use the http(s) API of InfluxDB 2.x.
InfluxDB 1.8.x does contain a forwards compatible API endpoint for this v2 API.

To use it, set 'influxdbproto' to 'http' or 'https' (depending on your configuration).
By default, {pve} uses the organization 'proxmox' and the bucket/db 'proxmox'
(They can be set with the configuration 'organization' and 'bucket' respectively).

Since InfluxDB's v2 API is only available with authentication, you have
to generate a token that can write into the correct bucket and set it.

In the v2 compatible API of 1.8.x, you can use 'user:password' as token
(if required), and can omit the 'organization' since that has no meaning in InfluxDB 1.x.

You can also set the HTTP Timeout (default is 1s) with the 'timeout' setting,
as well as the maximum batch size (default 25000000 bytes) with the
'max-body-size' setting (this corresponds to the InfluxDB setting with the
same name).
Commit	Line	Data
	1	[[external_metric_server]]
	2	External Metric Server
	3	----------------------
	4	ifdef::wiki[]
	5	:pve-toplevel:
	6	endif::wiki[]
	7
	8	[thumbnail="screenshot/gui-datacenter-metric-server-list.png"]
	9
	10	In {pve}, you can define external metric servers, which will periodically
	11	receive various stats about your hosts, virtual guests and storages.
	12
	13	Currently supported are:
	14
	15	* Graphite (see https://graphiteapp.org )
	16	* InfluxDB (see https://www.influxdata.com/time-series-platform/influxdb/ )
	17
	18	The external metric server definitions are saved in '/etc/pve/status.cfg', and
	19	can be edited through the web interface.
	20
	21	[[metric_server_graphite]]
	22	Graphite server configuration
	23	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	24
	25	[thumbnail="screenshot/gui-datacenter-metric-server-graphite.png"]
	26
	27	The default port is set to 2003 and the default graphite path is proxmox.
	28
	29	By default, {pve} sends the data over UDP, so the graphite server has to be
	30	configured to accept this. Here the maximum transmission unit (MTU) can be
	31	configured for environments not using the standard 1500 MTU.
	32
	33	You can also configure the plugin to use TCP. In order not to block the
	34	important `pvestatd` statistic collection daemon, a timeout is required to cope
	35	with network problems.
	36
	37	[[metric_server_influxdb]]
	38	Influxdb plugin configuration
	39	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	40
	41	[thumbnail="screenshot/gui-datacenter-metric-server-influxdb.png"]
	42
	43	{pve} sends the data over UDP, so the influxdb server has to be configured for
	44	this. The MTU can also be configured here, if necessary.
	45
	46	Here is an example configuration for influxdb (on your influxdb server):
	47
	48	----
	49	[[udp]]
	50	enabled = true
	51	bind-address = "0.0.0.0:8089"
	52	database = "proxmox"
	53	batch-size = 1000
	54	batch-timeout = "1s"
	55	----
	56
	57	With this configuration, your server listens on all IP addresses on port 8089,
	58	and writes the data in the proxmox database
	59
	60	Alternatively, the plugin can be configured to use the http(s) API of InfluxDB 2.x.
	61	InfluxDB 1.8.x does contain a forwards compatible API endpoint for this v2 API.
	62
	63	To use it, set 'influxdbproto' to 'http' or 'https' (depending on your configuration).
	64	By default, {pve} uses the organization 'proxmox' and the bucket/db 'proxmox'
	65	(They can be set with the configuration 'organization' and 'bucket' respectively).
	66
	67	Since InfluxDB's v2 API is only available with authentication, you have
	68	to generate a token that can write into the correct bucket and set it.
	69
	70	In the v2 compatible API of 1.8.x, you can use 'user:password' as token
	71	(if required), and can omit the 'organization' since that has no meaning in InfluxDB 1.x.
	72
	73	You can also set the HTTP Timeout (default is 1s) with the 'timeout' setting,
	74	as well as the maximum batch size (default 25000000 bytes) with the
	75	'max-body-size' setting (this corresponds to the InfluxDB setting with the
	76	same name).