Skip to content

write_graphite plugin
Plugin name write_graphite
Type write
Callbacks write
Status deprecated
Since 4.9
Copyright 2010 Gregory Szorc
Configuration collectd.conf(5)

The Carbon plugin writes data collected by collectd to Carbon, Graphite's storage API. It can be found at indygreg/collectd-carbon

In essence, this is an alternative writer to RRD. Graphite's web UI has very compelling features, such as interactive graphs and dynamic functions.

For version-5.1 and later using the Write Graphite plugin is highly recommended.

Synopsis

 <LoadPlugin "python">
   Globals true
 </LoadPlugin>

 Import "carbon_writer"
 <Module carbon_writer>
   LineReceiverHost "myhost.mydomain"
   LineReceiverPort 2003
   DeriveCounters true
   TypesDB "/usr/share/collectd/types.db"
 </Module>

Example graphs

Uses Graphite for rendering. See http://graphite.wikidot.com/screen-shots for some examples.

Caveats

Globals

If using versions 4.9 or 4.10, be sure to load the Python plugin with the Globals option set to true. Otherwise the Carbon module will not work properly. The appropriate configuration for loading the Python plugin is:

 <LoadPlugin "python">
   Globals true
 </LoadPlugin>

Versions before 4.9 don't support this option; it's possible the Carbon plugin doesn't work with these versions of collectd. Version-5.0 and later will automatically set this flag for the Python plugin, so the above syntax isn't required but still legal.

See also

  • Write Graphite plugin C-based plugin to send data to Graphite / Carbon efficiently. Included in collectd since version-5.1.

Dependencies

Configuration

Configuration options · from collectd.conf(5)

See this section in the full configuration reference

The write_graphite plugin writes data to Graphite, an open-source metrics storage and graphing project. The plugin connects to Carbon, the data layer of Graphite, via TCP or UDP and sends data via the "line based" protocol (per default using portE<nbsp>2003). The data will be sent in blocks of at most 1428 bytes to minimize the number of network packets.

Synopsis:

<Plugin write_graphite>
  <Node "example">
    Host "localhost"
    Port "2003"
    Protocol "tcp"
    LogSendErrors true
    Prefix "collectd"
    UseTags false
    ReverseHost false
  </Node>
</Plugin>

The configuration consists of one or more <Node Name> blocks. Inside the Node blocks, the following options are recognized:

Host Address
Hostname or address to connect to. Defaults to localhost.
Port Service
Service name or port number to connect to. Defaults to 2003.
Protocol String
Protocol to use when connecting to Graphite. Defaults to tcp.
ReconnectInterval Seconds
When set to non-zero, forces the connection to the Graphite backend to be closed and re-opend periodically. This behavior is desirable in environments where the connection to the Graphite backend is done through load balancers, for example. When set to zero, the default, the connetion is kept open for as long as possible.
LogSendErrors false|true
If set to true (the default), logs errors when sending data to Graphite. If set to false, it will not log the errors. This is especially useful when using Protocol UDP since many times we want to use the "fire-and-forget" approach and logging errors fills syslog with unneeded messages.
Prefix String

When UseTags is false, Prefix value is added in front of the host name. When UseTags is true, Prefix value is added in front of series name.

Dots and whitespace are not escaped in this string (see EscapeCharacter below).

Postfix String

When UseTags is false, Postfix value appended to the host name. When UseTags is true, Postgix value appended to the end of series name (before the first ; that separates the name from the tags).

Dots and whitespace are not escaped in this string (see EscapeCharacter below).

EscapeCharacter Char
Carbon uses the dot (.) as escape character and doesn't allow whitespace in the identifier. The EscapeCharacter option determines which character dots, whitespace and control characters are replaced with. Defaults to underscore (_).
StoreRates false|true
If set to true (the default), convert counter values to rates. If set to false counter values are stored as is, i. e. as an increasing integer number.
SeparateInstances false|true

If set to true, the plugin instance and type instance will be in their own path component, for example host.cpu.0.cpu.idle. If set to false (the default), the plugin and plugin instance (and likewise the type and type instance) are put into one component, for example host.cpu-0.cpu-idle.

Option value is not used when UseTags is true.

AlwaysAppendDS false|true
If set to true, append the name of the Data Source (DS) to the "metric" identifier. If set to false (the default), this is only done when there is more than one DS.
PreserveSeparator false|true

If set to false (the default) the . (dot) character is replaced with EscapeCharacter. Otherwise, if set to true, the . (dot) character is preserved, i.e. passed through.

Option value is not used when UseTags is true.

DropDuplicateFields false|true
If set to true, detect and remove duplicate components in Graphite metric names. For example, the metric name host.load.load.shortterm will be shortened to host.load.shortterm.
UseTags false|true

If set to true, Graphite metric names will be generated as tagged series. This allows for much more flexibility than the traditional hierarchical layout.

Example: test.single;host=example.com;plugin=test;plugin_instance=foo;type=single;type_instance=bar

You can use Postfix option to add more tags by specifying it like ;tag1=value1;tag2=value2. Note what tagging support was added since Graphite version 1.1.x.

If set to true, the SeparateInstances and PreserveSeparator settings are not used.

Default value: false.

ReverseHost false|true

If set to true, the (dot separated) parts of the host field of the value list will be rewritten in reverse order. The rewrite happens before special characters are replaced with the EscapeCharacter.

This option might be convenient if the metrics are presented with Graphite in a DNS like tree structure (probably without replacing dots in hostnames).

Example: Hostname "node3.cluster1.example.com" LoadPlugin "cpu" LoadPlugin "write_graphite" <Plugin "write_graphite"> <Node "graphite.example.com"> EscapeCharacter "." ReverseHost true </Node> </Plugin>

result on the wire: com.example.cluster1.node3.cpu-0.cpu-idle 99.900993 1543010932

Default value: false.