udp_listener

README

UDP listener service input plugin

The UDP listener is a service input plugin that listens for messages on a UDP socket and adds those messages to InfluxDB. The plugin expects messages in the Telegraf Input Data Formats.

Configuration:

This is a sample configuration for the plugin.

[[inputs.udp_listener]]
  ## Address and port to host UDP listener on
  service_address = ":8092"

  ## Number of UDP messages allowed to queue up. Once filled, the
  ## UDP listener will start dropping packets.
  allowed_pending_messages = 10000

  ## Data format to consume.
  ## Each data format has it's own unique set of configuration options, read
  ## more about them here:
  ## https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_INPUT.md
  data_format = "influx"

A Note on UDP OS Buffer Sizes

Some OSes (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 8MB before trying to run large amounts of UDP traffic to your instance. 8MB is just a recommendation, and can be adjusted higher.

Linux

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

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

If the values are less than 8388608 bytes you should add the following lines to the /etc/sysctl.conf file:

net.core.rmem_max=8388608
net.core.rmem_default=8388608

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=8388608
sysctl -w net.core.rmem_default=8388608

BSD/Darwin

On BSD/Darwin systems you need to add about a 15% padding to the kernel limit socket buffer. Meaning if you want an 8MB buffer (8388608 bytes) you need to set the kernel limit to 8388608*1.15 = 9646900. This is not documented anywhere but happens in the kernel here.

Check the current UDP/IP buffer limit by typing the following command:

sysctl kern.ipc.maxsockbuf

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

kern.ipc.maxsockbuf=9646900

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

sysctl -w kern.ipc.maxsockbuf=9646900

Documentation

Index

• Constants
• type UdpListener
  • func (u *UdpListener) Description() string
  • func (u *UdpListener) Gather(_ telegraf.Accumulator) error
  • func (u *UdpListener) SampleConfig() string
  • func (u *UdpListener) SetParser(parser parsers.Parser)
  • func (u *UdpListener) Start(acc telegraf.Accumulator) error
  • func (u *UdpListener) Stop()

Constants

const UDP_MAX_PACKET_SIZE int = 64 * 1024

UDP_MAX_PACKET_SIZE is packet limit, see https://en.wikipedia.org/wiki/User_Datagram_Protocol#Packet_structure

Types

type UdpListener

type UdpListener struct {
	ServiceAddress string

	// UDPBufferSize should only be set if you want/need the telegraf UDP socket to
	// differ from the system setting. In cases where you set the rmem_default to a lower
	// value at the host level, but need a larger buffer for UDP bursty traffic, this
	// setting enables you to configure that value ONLY for telegraf UDP sockets on this listener
	// Set this to 0 (or comment out) to take system default
	//
	// NOTE: You should ensure that your rmem_max is >= to this setting to work properly!
	// (e.g. sysctl -w net.core.rmem_max=N)
	UDPBufferSize          int `toml:"udp_buffer_size"`
	AllowedPendingMessages int

	// UDPPacketSize is deprecated, it's only here for legacy support
	// we now always create 1 max size buffer and then copy only what we need
	// into the in channel
	// see https://github.com/influxdata/telegraf/pull/992
	UDPPacketSize int `toml:"udp_packet_size"`

	sync.Mutex

	PacketsRecv selfstat.Stat
	BytesRecv   selfstat.Stat
	// contains filtered or unexported fields
}

UdpListener main struct for the collector

func (*UdpListener) Description

func (u *UdpListener) Description() string

func (*UdpListener) Gather

func (u *UdpListener) Gather(_ telegraf.Accumulator) error

All the work is done in the Start() function, so this is just a dummy function.

func (*UdpListener) SampleConfig

func (u *UdpListener) SampleConfig() string

func (*UdpListener) SetParser

func (u *UdpListener) SetParser(parser parsers.Parser)

func (*UdpListener) Start

func (u *UdpListener) Start(acc telegraf.Accumulator) error

func (*UdpListener) Stop

func (u *UdpListener) Stop()