README
¶
libkflow - library for sending kflow
libkflow is a library for generating and sending kflow records to Kentik written in Go and also providing a simple C API.
Go Usage
Create a libkflow Config and pass it to one of the NewSenderWith*
methods, along with the appropriate device identifier and an error
channel which may be polled for asynchronous errors.
errors := make(chan error, 100)
config := libkflow.NewConfig("email", "token", "program", "1.0.0")
s, err := libkflow.NewSenderWithDeviceID(0, errors, config)
s.Send(&flow.Flow{
Ipv4SrcAddr: src,
Ipv4DstAddr: dst,
})
C Usage
demo.c provides an example of correct API usage and will send one flow record to the test server which is expected to be running and listening on 127.0.0.1:8999.
Mock Server
A mock server that accepts API, flow, and metrics requests is available for testing purposes:
go install github.com/kentik/libkflow/cmd/server && bin/server
A variety of command line parameters are available, by default it will listen on 127.0.0.1:8999 and accept some default values for authentication and device identification. A full demonstration program written in Go is available:
Build
Building libkflow requires GNU make and the Go toolchain. Set GOPATH to the directory containing this file and invoke make:
$ export PATH=$PWD
$ make
The default make target will build libkflow.a and create a distribution
libkflow-$VERSION-$TARGET.tar.gz file containing the compiled library,
test server binary, demo.c, and kflow.h.
All built artifacts will be placed in $CURDIR/out/$TARGET where $CURDIR
is the current working directory and $TARGET is $GOOS-$GOARCH, for
example linux-amd64.
Documentation
¶
Index ¶
- Variables
- type Capture
- type Config
- func (c *Config) GetClient() *api.Client
- func (c *Config) NewMetrics(dev *api.Device) *metrics.Metrics
- func (c *Config) OverrideURLs(api, flow, metrics *url.URL)
- func (c *Config) SetCapture(capture Capture)
- func (c *Config) SetFlow(server string)
- func (c *Config) SetLeveledLogger(logger LeveledLogger)
- func (c *Config) SetLogger(logger Logger)
- func (c *Config) SetMetricsInterval(dur time.Duration)
- func (c *Config) SetMetricsPrefix(prefix string)
- func (c *Config) SetProxy(url *url.URL)
- func (c *Config) SetRetries(retries int)
- func (c *Config) SetSampleRate(sample int)
- func (c *Config) SetServer(host net.IP, port int)
- func (c *Config) SetTimeout(timeout time.Duration)
- func (c *Config) SetVerbose(level int)
- func (c *Config) WithRegistry(registry go_metrics.Registry)
- type LeveledLogger
- type Logger
- type Sender
- func NewSenderFromDevice(d *api.Device, errors chan<- error, cfg *Config) (*Sender, error)
- func NewSenderFromDeviceWithErrors(d *api.Device, cfg *Config) (*Sender, <-chan error, error)
- func NewSenderWithDeviceID(did int, errors chan<- error, cfg *Config) (*Sender, error)
- func NewSenderWithDeviceIF(dif string, errors chan<- error, cfg *Config) (*Sender, error)
- func NewSenderWithDeviceIP(dip net.IP, errors chan<- error, cfg *Config) (*Sender, error)
- func NewSenderWithDeviceName(name string, errors chan<- error, cfg *Config) (*Sender, error)
- func NewSenderWithDeviceNameWithErrors(name string, cfg *Config) (*Sender, <-chan error, error)
- func NewSenderWithNewDevice(dev *api.DeviceCreate, errors chan<- error, cfg *Config) (*Sender, error)
- func NewSenderWithNewDeviceWithErrors(dev *api.DeviceCreate, cfg *Config) (*Sender, <-chan error, error)
- func NewSenderWithNewSiteAndDevice(siteAndDevice *api.SiteAndDeviceCreate, errors chan<- error, cfg *Config) (*Sender, error)
- func NewSenderWithNewSiteAndDeviceWithErrors(siteAndDevice *api.SiteAndDeviceCreate, cfg *Config) (*Sender, <-chan error, error)
- func (s *Sender) GetClient() *api.Client
- func (s *Sender) GetDevice() *api.Device
- func (s *Sender) Send(flow *flow.Flow)
- func (s *Sender) SendDNS(res *api.DNSResponse) error
- func (s *Sender) SendEncodedDNS(data []byte)
- func (s *Sender) StartDNS(url *url.URL, interval time.Duration)
- func (s *Sender) Stop(wait time.Duration) bool
Constants ¶
This section is empty.
Variables ¶
var ( ErrInvalidAuth = errors.New("invalid API email/token") ErrInvalidConfig = errors.New("invalid config") ErrInvalidDevice = errors.New("invalid device") )
var Version = "0.0.0"
Version of libkflow
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// contains filtered or unexported fields
}
Config describes the libkflow configuration.
func NewConfig ¶
NewConfig returns a new Config given an API access email and token, and the name and version of the program using libkflow.
func (*Config) OverrideURLs ¶
OverrideURLs changes the default endpoint URL for API requests, flow, and metrics.
func (*Config) SetCapture ¶
SetCapture sets the packet capture details.
func (*Config) SetLeveledLogger ¶
func (c *Config) SetLeveledLogger(logger LeveledLogger)
SetLeveledLogger sets the level based logger to use for the underlying HTTP requests.
func (*Config) SetMetricsInterval ¶
func (*Config) SetMetricsPrefix ¶
func (*Config) SetProxy ¶
SetProxy sets the HTTP proxy used for making API requests, sending flow, and sending metrics.
func (*Config) SetRetries ¶
SetRetries sets the number of times to try HTTP requests.
func (*Config) SetSampleRate ¶
SetSampleRate sets the configured sample rate. If the sample rate is not set, and the rate configured in the device settings changes, then libkflow will abort the program with a call to exit().
func (*Config) SetServer ¶
SetServer changes the host and port used for API requests, flow, and metrics.
func (*Config) SetTimeout ¶
SetTimeout sets the HTTP request timeout.
func (*Config) SetVerbose ¶
SetVerbose sets the verbosity level. Specifying a value greater than zero will cause verbose debug messages to be print to stderr.
func (*Config) WithRegistry ¶
func (c *Config) WithRegistry(registry go_metrics.Registry)
WithRegistry allows setting a registry which will act as a shared registry between multiple Senders.
type LeveledLogger ¶
type LeveledLogger interface {
Error(string, ...interface{})
Info(string, ...interface{})
Debug(string, ...interface{})
Warn(string, ...interface{})
}
LeveledLogger interface implements the basic methods that a logger library needs
type Logger ¶
type Logger interface {
Printf(string, ...interface{})
}
Logger interface allows to use other loggers than standard log.Logger.
type Sender ¶
type Sender struct {
Device *api.Device
Errors chan<- error
Metrics *metrics.Metrics
// contains filtered or unexported fields
}
A Sender aggregates and transmits flow information to Kentik.
func NewSenderFromDevice ¶
NewSenderFromDevice returns a Sender for an existing Device
func NewSenderFromDeviceWithErrors ¶
NewSenderFromDeviceWithErrors returns a Sender and an error channel for an existing Device
func NewSenderWithDeviceID ¶
NewSenderWithDeviceID creates a new flow Sender given a device ID, error channel, and Config.
func NewSenderWithDeviceIF ¶
NewSenderWithDeviceIF creates a new flow Sender given a device interface name, error channel, and Config.
func NewSenderWithDeviceIP ¶
NewSenderWithDeviceIP creates a new flow Sender given a device IP address, error channel, and Config.
func NewSenderWithDeviceName ¶
NewSenderWithDeviceName creates a new flow Sender given a device name address, error channel, and Config.
func NewSenderWithDeviceNameWithErrors ¶
NewSenderWithDeviceNameWithErrors creates a new flow Sender given a device name address and Config. The channel is closed after Sender.Stop is called and all flow has been dispatched.
func NewSenderWithNewDevice ¶
func NewSenderWithNewDevice(dev *api.DeviceCreate, errors chan<- error, cfg *Config) (*Sender, error)
NewSenderWithNewDevice creates a new device given device creation parameters, and then creates a new flow Sender with that device, the error channel, and the Config.
func NewSenderWithNewDeviceWithErrors ¶
func NewSenderWithNewDeviceWithErrors(dev *api.DeviceCreate, cfg *Config) (*Sender, <-chan error, error)
NewSenderWithNewDeviceWithErrors creates a new device and returns a new flow Sender and an error channel which will report errors generated from the Sender. The channel is closed after Sender.Stop is called and all flow has been dispatched
func NewSenderWithNewSiteAndDevice ¶
func NewSenderWithNewSiteAndDevice(siteAndDevice *api.SiteAndDeviceCreate, errors chan<- error, cfg *Config) (*Sender, error)
NewSenderWithNewSiteAndDevice creates a new device and site then returns a flow Sender for that newly created device
func NewSenderWithNewSiteAndDeviceWithErrors ¶
func NewSenderWithNewSiteAndDeviceWithErrors(siteAndDevice *api.SiteAndDeviceCreate, cfg *Config) (*Sender, <-chan error, error)
NewSenderWithNewSiteAndDeviceWithErrors is the same as NewSenderWithNewSiteAndDeviceWithErrors except rather than passing in a channel to receive errors, a channel is returned by the function. The channel is closed after Sender.Stop is called and all flow has been dispatched
Source Files
Directories