Documentation

UDP protocol support in InfluxDB

This page documents an earlier version of InfluxDB. InfluxDB v2.6 is the latest stable version.

The UDP Input

A note on UDP/IP OS Buffer sizes

Some operating systems (most notably, Linux) place very restricive limits on the performance of UDP protocols. It is highly recommended that you increase these OS limits to at least 25MB before trying to run UDP traffic to your instance. 25MB is just a recommendation, and should be adjusted to be inline with your read-buffer plugin setting.

Linux

Check the current UDP/IP receive buffer default and limit by typing the following commands:

sysctl net.core.rmem_max
sysctl net.core.rmem_default

If the values are less than 26214400 bytes (25MB), you should add the following lines to the /etc/sysctl.conf file:

net.core.rmem_max=26214400
net.core.rmem_default=26214400

Changes to /etc/sysctl.conf do not take effect until reboot. To update the values immediately, type the following commands as root:

sysctl -w net.core.rmem_max=26214400
sysctl -w net.core.rmem_default=26214400

BSD/Darwin

On BSD/Darwin systems, you need to add about a 15% padding to the kernel limit socket buffer. For example, if you want a 25MB buffer (26214400 bytes) you need to set the kernel limit to 26214400*1.15 = 30146560. This is not documented anywhere but happens in the kernel here.

Checking current UDP/IP buffer limits

To check the current UDP/IP buffer limit, type the following command:

sysctl kern.ipc.maxsockbuf

If the value is less than 30146560 bytes, you should add the following lines to the /etc/sysctl.conf file (create it if necessary):

kern.ipc.maxsockbuf=30146560

Changes to /etc/sysctl.conf do not take effect until reboot. To update the values immediately, type the following command as root:

sysctl -w kern.ipc.maxsockbuf=30146560

Using the read-buffer option for the UDP listener

The read-buffer option allows users to set the buffer size for the UDP listener. It sets the size of the operating system’s receive buffer associated with the UDP traffic. Keep in mind that the OS must be able to handle the number set here or the UDP listener will error and exit.

Setting read-buffer = 0 results in the OS default being used and is usually too small for high UDP performance.

Configuration

Each UDP input allows the binding address, target database, and target retention policy to be set. If the database does not exist, it will be created automatically when the input is initialized. If the retention policy is not configured, then the default retention policy for the database is used. However, if the retention policy is set, the retention policy must be explicitly created. The input will not automatically create it.

Each UDP input also performs internal batching of the points it receives, as batched writes to the database are more efficient. The default batch size is 1000, pending batch factor is 5, with a batch timeout of 1 second. This means the input will write batches of maximum size 1000, but if a batch has not reached 1000 points within 1 second of the first point being added to a batch, it will emit that batch regardless of size. The pending batch factor controls how many batches can be in memory at once, allowing the input to transmit a batch, while still building other batches.

Points written via the UDP listener are set to nanosecond level precision by default. Like the HTTP write endpoint, any points written to the UDP listener without a timestamp are assigned a timestamp by InfluxDB when the points are received.

Processing

The UDP input can receive up to 64KB per read, and splits the received data by newline. Each part is then interpreted as line-protocol encoded points, and parsed accordingly.

UDP is connectionless

Since UDP is a connectionless protocol, there is no way to signal to the data source if any error occurs, and if data has even been successfully indexed. This should be kept in mind when deciding if and when to use the UDP input. The built-in UDP statistics are useful for monitoring the UDP inputs.

Config examples

One UDP listener

# influxd.conf
...
[[udp]]
  enabled = true
  bind-address = ":8089" # the bind address
  database = "telegraf" # name of the database that will be written to
  batch-size = 5000 # will flush if this many points get buffered
  batch-timeout = "1s" # will flush at least this often even if the batch-size is not reached
  batch-pending = 10 # number of batches that may be pending in memory
  read-buffer = 0 # UDP read buffer, 0 means to use OS default
  precision = "n" # sets the default precision of points written via UDP
...

Multiple UDP listeners

# influxd.conf
...
[[udp]]
  # Default UDP for Telegraf
  enabled = true
  bind-address = ":8089" # the bind address
  database = "telegraf" # name of the database that will be written to
  batch-size = 5000 # will flush if this many points get buffered
  batch-timeout = "1s" # will flush at least this often even if the batch-size is not reached
  batch-pending = 10 # number of batches that may be pending in memory
  read-buffer = 0 # UDP read buffer size, 0 means to use OS default
  precision = "n" # sets the default precision of points written via UDP

[[udp]]
  # High-traffic UDP
  enabled = true
  bind-address = ":8189" # the bind address
  database = "mymetrics" # name of the database that will be written to
  batch-size = 5000 # will flush if this many points get buffered
  batch-timeout = "1s" # will flush at least this often even if the batch-size is not reached
  batch-pending = 100 # number of batches that may be pending in memory
  read-buffer = 8388608 # (8*1024*1024) UDP read buffer size
  precision = "n" # sets the default precision of points written via UDP
...

Content from README


Was this page helpful?

Thank you for your feedback!


Set your InfluxDB URL

Linux Package Signing Key Rotation

All signed InfluxData Linux packages have been resigned with an updated key. If using Linux, you may need to update your package configuration to continue to download and verify InfluxData software packages.

For more information, see the Linux Package Signing Key Rotation blog post.

InfluxDB Cloud backed by InfluxDB IOx

All InfluxDB Cloud organizations created on or after January 31, 2023 are backed by the new InfluxDB IOx storage engine. Check the right column of your InfluxDB Cloud organization homepage to see which InfluxDB storage engine you’re using.

If powered by IOx, this is the correct documentation.

If powered by TSM, see the TSM-based InfluxDB Cloud documentation.

InfluxDB Cloud backed by InfluxDB TSM

All InfluxDB Cloud organizations created on or after January 31, 2023 are backed by the new InfluxDB IOx storage engine which enables nearly unlimited series cardinality and SQL query support. Check the right column of your InfluxDB Cloud organization homepage to see which InfluxDB storage engine you’re using.

If powered by TSM, this is the correct documentation.

If powered by IOx, see the IOx-based InfluxDB Cloud documentation.

State of the InfluxDB Cloud (IOx) documentation

The new documentation for InfluxDB Cloud backed by InfluxDB IOx is a work in progress. We are adding new information and content almost daily. Thank you for your patience!

If there is specific information you’re looking for, please submit a documentation issue.