graphite

README

The Graphite Input

A Note On UDP/IP OS Buffer Sizes

If you're using UDP input and running Linux or FreeBSD, please adjust your UDP buffer size limit, see here for more details.

Configuration

Each Graphite input allows the binding address, target database, and protocol to be set. If the database does not exist, it will be created automatically when the input is initialized. The write-consistency-level can also be set. If any write operations do not meet the configured consistency guarantees, an error will occur and the data will not be indexed. The default consistency-level is ONE.

Each Graphite input also performs internal batching of the points it receives, as batched writes to the database are more efficient. The default batch size is 1000, pending batch factor is 5, with a batch timeout of 1 second. This means the input will write batches of maximum size 1000, but if a batch has not reached 1000 points within 1 second of the first point being added to a batch, it will emit that batch regardless of size. The pending batch factor controls how many batches can be in memory at once, allowing the input to transmit a batch, while still building other batches.

Parsing Metrics

The Graphite plugin allows measurements to be saved using the Graphite line protocol. By default, enabling the Graphite plugin will allow you to collect metrics and store them using the metric name as the measurement. If you send a metric named servers.localhost.cpu.loadavg.10, it will store the full metric name as the measurement with no extracted tags.

While this default setup works, it is not the ideal way to store measurements in InfluxDB since it does not take advantage of tags. It also will not perform optimally with large dataset sizes since queries will be forced to use regexes which is known to not scale well.

To extract tags from metrics, one or more templates must be configured to parse metrics into tags and measurements.

Templates

Templates allow matching parts of a metric name to be used as tag keys in the stored metric. They have a similar format to Graphite metric names. The values in between the separators are used as the tag keys. The location of the tag key that matches the same position as the Graphite metric section is used as the value. If there is no value, the Graphite portion is skipped.

The special value measurement is used to define the measurement name. It can have a trailing * to indicate that the remainder of the metric should be used. If a measurement is not specified, the full metric name is used.

Basic Matching

servers.localhost.cpu.loadavg.10

• Template: .host.resource.measurement*
• Output: measurement =loadavg.10 tags =host=localhost resource=cpu

Multiple Measurement & Tags Matching

The measurement can be specified multiple times in a template to provide more control over the measurement name. Tags can also be matched multiple times. Multiple values will be joined together using the Separator config variable. By default, this value is ..

servers.localhost.localdomain.cpu.cpu0.user

• Template: .host.host.measurement.cpu.measurement
• Output: measurement = cpu.user tags = host=localhost.localdomain cpu=cpu0

Since . requires queries on measurements to be double-quoted, you may want to set this to _ to simplify querying parsed metrics.

servers.localhost.cpu.cpu0.user

• Separator: _
• Template: .host.measurement.cpu.measurement
• Output: measurement = cpu_user tags = host=localhost cpu=cpu0

Adding Tags

Additional tags can be added to a metric if they don't exist on the received metric. You can add additional tags by specifying them after the pattern. Tags have the same format as the line protocol. Multiple tags are separated by commas.

servers.localhost.cpu.loadavg.10

• Template: .host.resource.measurement* region=us-west,zone=1a
• Output: measurement = loadavg.10 tags = host=localhost resource=cpu region=us-west zone=1a

Fields

A field key can be specified by using the keyword field. By default if no field keyword is specified then the metric will be written to a field named value.

The field key can also be derived from the second "half" of the input metric-name by specifying field* (eg measurement.measurement.field*). This cannot be used in conjunction with "measurement*"!

It's possible to amend measurement metrics with additional fields, e.g:

Input:

sensu.metric.net.server0.eth0.rx_packets 461295119435 1444234982
sensu.metric.net.server0.eth0.tx_bytes 1093086493388480 1444234982
sensu.metric.net.server0.eth0.rx_bytes 1015633926034834 1444234982
sensu.metric.net.server0.eth0.tx_errors 0 1444234982
sensu.metric.net.server0.eth0.rx_errors 0 1444234982
sensu.metric.net.server0.eth0.tx_dropped 0 1444234982
sensu.metric.net.server0.eth0.rx_dropped 0 1444234982

With template:

sensu.metric.* ..measurement.host.interface.field

Becomes database entry:

> select * from net
name: net
---------
time      host  interface rx_bytes    rx_dropped  rx_errors rx_packets    tx_bytes    tx_dropped  tx_errors
1444234982000000000 server0  eth0    1.015633926034834e+15 0   0   4.61295119435e+11 1.09308649338848e+15  0 0

Multiple Templates

One template may not match all metrics. For example, using multiple plugins with diamond will produce metrics in different formats. If you need to use multiple templates, you'll need to define a prefix filter that must match before the template can be applied.

Filters

Filters have a similar format to templates but work more like wildcard expressions. When multiple filters would match a metric, the more specific one is chosen. Filters are configured by adding them before the template.

For example,

servers.localhost.cpu.loadavg.10
servers.host123.elasticsearch.cache_hits 100
servers.host456.mysql.tx_count 10
servers.host789.prod.mysql.tx_count 10

• servers.* would match all values
• servers.*.mysql would match servers.host456.mysql.tx_count 10
• servers.localhost.* would match servers.localhost.cpu.loadavg
• servers.*.*.mysql would match servers.host789.prod.mysql.tx_count 10

Default Templates

If no template filters are defined or you want to just have one basic template, you can define a default template. This template will apply to any metric that has not already matched a filter.

dev.http.requests.200
prod.myapp.errors.count
dev.db.queries.count

• env.app.measurement* would create
  • measurement=requests.200 tags=env=dev,app=http
  • measurement= errors.count tags=env=prod,app=myapp
  • measurement=queries.count tags=env=dev,app=db

Global Tags

If you need to add the same set of tags to all metrics, you can define them globally at the plugin level and not within each template description.

Minimal Config

[[graphite]]
  enabled = true
  # bind-address = ":2003"
  # protocol = "tcp"
  # consistency-level = "one"

  ### If matching multiple measurement files, this string will be used to join the matched values.
  # separator = "."

  ### Default tags that will be added to all metrics.  These can be overridden at the template level
  ### or by tags extracted from metric
  # tags = ["region=us-east", "zone=1c"]

  ### Each template line requires a template pattern.  It can have an optional
  ### filter before the template and separated by spaces.  It can also have optional extra
  ### tags following the template.  Multiple tags should be separated by commas and no spaces
  ### similar to the line protocol format.  The can be only one default template.
  # templates = [
  #   "*.app env.service.resource.measurement",
  #   # Default template
  #   "server.*",
 #]

Customized Config

[[graphite]]
   enabled = true
   separator = "_"
   tags = ["region=us-east", "zone=1c"]
   templates = [
     # filter + template
     "*.app env.service.resource.measurement",

     # filter + template + extra tag
     "stats.* .host.measurement* region=us-west,agent=sensu",

     # filter + template with field key
     "stats.* .host.measurement.field",

     # default template. Ignore the first Graphite component "servers"
     ".measurement*",
 ]

Two Graphite Listeners, UDP & TCP, Config

[[graphite]]
  enabled = true
  bind-address = ":2003"
  protocol = "tcp"
  # consistency-level = "one"

[[graphite]]
  enabled = true
  bind-address = ":2004" # the bind address
  protocol = "udp" # protocol to read via
  udp-read-buffer = 8388608 # (8*1024*1024) UDP read buffer size

Documentation

Index

• Constants
• Variables
• func NewTemplate(pattern string, defaultTags models.Tags, separator string) (*template, error)
• type Config
  • func NewConfig() Config
  • func (c *Config) DefaultTags() models.Tags
  • func (c *Config) Validate() error
  • func (c *Config) WithDefaults() *Config
• type Options
• type Parser
  • func NewParser(templates []string, defaultTags models.Tags) (*Parser, error)
  • func NewParserWithOptions(options Options) (*Parser, error)
  • func (p *Parser) ApplyTemplate(line string) (string, map[string]string, string, error)
  • func (p *Parser) Parse(line string) (models.Point, error)
• type Service
  • func NewService(c Config) (*Service, error)
  • func (s *Service) Addr() net.Addr
  • func (s *Service) Close() error
  • func (s *Service) Closed() bool
  • func (s *Service) Diagnostics() (*diagnostics.Diagnostics, error)
  • func (s *Service) Open() error
  • func (s *Service) Statistics(tags map[string]string) []models.Statistic
  • func (s *Service) WithLogger(log zap.Logger)
• type Statistics
• type UnsupportedValueError
  • func (err *UnsupportedValueError) Error() string

Constants

const (
	// DefaultBindAddress is the default binding interface if none is specified.
	DefaultBindAddress = ":2003"

	// DefaultDatabase is the default database if none is specified.
	DefaultDatabase = "graphite"

	// DefaultProtocol is the default IP protocol used by the Graphite input.
	DefaultProtocol = "tcp"

	// DefaultConsistencyLevel is the default write consistency for the Graphite input.
	DefaultConsistencyLevel = "one"

	// DefaultSeparator is the default join character to use when joining multiple
	// measurement parts in a template.
	DefaultSeparator = "."

	// DefaultBatchSize is the default write batch size.
	DefaultBatchSize = 5000

	// DefaultBatchPending is the default number of pending write batches.
	DefaultBatchPending = 10

	// DefaultBatchTimeout is the default Graphite batch timeout.
	DefaultBatchTimeout = time.Second

	// DefaultUDPReadBuffer is the default buffer size for the UDP listener.
	// Sets the size of the operating system's receive buffer associated with
	// the UDP traffic. Keep in mind that the OS must be able
	// to handle the number set here or the UDP listener will error and exit.
	//
	// DefaultReadBuffer = 0 means to use the OS default, which is usually too
	// small for high UDP performance.
	//
	// Increasing OS buffer limits:
	//     Linux:      sudo sysctl -w net.core.rmem_max=<read-buffer>
	//     BSD/Darwin: sudo sysctl -w kern.ipc.maxsockbuf=<read-buffer>
	DefaultUDPReadBuffer = 0
)

Variables

var (
	MinDate = time.Date(1901, 12, 13, 0, 0, 0, 0, time.UTC)
	MaxDate = time.Date(2038, 1, 19, 0, 0, 0, 0, time.UTC)
)

Minimum and maximum supported dates for timestamps.

Functions

func NewTemplate

func NewTemplate(pattern string, defaultTags models.Tags, separator string) (*template, error)

NewTemplate returns a new template ensuring it has a measurement specified.

Types

type Config

type Config struct {
	Enabled          bool          `toml:"enabled"`
	BindAddress      string        `toml:"bind-address"`
	Database         string        `toml:"database"`
	RetentionPolicy  string        `toml:"retention-policy"`
	Protocol         string        `toml:"protocol"`
	BatchSize        int           `toml:"batch-size"`
	BatchPending     int           `toml:"batch-pending"`
	BatchTimeout     toml.Duration `toml:"batch-timeout"`
	ConsistencyLevel string        `toml:"consistency-level"`
	Templates        []string      `toml:"templates"`
	Tags             []string      `toml:"tags"`
	Separator        string        `toml:"separator"`
	UDPReadBuffer    int           `toml:"udp-read-buffer"`
}

Config represents the configuration for Graphite endpoints.

func NewConfig

func NewConfig() Config

NewConfig returns a new instance of Config with defaults.

func (*Config) DefaultTags

func (c *Config) DefaultTags() models.Tags

DefaultTags returns the config's tags.

func (*Config) Validate

func (c *Config) Validate() error

Validate validates the config's templates and tags.

func (*Config) WithDefaults

func (c *Config) WithDefaults() *Config

WithDefaults takes the given config and returns a new config with any required default values set.

type Options

type Options struct {
	Separator   string
	Templates   []string
	DefaultTags models.Tags
}

Options are configurable values that can be provided to a Parser

type Parser

type Parser struct {
	// contains filtered or unexported fields
}

Parser encapsulates a Graphite Parser.

func NewParser

func NewParser(templates []string, defaultTags models.Tags) (*Parser, error)

NewParser returns a GraphiteParser instance.

func NewParserWithOptions

func NewParserWithOptions(options Options) (*Parser, error)

NewParserWithOptions returns a graphite parser using the given options

func (*Parser) ApplyTemplate

func (p *Parser) ApplyTemplate(line string) (string, map[string]string, string, error)

ApplyTemplate extracts the template fields from the given line and returns the measurement name and tags.

func (*Parser) Parse

func (p *Parser) Parse(line string) (models.Point, error)

Parse performs Graphite parsing of a single line.

type Service

type Service struct {
	Monitor interface {
		RegisterDiagnosticsClient(name string, client diagnostics.Client)
		DeregisterDiagnosticsClient(name string)
	}
	PointsWriter interface {
		WritePoints(database, retentionPolicy string, consistencyLevel models.ConsistencyLevel, points []models.Point) error
	}
	MetaClient interface {
		CreateDatabase(name string) (*meta.DatabaseInfo, error)
		CreateDatabaseWithRetentionPolicy(name string, spec *meta.RetentionPolicySpec) (*meta.DatabaseInfo, error)
		CreateRetentionPolicy(database string, spec *meta.RetentionPolicySpec, makeDefault bool) (*meta.RetentionPolicyInfo, error)
		Database(name string) *meta.DatabaseInfo
		RetentionPolicy(database, name string) (*meta.RetentionPolicyInfo, error)
	}
	// contains filtered or unexported fields
}

Service represents a Graphite service.

func NewService

func NewService(c Config) (*Service, error)

NewService returns an instance of the Graphite service.

func (*Service) Addr

func (s *Service) Addr() net.Addr

Addr returns the address the Service binds to.

func (*Service) Close

func (s *Service) Close() error

Close stops all data processing on the Graphite input.

func (*Service) Closed

func (s *Service) Closed() bool

Closed returns true if the service is currently closed.

func (*Service) Diagnostics

func (s *Service) Diagnostics() (*diagnostics.Diagnostics, error)

Diagnostics returns diagnostics of the graphite service.

func (*Service) Open

func (s *Service) Open() error

Open starts the Graphite input processing data.

func (*Service) Statistics

func (s *Service) Statistics(tags map[string]string) []models.Statistic

Statistics returns statistics for periodic monitoring.

func (*Service) WithLogger

func (s *Service) WithLogger(log zap.Logger)

type Statistics

type Statistics struct {
	PointsReceived      int64
	BytesReceived       int64
	PointsParseFail     int64
	PointsNaNFail       int64
	BatchesTransmitted  int64
	PointsTransmitted   int64
	BatchesTransmitFail int64
	ActiveConnections   int64
	HandledConnections  int64
}

Statistics maintains statistics for the graphite service.

type UnsupportedValueError

type UnsupportedValueError struct {
	Field string
	Value float64
}

An UnsupportedValueError is returned when a parsed value is not supported.

func (*UnsupportedValueError) Error

func (err *UnsupportedValueError) Error() string