Skip to content

Commit

Permalink
0.3.0: update README and documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@sparrc
sparrc committed Jan 8, 2016
1 parent 9c5db10 commit ac13af0
Show file tree
Hide file tree
Showing 4 changed files with 141 additions and 97 deletions.
7 changes: 5 additions & 2 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,11 @@ directory.
- **breaking change** `jolokia` plugin: must use global tag/drop/pass parameters
for configuration.
- **breaking change** `twemproxy` plugin: `prefix` option removed.
- **breaking change** `procstat` cpu measurements are now prepended with `cpu_time_` instead of
only `cpu_`
- **breaking change** `procstat` cpu measurements are now prepended with `cpu_time_`
instead of only `cpu_`
- **breaking change** some command-line flags have been renamed to separate words.
`-configdirectory` -> `-config-directory`, `-filter` -> `-input-filter`,
`-outputfilter` -> `-output-filter`
- The prometheus plugin schema has not been changed (measurements have not been
aggregated).

Expand Down
48 changes: 32 additions & 16 deletions CONFIGURATION.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Telegraf Configuration

## Generating a config file
## Generating a Configuration File

A default Telegraf config file can be generated using the `-sample-config` flag,
like this: `telegraf -sample-config`
Expand All @@ -9,7 +9,20 @@ To generate a file with specific inputs and outputs, you can use the
`-input-filter` and `-output-filter` flags, like this:
`telegraf -sample-config -input-filter cpu:mem:net:swap -output-filter influxdb:kafka`

## Plugin Configuration
## Telegraf Agent Configuration

Telegraf has a few options you can configure under the `agent` section of the
config.

* **hostname**: The hostname is passed as a tag. By default this will be
the value returned by `hostname` on the machine running Telegraf.
You can override that value here.
* **interval**: How often to gather metrics. Uses a simple number +
unit parser, e.g. "10s" for 10 seconds or "5m" for 5 minutes.
* **debug**: Set to true to gather and send metrics to STDOUT as well as
InfluxDB.

## Input Configuration

There are some configuration options that are configurable per plugin:

Expand All @@ -22,7 +35,7 @@ There are some configuration options that are configurable per plugin:
global interval, but if one particular plugin should be run less or more often,
you can configure that here.

### Plugin Filters
### Input Filters

There are also filters that can be configured per plugin:

Expand All @@ -36,7 +49,7 @@ match against the tag name, and if it matches the measurement is emitted.
* **tagdrop**: The inverse of tagpass. If a tag matches, the measurement is not
emitted. This is tested on measurements that have passed the tagpass test.

### Plugin Configuration Examples
### Input Configuration Examples

This is a full working config that will output CPU data to an InfluxDB instance
at 192.168.59.103:8086, tagging measurements with dc="denver-1". It will output
Expand All @@ -57,19 +70,19 @@ fields which begin with `time_`.
database = "telegraf" # required.
precision = "s"

# PLUGINS
[plugins]
# INPUTS
[inputs]
[[inputs.cpu]]
percpu = true
totalcpu = false
# filter all fields beginning with 'time_'
drop = ["time_*"]
```

### Plugin Config: tagpass and tagdrop
### Input Config: tagpass and tagdrop

```toml
[plugins]
[inputs]
[[inputs.cpu]]
percpu = true
totalcpu = false
Expand All @@ -88,7 +101,7 @@ fields which begin with `time_`.
path = [ "/opt", "/home*" ]
```

### Plugin Config: pass and drop
### Input Config: pass and drop

```toml
# Drop all metrics for guest & steal CPU usage
Expand All @@ -102,7 +115,7 @@ fields which begin with `time_`.
pass = ["inodes*"]
```

### Plugin config: prefix, suffix, and override
### Input config: prefix, suffix, and override

This plugin will emit measurements with the name `cpu_total`

Expand All @@ -122,7 +135,7 @@ This will emit measurements with the name `foobar`
totalcpu = true
```

### Plugin config: tags
### Input config: tags

This plugin will emit measurements with two additional tags: `tag1=foo` and
`tag2=bar`
Expand All @@ -136,10 +149,12 @@ This plugin will emit measurements with two additional tags: `tag1=foo` and
tag2 = "bar"
```

### Multiple plugins of the same type
### Multiple inputs of the same type

Additional plugins (or outputs) of the same type can be specified,
just define more instances in the config file:
Additional inputs (or outputs) of the same type can be specified,
just define more instances in the config file. It is highly recommended that
you utilize `name_override`, `name_prefix`, or `name_suffix` config options
to avoid measurement collisions:

```toml
[[inputs.cpu]]
Expand All @@ -149,6 +164,7 @@ just define more instances in the config file:
[[inputs.cpu]]
percpu = true
totalcpu = false
name_override = "percpu_usage"
drop = ["cpu_time*"]
```

Expand All @@ -158,8 +174,8 @@ Telegraf also supports specifying multiple output sinks to send data to,
configuring each output sink is different, but examples can be
found by running `telegraf -sample-config`.

Outputs also support the same configurable options as plugins
(pass, drop, tagpass, tagdrop), added in 0.2.4
Outputs also support the same configurable options as inputs
(pass, drop, tagpass, tagdrop)

```toml
[[outputs.influxdb]]
Expand Down
121 changes: 62 additions & 59 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,23 +1,35 @@
# Telegraf - A native agent for InfluxDB [![Circle CI](https://circleci.com/gh/influxdata/telegraf.svg?style=svg)](https://circleci.com/gh/influxdata/telegraf)
# Telegraf [![Circle CI](https://circleci.com/gh/influxdata/telegraf.svg?style=svg)](https://circleci.com/gh/influxdata/telegraf)

Telegraf is an agent written in Go for collecting metrics from the system it's
running on, or from other services, and writing them into InfluxDB.
running on, or from other services, and writing them into InfluxDB or other
[outputs](https://github.com/influxdata/telegraf#supported-output-plugins).

Design goals are to have a minimal memory footprint with a plugin system so
that developers in the community can easily add support for collecting metrics
from well known services (like Hadoop, Postgres, or Redis) and third party
APIs (like Mailchimp, AWS CloudWatch, or Google Analytics).

We'll eagerly accept pull requests for new plugins and will manage the set of
plugins that Telegraf supports. See the
[contributing guide](CONTRIBUTING.md) for instructions on
writing new inputs.
New input and output plugins are designed to be easy to contribute,
we'll eagerly accept pull
requests and will manage the set of plugins that Telegraf supports.
See the [contributing guide](CONTRIBUTING.md) for instructions on writing
new plugins.

## Installation:

NOTE: Telegraf 0.3.x is **not** backwards-compatible with previous versions of
telegraf, both in the database layout and the configuration file. 0.2.x will
continue to be supported, see below for download links.

TODO: link to blog post about 0.3.x changes.

### Linux deb and rpm packages:

Latest:
* http://get.influxdb.org/telegraf/telegraf_0.3.0_amd64.deb
* http://get.influxdb.org/telegraf/telegraf-0.3.0-1.x86_64.rpm

0.2.x:
* http://get.influxdb.org/telegraf/telegraf_0.2.4_amd64.deb
* http://get.influxdb.org/telegraf/telegraf-0.2.4-1.x86_64.rpm

Expand All @@ -33,6 +45,11 @@ controlled via `systemctl [action] telegraf`
### Linux binaries:

Latest:
* http://get.influxdb.org/telegraf/telegraf_linux_amd64_0.3.0.tar.gz
* http://get.influxdb.org/telegraf/telegraf_linux_386_0.3.0.tar.gz
* http://get.influxdb.org/telegraf/telegraf_linux_arm_0.3.0.tar.gz

0.2.x:
* http://get.influxdb.org/telegraf/telegraf_linux_amd64_0.2.4.tar.gz
* http://get.influxdb.org/telegraf/telegraf_linux_386_0.2.4.tar.gz
* http://get.influxdb.org/telegraf/telegraf_linux_arm_0.2.4.tar.gz
Expand All @@ -51,32 +68,6 @@ brew update
brew install telegraf
```

### Version 0.3.0 Beta

Version 0.3.0 will introduce many new breaking changes to Telegraf. For starters,
plugin measurements will be aggregated into fields. This means that there will no
longer be a `cpu_usage_idle` measurement, there will be a `cpu` measurement with
a `usage_idle` field.

There will also be config file changes, meaning that your 0.2.x Telegraf config
files will no longer work properly. It is recommended that you use the
`-sample-config` flag to generate a new config file to see what the changes are.
You can also read the
[0.3.0 configuration guide](https://github.com/influxdb/telegraf/blob/0.3.0/CONFIGURATION.md)
to see some of the new features and options available.

You can read more about the justifications for the aggregated measurements
[here](https://github.com/influxdb/telegraf/issues/152), and a more detailed
breakdown of the work [here](https://github.com/influxdb/telegraf/pull/437).
Once we're closer to a full release, there will be a detailed blog post
explaining all the changes.

* http://get.influxdb.org/telegraf/telegraf_0.3.0-beta2_amd64.deb
* http://get.influxdb.org/telegraf/telegraf-0.3.0_beta2-1.x86_64.rpm
* http://get.influxdb.org/telegraf/telegraf_linux_amd64_0.3.0-beta2.tar.gz
* http://get.influxdb.org/telegraf/telegraf_linux_386_0.3.0-beta2.tar.gz
* http://get.influxdb.org/telegraf/telegraf_linux_arm_0.3.0-beta2.tar.gz

### From Source:

Telegraf manages dependencies via [gdm](https://github.com/sparrc/gdm),
Expand All @@ -91,37 +82,49 @@ if you don't have it already. You also must build with golang version 1.4+.

### How to use it:

* Run `telegraf -sample-config > telegraf.conf` to create an initial configuration.
* Or run `telegraf -sample-config -input-filter cpu:mem -output-filter influxdb > telegraf.conf`.
to create a config file with only CPU and memory plugins defined, and InfluxDB
output defined.
* Edit the configuration to match your needs.
* Run `telegraf -config telegraf.conf -test` to output one full measurement
sample to STDOUT. NOTE: you may want to run as the telegraf user if you are using
the linux packages `sudo -u telegraf telegraf -config telegraf.conf -test`
* Run `telegraf -config telegraf.conf` to gather and send metrics to configured outputs.
* Run `telegraf -config telegraf.conf -input-filter system:swap`.
to run telegraf with only the system & swap plugins defined in the config.

## Telegraf Options

Telegraf has a few options you can configure under the `agent` section of the
config.

* **hostname**: The hostname is passed as a tag. By default this will be
the value returned by `hostname` on the machine running Telegraf.
You can override that value here.
* **interval**: How often to gather metrics. Uses a simple number +
unit parser, e.g. "10s" for 10 seconds or "5m" for 5 minutes.
* **debug**: Set to true to gather and send metrics to STDOUT as well as
InfluxDB.
```console
$ telegraf -help
Telegraf, The plugin-driven server agent for reporting metrics into InfluxDB

Usage:

telegraf <flags>

The flags are:

-config <file> configuration file to load
-test gather metrics once, print them to stdout, and exit
-sample-config print out full sample configuration to stdout
-config-directory directory containing additional *.conf files
-input-filter filter the input plugins to enable, separator is :
-output-filter filter the output plugins to enable, separator is :
-usage print usage for a plugin, ie, 'telegraf -usage mysql'
-version print the version to stdout

Examples:

# generate a telegraf config file:
telegraf -sample-config > telegraf.conf

# generate config with only cpu input & influxdb output plugins defined
telegraf -sample-config -input-filter cpu -output-filter influxdb

# run a single telegraf collection, outputing metrics to stdout
telegraf -config telegraf.conf -test

# run telegraf with all plugins defined in config file
telegraf -config telegraf.conf

# run telegraf, enabling the cpu & memory input, and influxdb output plugins
telegraf -config telegraf.conf -input-filter cpu:mem -output-filter influxdb
```

## Configuration

See the [configuration guide](CONFIGURATION.md) for a rundown of the more advanced
configuration options.

## Supported Plugins
## Supported Input Plugins

**You can view usage instructions for each plugin by running**
`telegraf -usage <pluginname>`.
Expand Down Expand Up @@ -166,7 +169,7 @@ Telegraf currently has support for collecting metrics from:
* diskio
* swap

## Supported Service Plugins
## Supported Input Service Plugins

Telegraf can collect metrics via the following services:

Expand All @@ -176,7 +179,7 @@ Telegraf can collect metrics via the following services:
We'll be adding support for many more over the coming months. Read on if you
want to add support for another service or third-party API.

## Supported Outputs
## Supported Output Plugins

* influxdb
* nsq
Expand Down
Loading

0 comments on commit ac13af0

Please sign in to comment.