Root directory cleanup

docs/CONFIGURATION.md

@@ -0,0 +1,218 @@
+# Telegraf Configuration
+
+## Generating a Configuration File
+
+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:
+`telegraf -sample-config -input-filter cpu:mem:net:swap -output-filter influxdb:kafka`
+
+## `[global_tags]` Configuration
+
+Global tags can be specific in the `[global_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.
+
+* **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().
+
+## `[inputs.xxx]` Configuration
+
+There are some configuration options that are configurable per input:
+
+* **name_override**: Override the base name of the measurement.
+(Default is the name of the input).
+* **name_prefix**: Specifies a prefix to attach to the measurement name.
+* **name_suffix**: Specifies a suffix to attach to the measurement name.
+* **tags**: A map of tags to apply to a specific input's measurements.
+* **interval**: How often to gather this metric. Normal plugins use a single
+global interval, but if one particular input should be run less or more often,
+you can configure that here.
+
+#### Input Filters
+
+There are also filters that can be configured per input:
+
+* **pass**: An array of strings that is used to filter metrics generated by the
+current input. Each string in the array is tested as a glob match against field names
+and if it matches, the field is emitted.
+* **drop**: The inverse of pass, if a field name matches, it is not emitted.
+* **tagpass**: tag names and arrays of strings that are used to filter
+measurements by the current input. Each string in the array is tested as a glob
+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
+
+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
+measurements at a 10s interval and will collect per-cpu data, dropping any
+fields which begin with `time_`.
+
+```toml
+[global_tags]
+  dc = "denver-1"
+
+[agent]
+  interval = "10s"
+
+# OUTPUTS
+[[outputs.influxdb]]
+  url = "http://192.168.59.103:8086" # required.
+  database = "telegraf" # required.
+  precision = "s"
+
+# INPUTS
+[[inputs.cpu]]
+  percpu = true
+  totalcpu = false
+  # filter all fields beginning with 'time_'
+  drop = ["time_*"]
+```
+
+#### Input Config: tagpass and tagdrop
+
+```toml
+[[inputs.cpu]]
+  percpu = true
+  totalcpu = false
+  drop = ["cpu_time"]
+  # Don't collect CPU data for cpu6 & cpu7
+  [inputs.cpu.tagdrop]
+    cpu = [ "cpu6", "cpu7" ]
+
+[[inputs.disk]]
+  [inputs.disk.tagpass]
+    # tagpass conditions are OR, not AND.
+    # If the (filesystem is ext4 or xfs) OR (the path is /opt or /home)
+    # then the metric passes
+    fstype = [ "ext4", "xfs" ]
+    # Globs can also be used on the tag values
+    path = [ "/opt", "/home*" ]
+```
+
+#### Input Config: pass and drop
+
+```toml
+# Drop all metrics for guest & steal CPU usage
+[[inputs.cpu]]
+  percpu = false
+  totalcpu = true
+  drop = ["usage_guest", "usage_steal"]
+
+# Only store inode related metrics for disks
+[[inputs.disk]]
+  pass = ["inodes*"]
+```
+
+#### Input config: prefix, suffix, and override
+
+This plugin will emit measurements with the name `cpu_total`
+
+```toml
+[[inputs.cpu]]
+  name_suffix = "_total"
+  percpu = false
+  totalcpu = true
+```
+
+This will emit measurements with the name `foobar`
+
+```toml
+[[inputs.cpu]]
+  name_override = "foobar"
+  percpu = false
+  totalcpu = true
+```
+
+#### Input config: tags
+
+This plugin will emit measurements with two additional tags: `tag1=foo` and
+`tag2=bar`
+
+```toml
+[[inputs.cpu]]
+  percpu = false
+  totalcpu = true
+  [inputs.cpu.tags]
+    tag1 = "foo"
+    tag2 = "bar"
+```
+
+#### 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
+you utilize `name_override`, `name_prefix`, or `name_suffix` config options
+to avoid measurement collisions:
+
+```toml
+[[inputs.cpu]]
+  percpu = false
+  totalcpu = true
+
+[[inputs.cpu]]
+  percpu = true
+  totalcpu = false
+  name_override = "percpu_usage"
+  drop = ["cpu_time*"]
+```
+
+## `[outputs.xxx]` Configuration
+
+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 inputs
+(pass, drop, tagpass, tagdrop)
+
+```toml
+[[outputs.influxdb]]
+  urls = [ "http://localhost:8086" ]
+  database = "telegraf"
+  precision = "s"
+  # Drop all measurements that start with "aerospike"
+  drop = ["aerospike*"]
+
+[[outputs.influxdb]]
+  urls = [ "http://localhost:8086" ]
+  database = "telegraf-aerospike-data"
+  precision = "s"
+  # Only accept aerospike data:
+  pass = ["aerospike*"]
+
+[[outputs.influxdb]]
+  urls = [ "http://localhost:8086" ]
+  database = "telegraf-cpu0-data"
+  precision = "s"
+  # Only store measurements where the tag "cpu" matches the value "cpu0"
+  [outputs.influxdb.tagpass]
+    cpu = ["cpu0"]
+```