README
¶
SFlow Input Plugin
The SFlow Input Plugin provides support for acting as an SFlow V5 collector in accordance with the specification from sflow.org.
Currently only Flow Samples of Ethernet / IPv4 & IPv4 TCP & UDP headers are turned into metrics. Counters and other header samples are ignored.
Series Cardinality Warning
This plugin may produce a high number of series which, when not controlled for, will cause high load on your database. Use the following techniques to avoid cardinality issues:
- Use metric filtering options to exclude unneeded measurements and tags.
- Write to a database with an appropriate retention policy.
- Consider using the Time Series Index.
- Monitor your databases series cardinality.
- Consult the InfluxDB documentation for the most up-to-date techniques.
Configuration
[[inputs.sflow]]
## Address to listen for sFlow packets.
## example: service_address = "udp://:6343"
## service_address = "udp4://:6343"
## service_address = "udp6://:6343"
service_address = "udp://:6343"
## Set the size of the operating system's receive buffer.
## example: read_buffer_size = "64KiB"
# read_buffer_size = ""
Metrics
- sflow
- tags:
- agent_address (IP address of the agent that obtained the sflow sample and sent it to this collector)
- source_id_type(source_id_type field of flow_sample or flow_sample_expanded structures)
- source_id_index(source_id_index field of flow_sample or flow_sample_expanded structures)
- input_ifindex (value (input) field of flow_sample or flow_sample_expanded structures)
- output_ifindex (value (output) field of flow_sample or flow_sample_expanded structures)
- sample_direction (source_id_index, netif_index_in and netif_index_out)
- header_protocol (header_protocol field of sampled_header structures)
- ether_type (eth_type field of an ETHERNET-ISO88023 header)
- src_ip (source_ipaddr field of IPv4 or IPv6 structures)
- src_port (src_port field of TCP or UDP structures)
- src_port_name (src_port)
- src_mac (source_mac_addr field of an ETHERNET-ISO88023 header)
- src_vlan (src_vlan field of extended_switch structure)
- src_priority (src_priority field of extended_switch structure)
- src_mask_len (src_mask_len field of extended_router structure)
- dst_ip (destination_ipaddr field of IPv4 or IPv6 structures)
- dst_port (dst_port field of TCP or UDP structures)
- dst_port_name (dst_port)
- dst_mac (destination_mac_addr field of an ETHERNET-ISO88023 header)
- dst_vlan (dst_vlan field of extended_switch structure)
- dst_priority (dst_priority field of extended_switch structure)
- dst_mask_len (dst_mask_len field of extended_router structure)
- next_hop (next_hop field of extended_router structure)
- ip_version (ip_ver field of IPv4 or IPv6 structures)
- ip_protocol (ip_protocol field of IPv4 or IPv6 structures)
- ip_dscp (ip_dscp field of IPv4 or IPv6 structures)
- ip_ecn (ecn field of IPv4 or IPv6 structures)
- tcp_urgent_pointer (urgent_pointer field of TCP structure)
- fields:
- bytes (integer, the product of frame_length and packets)
- drops (integer, drops field of flow_sample or flow_sample_expanded structures)
- packets (integer, sampling_rate field of flow_sample or flow_sample_expanded structures)
- frame_length (integer, frame_length field of sampled_header structures)
- header_size (integer, header_size field of sampled_header structures)
- ip_fragment_offset (integer, ip_ver field of IPv4 structures)
- ip_header_length (integer, ip_ver field of IPv4 structures)
- ip_total_length (integer, ip_total_len field of IPv4 structures)
- ip_ttl (integer, ip_ttl field of IPv4 structures or ip_hop_limit field IPv6 structures)
- tcp_header_length (integer, size field of TCP structure. This value is specified in 32-bit words. It must be multiplied by 4 to produce a value in bytes.)
- tcp_window_size (integer, window_size field of TCP structure)
- udp_length (integer, length field of UDP structures)
- ip_flags (integer, ip_ver field of IPv4 structures)
- tcp_flags (integer, TCP flags of TCP IP header (IPv4 or IPv6))
- tags:
Troubleshooting
The sflowtool utility can be used to print sFlow packets, and compared against the metrics produced by Telegraf.
sflowtool -p 6343
If opening an issue, in addition to the output of sflowtool it will also be helpful to collect a packet capture. Adjust the interface, host and port as needed:
sudo tcpdump -s 0 -i eth0 -w telegraf-sflow.pcap host 127.0.0.1 and port 6343
Example Output
sflow,agent_address=0.0.0.0,dst_ip=10.0.0.2,dst_mac=ff:ff:ff:ff:ff:ff,dst_port=40042,ether_type=IPv4,header_protocol=ETHERNET-ISO88023,input_ifindex=6,ip_dscp=27,ip_ecn=0,output_ifindex=1073741823,source_id_index=3,source_id_type=0,src_ip=10.0.0.1,src_mac=ff:ff:ff:ff:ff:ff,src_port=443 bytes=1570i,drops=0i,frame_length=157i,header_length=128i,ip_flags=2i,ip_fragment_offset=0i,ip_total_length=139i,ip_ttl=42i,sampling_rate=10i,tcp_header_length=0i,tcp_urgent_pointer=0i,tcp_window_size=14i 1584473704793580447
Reference Documentation
This sflow implementation was built from the reference document sflow.org/sflow_version_5.txt
Documentation
¶
Index ¶
- Constants
- Variables
- type AddressType
- type ContainsMetricData
- type EthHeader
- type FlowData
- type FlowFormatType
- type FlowRecord
- type Header
- type HeaderProtocolType
- type IPHeader
- type IPV4Header
- type IPV6Header
- type InterfaceFormatType
- type PacketDecoder
- type ProtocolHeader
- type RawPacketHeaderFlowData
- type SFlow
- type Sample
- type SampleData
- type SampleDataFlowSampleExpanded
- type SampleType
- type TCPHeader
- type UDPHeader
- type V5Format
Constants ¶
const ( IPProtocolTCP uint8 = 6 IPProtocolUDP uint8 = 17 )
Variables ¶
var ETypeMap = map[uint16]string{
0x0800: "IPv4",
0x86DD: "IPv6",
}
var HeaderProtocolMap = map[HeaderProtocolType]string{ HeaderProtocolTypeEthernetISO88023: "ETHERNET-ISO88023", }
Functions ¶
This section is empty.
Types ¶
type AddressType ¶ added in v1.15.0
type AddressType uint32 // must be uint32
const ( AddressTypeUnknown AddressType = 0 AddressTypeIPV4 AddressType = 1 AddressTypeIPV6 AddressType = 2 )
type ContainsMetricData ¶ added in v1.15.0
type EthHeader ¶ added in v1.15.0
type FlowData ¶ added in v1.15.0
type FlowData ContainsMetricData
type FlowFormatType ¶ added in v1.15.0
type FlowFormatType uint32
const (
FlowFormatTypeRawPacketHeader FlowFormatType = 1 // sflow_version_5.txt line: 1938
)
type FlowRecord ¶ added in v1.15.0
type FlowRecord struct { FlowFormat FlowFormatType FlowData FlowData }
type Header ¶ added in v1.15.0
type Header ContainsMetricData
type HeaderProtocolType ¶ added in v1.15.0
type HeaderProtocolType uint32
const ( HeaderProtocolTypeEthernetISO88023 HeaderProtocolType = 1 HeaderProtocolTypeISO88024TokenBus HeaderProtocolType = 2 HeaderProtocolTypeISO88025TokenRing HeaderProtocolType = 3 HeaderProtocolTypeFDDI HeaderProtocolType = 4 HeaderProtocolTypeFrameRelay HeaderProtocolType = 5 HeaderProtocolTypeX25 HeaderProtocolType = 6 HeaderProtocolTypePPP HeaderProtocolType = 7 HeaderProtocolTypeSMDS HeaderProtocolType = 8 HeaderProtocolTypeAAL5 HeaderProtocolType = 9 HeaderProtocolTypeAAL5IP HeaderProtocolType = 10 /* e.g. Cisco AAL5 mux */ HeaderProtocolTypeIPv4 HeaderProtocolType = 11 HeaderProtocolTypeIPv6 HeaderProtocolType = 12 HeaderProtocolTypeMPLS HeaderProtocolType = 13 HeaderProtocolTypePOS HeaderProtocolType = 14 /* RFC 1662, 2615 */ )
type IPHeader ¶ added in v1.15.0
type IPHeader ContainsMetricData
type IPV4Header ¶ added in v1.15.0
type IPV4Header struct { Version uint8 // 4 bit InternetHeaderLength uint8 // 4 bit DSCP uint8 ECN uint8 TotalLength uint16 Identification uint16 Flags uint8 FragmentOffset uint16 TTL uint8 Protocol uint8 // https://en.wikipedia.org/wiki/List_of_IP_protocol_numbers HeaderChecksum uint16 SourceIP [4]byte DestIP [4]byte ProtocolHeader ProtocolHeader }
https://en.wikipedia.org/wiki/IPv4#Header
func (IPV4Header) GetFields ¶ added in v1.15.0
func (h IPV4Header) GetFields() map[string]interface{}
func (IPV4Header) GetTags ¶ added in v1.15.0
func (h IPV4Header) GetTags() map[string]string
type IPV6Header ¶ added in v1.15.0
type IPV6Header struct { DSCP uint8 ECN uint8 PayloadLength uint16 NextHeaderProto uint8 // tcp/udp? HopLimit uint8 SourceIP [16]byte DestIP [16]byte ProtocolHeader ProtocolHeader }
https://en.wikipedia.org/wiki/IPv6_packet
func (IPV6Header) GetFields ¶ added in v1.15.0
func (h IPV6Header) GetFields() map[string]interface{}
func (IPV6Header) GetTags ¶ added in v1.15.0
func (h IPV6Header) GetTags() map[string]string
type InterfaceFormatType ¶ added in v1.15.0
type InterfaceFormatType uint8 // sflow_version_5.txt line 1497
const ( InterfaceFormatTypeSingleInterface InterfaceFormatType = 0 InterfaceFormatTypePacketDiscarded InterfaceFormatType = 1 )
type PacketDecoder ¶ added in v1.15.0
func NewDecoder ¶ added in v1.15.0
func NewDecoder() *PacketDecoder
func (*PacketDecoder) DecodeOnePacket ¶ added in v1.15.0
func (d *PacketDecoder) DecodeOnePacket(r io.Reader) (*V5Format, error)
func (*PacketDecoder) OnPacket ¶ added in v1.15.0
func (d *PacketDecoder) OnPacket(f func(p *V5Format))
type ProtocolHeader ¶ added in v1.15.0
type ProtocolHeader ContainsMetricData
type RawPacketHeaderFlowData ¶ added in v1.15.0
type RawPacketHeaderFlowData struct { HeaderProtocol HeaderProtocolType FrameLength uint32 Bytes uint32 StrippedOctets uint32 HeaderLength uint32 Header Header }
func (RawPacketHeaderFlowData) GetFields ¶ added in v1.15.0
func (h RawPacketHeaderFlowData) GetFields() map[string]interface{}
func (RawPacketHeaderFlowData) GetTags ¶ added in v1.15.0
func (h RawPacketHeaderFlowData) GetTags() map[string]string
type SFlow ¶
type SFlow struct { ServiceAddress string `toml:"service_address"` ReadBufferSize config.Size `toml:"read_buffer_size"` Log telegraf.Logger `toml:"-"` // contains filtered or unexported fields }
func (*SFlow) Description ¶
Description answers a description of this input plugin
func (*SFlow) Gather ¶
func (s *SFlow) Gather(_ telegraf.Accumulator) error
Gather is a NOOP for sFlow as it receives, asynchronously, sFlow network packets
func (*SFlow) SampleConfig ¶
SampleConfig answers a sample configuration
type Sample ¶ added in v1.15.0
type Sample struct { SampleType SampleType SampleData SampleDataFlowSampleExpanded }
type SampleData ¶ added in v1.15.0
type SampleData interface{}
type SampleDataFlowSampleExpanded ¶ added in v1.15.0
type SampleDataFlowSampleExpanded struct { SequenceNumber uint32 SourceIDType uint32 SourceIDIndex uint32 SamplingRate uint32 SamplePool uint32 Drops uint32 SampleDirection string // ingress/egress InputIfFormat uint32 InputIfIndex uint32 OutputIfFormat uint32 OutputIfIndex uint32 FlowRecords []FlowRecord }
type SampleType ¶ added in v1.15.0
type SampleType uint32
const ( SampleTypeFlowSample SampleType = 1 // sflow_version_5.txt line: 1614 SampleTypeFlowSampleExpanded SampleType = 3 // sflow_version_5.txt line: 1698 )
type TCPHeader ¶ added in v1.15.0
type V5Format ¶
type V5Format struct { Version uint32 AgentAddress net.IPAddr SubAgentID uint32 SequenceNumber uint32 Uptime uint32 Samples []Sample }
V5Format answers and decoder.Directive capable of decoding sFlow v5 packets in accordance with SFlow v5 specification at https://sflow.org/sflow_version_5.txt