diff --git a/CONFIGURATION.md b/CONFIGURATION.md index ee79da98a..421fe4f72 100644 --- a/CONFIGURATION.md +++ b/CONFIGURATION.md @@ -2,27 +2,46 @@ ## Generating a Configuration File -A default Telegraf config file can be generated using the `-sample-config` flag, -like this: `telegraf -sample-config` +A default Telegraf config file can be generated using the -sample-config flag: +`telegraf -sample-config > telegraf.conf` To generate a file with specific inputs and outputs, you can use the -`-input-filter` and `-output-filter` flags, like this: +-input-filter and -output-filter flags: `telegraf -sample-config -input-filter cpu:mem:net:swap -output-filter influxdb:kafka` -## Telegraf Agent Configuration +## `[tags]` Configuration + +Global tags can be specific in the `[tags]` section of the config file in +key="value" format. All metrics being gathered on this host will be tagged +with the tags specified here. + +## `[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. +* **interval**: Default data collection interval for all inputs +* **round_interval**: Rounds collection interval to 'interval' +ie, if interval="10s" then always collect on :00, :10, :20, etc. +* **metric_buffer_limit**: Telegraf will cache metric_buffer_limit metrics +for each output, and will flush this buffer on a successful write. +* **collection_jitter**: Collection jitter is used to jitter +the collection by a random amount. +Each plugin will sleep for a random time within jitter before collecting. +This can be used to avoid many plugins querying things like sysfs at the +same time, which can have a measurable effect on the system. +* **flush_interval**: Default data flushing interval for all outputs. +You should not set this below +interval. Maximum flush_interval will be flush_interval + flush_jitter +* **flush_jitter**: Jitter the flush interval by a random amount. +This is primarily to avoid +large write spikes for users running a large number of telegraf instances. +ie, a jitter of 5s and flush_interval 10s means flushes will happen every 10-15s. +* **debug**: Run telegraf in debug mode. +* **quiet**: Run telegraf in quiet mode. +* **hostname**: Override default hostname, if empty use os.Hostname(). -## Input Configuration +## `[inputs.xxx]` Configuration There are some configuration options that are configurable per input: @@ -35,7 +54,7 @@ There are some configuration options that are configurable per input: global interval, but if one particular input should be run less or more often, you can configure that here. -### Input Filters +#### Input Filters There are also filters that can be configured per input: @@ -49,7 +68,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. -### Input 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 @@ -77,7 +96,7 @@ fields which begin with `time_`. drop = ["time_*"] ``` -### Input Config: tagpass and tagdrop +#### Input Config: tagpass and tagdrop ```toml [[inputs.cpu]] @@ -98,7 +117,7 @@ fields which begin with `time_`. path = [ "/opt", "/home*" ] ``` -### Input Config: pass and drop +#### Input Config: pass and drop ```toml # Drop all metrics for guest & steal CPU usage @@ -112,7 +131,7 @@ fields which begin with `time_`. pass = ["inodes*"] ``` -### Input config: prefix, suffix, and override +#### Input config: prefix, suffix, and override This plugin will emit measurements with the name `cpu_total` @@ -132,7 +151,7 @@ This will emit measurements with the name `foobar` totalcpu = true ``` -### Input config: tags +#### Input config: tags This plugin will emit measurements with two additional tags: `tag1=foo` and `tag2=bar` @@ -146,7 +165,7 @@ This plugin will emit measurements with two additional tags: `tag1=foo` and tag2 = "bar" ``` -### Multiple inputs of the same type +#### Multiple inputs of the same type Additional inputs (or outputs) of the same type can be specified, just define more instances in the config file. It is highly recommended that @@ -165,7 +184,7 @@ to avoid measurement collisions: drop = ["cpu_time*"] ``` -## Output Configuration +## `[outputs.xxx]` Configuration Telegraf also supports specifying multiple output sinks to send data to, configuring each output sink is different, but examples can be diff --git a/etc/telegraf.conf b/etc/telegraf.conf index 9871ae7bc..7cafa9512 100644 --- a/etc/telegraf.conf +++ b/etc/telegraf.conf @@ -1,27 +1,18 @@ # Telegraf configuration # Telegraf is entirely plugin driven. All metrics are gathered from the -# declared inputs. +# declared inputs, and sent to the declared outputs. -# Even if a plugin has no configuration, it must be declared in here -# to be active. Declaring a plugin means just specifying the name -# as a section with no variables. To deactivate a plugin, comment -# out the name and any variables. +# Plugins must be declared in here to be active. +# To deactivate a plugin, comment out the name and any variables. -# Use 'telegraf -config telegraf.toml -test' to see what metrics a config +# Use 'telegraf -config telegraf.conf -test' to see what metrics a config # file would generate. -# One rule that plugins conform to is wherever a connection string -# can be passed, the values '' and 'localhost' are treated specially. -# They indicate to the plugin to use their own builtin configuration to -# connect to the local system. - -# NOTE: The configuration has a few required parameters. They are marked -# with 'required'. Be sure to edit those to make this configuration work. - -# Tags can also be specified via a normal map, but only one form at a time: +# Global tags can be specified here in key="value" format. [tags] - # dc = "us-east-1" + # dc = "us-east-1" # will tag all metrics with dc=us-east-1 + # rack = "1a" # Configuration for telegraf agent [agent] @@ -97,9 +88,9 @@ # By default, telegraf will gather stats for all devices including # disk partitions. # Setting devices will restrict the stats to the specified devices. - # Devices=["sda","sdb"] + # devices = ["sda", "sdb"] # Uncomment the following line if you do not need disk serial numbers. - # SkipSerialNumber = true + # skip_serial_number = true # Read metrics about memory usage [[inputs.mem]] diff --git a/internal/config/config.go b/internal/config/config.go index 5f97f8350..feb472ab1 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -136,9 +136,10 @@ var header = `# Telegraf configuration # Use 'telegraf -config telegraf.conf -test' to see what metrics a config # file would generate. -# Tags can also be specified via a normal map, but only one form at a time: +# Global tags can be specified here in key="value" format. [tags] - # dc = "us-east-1" + # dc = "us-east-1" # will tag all metrics with dc=us-east-1 + # rack = "1a" # Configuration for telegraf agent [agent] diff --git a/plugins/inputs/snmp/snmp_test.go b/plugins/inputs/snmp/snmp_test.go index 594a70217..8b3f91380 100644 --- a/plugins/inputs/snmp/snmp_test.go +++ b/plugins/inputs/snmp/snmp_test.go @@ -55,7 +55,7 @@ func TestSNMPErrorBulk(t *testing.T) { Oid: ".1.3.6.1.2.1.2.2.1.16", } h := Host{ - Address: "127.0.0.1", + Address: testutil.GetLocalHost(), Collect: []string{"oid1"}, } s := Snmp{ @@ -75,7 +75,7 @@ func TestSNMPGet1(t *testing.T) { Oid: ".1.3.6.1.2.1.2.2.1.16.1", } h := Host{ - Address: "127.0.0.1:31161", + Address: testutil.GetLocalHost() + ":31161", Community: "telegraf", Version: 2, Timeout: 2.0, @@ -98,7 +98,7 @@ func TestSNMPGet1(t *testing.T) { }, map[string]string{ "unit": "octets", - "host": "127.0.0.1", + "host": testutil.GetLocalHost(), }, ) } @@ -109,7 +109,7 @@ func TestSNMPGet2(t *testing.T) { Oid: "ifNumber", } h := Host{ - Address: "127.0.0.1:31161", + Address: testutil.GetLocalHost() + ":31161", Community: "telegraf", Version: 2, Timeout: 2.0, @@ -133,7 +133,7 @@ func TestSNMPGet2(t *testing.T) { }, map[string]string{ "instance": "0", - "host": "127.0.0.1", + "host": testutil.GetLocalHost(), }, ) } @@ -146,7 +146,7 @@ func TestSNMPGet3(t *testing.T) { Instance: "1", } h := Host{ - Address: "127.0.0.1:31161", + Address: testutil.GetLocalHost() + ":31161", Community: "telegraf", Version: 2, Timeout: 2.0, @@ -171,7 +171,7 @@ func TestSNMPGet3(t *testing.T) { map[string]string{ "unit": "octets", "instance": "1", - "host": "127.0.0.1", + "host": testutil.GetLocalHost(), }, ) } @@ -184,7 +184,7 @@ func TestSNMPEasyGet4(t *testing.T) { Instance: "1", } h := Host{ - Address: "127.0.0.1:31161", + Address: testutil.GetLocalHost() + ":31161", Community: "telegraf", Version: 2, Timeout: 2.0, @@ -210,7 +210,7 @@ func TestSNMPEasyGet4(t *testing.T) { map[string]string{ "unit": "octets", "instance": "1", - "host": "127.0.0.1", + "host": testutil.GetLocalHost(), }, ) @@ -221,7 +221,7 @@ func TestSNMPEasyGet4(t *testing.T) { }, map[string]string{ "instance": "0", - "host": "127.0.0.1", + "host": testutil.GetLocalHost(), }, ) } @@ -234,7 +234,7 @@ func TestSNMPEasyGet5(t *testing.T) { Instance: "1", } h := Host{ - Address: "127.0.0.1:31161", + Address: testutil.GetLocalHost() + ":31161", Community: "telegraf", Version: 2, Timeout: 2.0, @@ -260,7 +260,7 @@ func TestSNMPEasyGet5(t *testing.T) { map[string]string{ "unit": "octets", "instance": "1", - "host": "127.0.0.1", + "host": testutil.GetLocalHost(), }, ) @@ -271,14 +271,14 @@ func TestSNMPEasyGet5(t *testing.T) { }, map[string]string{ "instance": "0", - "host": "127.0.0.1", + "host": testutil.GetLocalHost(), }, ) } func TestSNMPEasyGet6(t *testing.T) { h := Host{ - Address: "127.0.0.1:31161", + Address: testutil.GetLocalHost() + ":31161", Community: "telegraf", Version: 2, Timeout: 2.0, @@ -301,7 +301,7 @@ func TestSNMPEasyGet6(t *testing.T) { }, map[string]string{ "instance": "0", - "host": "127.0.0.1", + "host": testutil.GetLocalHost(), }, ) } @@ -314,7 +314,7 @@ func TestSNMPBulk1(t *testing.T) { MaxRepetition: 2, } h := Host{ - Address: "127.0.0.1:31161", + Address: testutil.GetLocalHost() + ":31161", Community: "telegraf", Version: 2, Timeout: 2.0, @@ -339,7 +339,7 @@ func TestSNMPBulk1(t *testing.T) { map[string]string{ "unit": "octets", "instance": "1", - "host": "127.0.0.1", + "host": testutil.GetLocalHost(), }, ) @@ -351,7 +351,7 @@ func TestSNMPBulk1(t *testing.T) { map[string]string{ "unit": "octets", "instance": "2", - "host": "127.0.0.1", + "host": testutil.GetLocalHost(), }, ) @@ -363,7 +363,7 @@ func TestSNMPBulk1(t *testing.T) { map[string]string{ "unit": "octets", "instance": "3", - "host": "127.0.0.1", + "host": testutil.GetLocalHost(), }, ) @@ -375,7 +375,7 @@ func TestSNMPBulk1(t *testing.T) { map[string]string{ "unit": "octets", "instance": "36", - "host": "127.0.0.1", + "host": testutil.GetLocalHost(), }, ) } @@ -392,7 +392,7 @@ func dTestSNMPBulk2(t *testing.T) { MaxRepetition: 2, } h := Host{ - Address: "127.0.0.1:31161", + Address: testutil.GetLocalHost() + ":31161", Community: "telegraf", Version: 2, Timeout: 2.0, @@ -417,7 +417,7 @@ func dTestSNMPBulk2(t *testing.T) { map[string]string{ "unit": "octets", "instance": "1", - "host": "127.0.0.1", + "host": testutil.GetLocalHost(), }, ) @@ -429,7 +429,7 @@ func dTestSNMPBulk2(t *testing.T) { map[string]string{ "unit": "octets", "instance": "2", - "host": "127.0.0.1", + "host": testutil.GetLocalHost(), }, ) @@ -441,7 +441,7 @@ func dTestSNMPBulk2(t *testing.T) { map[string]string{ "unit": "octets", "instance": "3", - "host": "127.0.0.1", + "host": testutil.GetLocalHost(), }, ) @@ -453,7 +453,7 @@ func dTestSNMPBulk2(t *testing.T) { map[string]string{ "unit": "octets", "instance": "36", - "host": "127.0.0.1", + "host": testutil.GetLocalHost(), }, ) } diff --git a/plugins/inputs/system/disk.go b/plugins/inputs/system/disk.go index 5143859d1..aeddd3f9b 100644 --- a/plugins/inputs/system/disk.go +++ b/plugins/inputs/system/disk.go @@ -80,8 +80,8 @@ func (_ *DiskIOStats) Description() string { var diskIoSampleConfig = ` # By default, telegraf will gather stats for all devices including # disk partitions. - # Setting devices will restrict the stats to the specified devcies. - # devices = ["sda","sdb"] + # Setting devices will restrict the stats to the specified devices. + # devices = ["sda", "sdb"] # Uncomment the following line if you do not need disk serial numbers. # skip_serial_number = true `