Socket Stage (UDP)

This stage allows you to receive UDP packets from a remote source (sensor). These packets will be grouped together into UdpPacketGroup messages before publishing.

Grouping is intended as a mechanism to batch messages on high-rate sensors, reducing performance overhead of publishing and logging individual UDP packets.

Configuration

Basic configuration is in the UdpSocketStageConfig:

  • address - The address and port you expect to receive packets from.
  • reuse_address - If SO_REUSEADDR can be set on this socket.
  • interface - The name of a local interface to bind to (defaults to any).
  • group_size - The number of packets to bundle before publishing a group.
  • thread_priority - Priority to set the for the reading thread.
  • thread_processor_affinity - Which processors the reading thread can operate on.
  • multicast - Use this to indicate the stage should join a multicast group on its bound address.
  • multicast_address - Use this to specify the IP address of the local interface on which to join the multicast group (blank defaults to INADDR_ANY).
  • unix_domain_client - Use this to connect to a domain socket instead of a IP socket.
  • kernel_receive_buffer_size_b - Size of the kernel receive buffer (zero for kernel default).
  • kernel_transmit_buffer_size_b - Size of the kernel transmit buffer (zero for kernel default).

The kernel receive and transmit buffer sizes are used to configure the kernel-size of the buffers, allowing data to be buffered on the kernel rather than keeping it in userspace. This can help avoid dropped packets (on the receive size) if the stage is not keeping up.

Interacting

There is no inputs to this stage. It starts a background thread which services a socket. The thread will retry binding the socket until it is successful.

All packet groups are published under packet_group in the stage’s namespace.

The stage listens for data to publish on the egress_packets channel. Anything received will be written over the UDP socket when connected (or dropped otherwise). Packets are written 1:1 – please ensure the size of your packet does not exceed the configured UDP maximum for the host machine.

Metrics

The stage periodically (at 1Hz) emits a SocketStats structure containing rate and size information. This is published under the socket_stats channel within the stage’s namespace.