sflow

package
v1.24.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 12, 2022 License: MIT Imports: 17 Imported by: 0

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:

Configuration

# SFlow V5 Protocol Listener
[[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))

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

View Source 
const (
	IPProtocolTCP uint8 = 6
	IPProtocolUDP uint8 = 17
)

Variables

View Source 
var ETypeMap = map[uint16]string{
	0x0800: "IPv4",
	0x86DD: "IPv6",
}
View Source 
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 ContainsMetricData interface {
	GetTags() map[string]string
	GetFields() map[string]interface{}
}

type EthHeader added in v1.15.0 

type EthHeader struct {
	DestinationMAC        [6]byte
	SourceMAC             [6]byte
	TagProtocolIdentifier uint16
	TagControlInformation uint16
	EtherTypeCode         uint16
	EtherType             string
	IPHeader              IPHeader
}

func (EthHeader) GetFields added in v1.15.0 

func (h EthHeader) GetFields() map[string]interface{}

func (EthHeader) GetTags added in v1.15.0 

func (h EthHeader) GetTags() map[string]string

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 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 

type PacketDecoder struct {
	Log telegraf.Logger
	// contains filtered or unexported fields
}

func NewDecoder added in v1.15.0 

func NewDecoder() *PacketDecoder

func (*PacketDecoder) Decode added in v1.15.0 

func (d *PacketDecoder) Decode(r io.Reader) error

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) Address 

func (s *SFlow) Address() net.Addr

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) Init 

func (s *SFlow) Init() error

func (*SFlow) SampleConfig 

func (*SFlow) SampleConfig() string

func (*SFlow) Start 

func (s *SFlow) Start(acc telegraf.Accumulator) error

Start starts this sFlow listener listening on the configured network for sFlow packets

func (*SFlow) Stop 

func (s *SFlow) Stop()

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 TCPHeader struct {
	SourcePort       uint16
	DestinationPort  uint16
	Sequence         uint32
	AckNumber        uint32
	TCPHeaderLength  uint8
	Flags            uint16
	TCPWindowSize    uint16
	Checksum         uint16
	TCPUrgentPointer uint16
}

https://en.wikipedia.org/wiki/Transmission_Control_Protocol

func (TCPHeader) GetFields added in v1.15.0 

func (h TCPHeader) GetFields() map[string]interface{}

func (TCPHeader) GetTags added in v1.15.0 

func (h TCPHeader) GetTags() map[string]string

type UDPHeader added in v1.15.0 

type UDPHeader struct {
	SourcePort      uint16
	DestinationPort uint16
	UDPLength       uint16
	Checksum        uint16
}

func (UDPHeader) GetFields added in v1.15.0 

func (h UDPHeader) GetFields() map[string]interface{}

func (UDPHeader) GetTags added in v1.15.0 

func (h UDPHeader) GetTags() map[string]string

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

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.