diff --git a/docs/AGGREGATORS.md b/docs/AGGREGATORS.md index 0edf46783..265b9fa68 100644 --- a/docs/AGGREGATORS.md +++ b/docs/AGGREGATORS.md @@ -1,15 +1,15 @@ -### Aggregator Plugins +# Aggregator Plugins This section is for developers who want to create a new aggregator plugin. -### Aggregator Plugin Guidelines +## Aggregator Plugin Guidelines * A aggregator must conform to the [telegraf.Aggregator][] interface. * Aggregators should call `aggregators.Add` in their `init` function to register themselves. See below for a quick example. * To be available within Telegraf itself, plugins must add themselves to the `github.com/influxdata/telegraf/plugins/aggregators/all/all.go` file. -- The `SampleConfig` function should return valid toml that describes how the +* The `SampleConfig` function should return valid toml that describes how the plugin can be configured. This is included in `telegraf config`. Please consult the [Sample Config][] page for the latest style guidelines. * The `Description` function should say in one line what this aggregator does. @@ -17,7 +17,7 @@ This section is for developers who want to create a new aggregator plugin. through it. This should be done using the builtin `HashID()` function of each metric. * When the `Reset()` function is called, all caches should be cleared. -- Follow the recommended [Code Style][]. +* Follow the recommended [Code Style][]. ### Aggregator Plugin Example @@ -27,21 +27,21 @@ package min // min.go import ( - "github.com/influxdata/telegraf" - "github.com/influxdata/telegraf/plugins/aggregators" + "github.com/influxdata/telegraf" + "github.com/influxdata/telegraf/plugins/aggregators" ) type Min struct { - // caches for metric fields, names, and tags - fieldCache map[uint64]map[string]float64 - nameCache map[uint64]string - tagCache map[uint64]map[string]string + // caches for metric fields, names, and tags + fieldCache map[uint64]map[string]float64 + nameCache map[uint64]string + tagCache map[uint64]map[string]string } func NewMin() telegraf.Aggregator { - m := &Min{} - m.Reset() - return m + m := &Min{} + m.Reset() + return m } var sampleConfig = ` @@ -53,77 +53,77 @@ var sampleConfig = ` ` func (m *Min) Init() error { - return nil + return nil } func (m *Min) SampleConfig() string { - return sampleConfig + return sampleConfig } func (m *Min) Description() string { - return "Keep the aggregate min of each metric passing through." + return "Keep the aggregate min of each metric passing through." } func (m *Min) Add(in telegraf.Metric) { - id := in.HashID() - if _, ok := m.nameCache[id]; !ok { - // hit an uncached metric, create caches for first time: - m.nameCache[id] = in.Name() - m.tagCache[id] = in.Tags() - m.fieldCache[id] = make(map[string]float64) - for k, v := range in.Fields() { - if fv, ok := convert(v); ok { - m.fieldCache[id][k] = fv - } - } - } else { - for k, v := range in.Fields() { - if fv, ok := convert(v); ok { - if _, ok := m.fieldCache[id][k]; !ok { - // hit an uncached field of a cached metric - m.fieldCache[id][k] = fv - continue - } - if fv < m.fieldCache[id][k] { + id := in.HashID() + if _, ok := m.nameCache[id]; !ok { + // hit an uncached metric, create caches for first time: + m.nameCache[id] = in.Name() + m.tagCache[id] = in.Tags() + m.fieldCache[id] = make(map[string]float64) + for k, v := range in.Fields() { + if fv, ok := convert(v); ok { + m.fieldCache[id][k] = fv + } + } + } else { + for k, v := range in.Fields() { + if fv, ok := convert(v); ok { + if _, ok := m.fieldCache[id][k]; !ok { + // hit an uncached field of a cached metric + m.fieldCache[id][k] = fv + continue + } + if fv < m.fieldCache[id][k] { // set new minimum - m.fieldCache[id][k] = fv - } - } - } - } + m.fieldCache[id][k] = fv + } + } + } + } } func (m *Min) Push(acc telegraf.Accumulator) { - for id, _ := range m.nameCache { - fields := map[string]interface{}{} - for k, v := range m.fieldCache[id] { - fields[k+"_min"] = v - } - acc.AddFields(m.nameCache[id], fields, m.tagCache[id]) - } + for id, _ := range m.nameCache { + fields := map[string]interface{}{} + for k, v := range m.fieldCache[id] { + fields[k+"_min"] = v + } + acc.AddFields(m.nameCache[id], fields, m.tagCache[id]) + } } func (m *Min) Reset() { - m.fieldCache = make(map[uint64]map[string]float64) - m.nameCache = make(map[uint64]string) - m.tagCache = make(map[uint64]map[string]string) + m.fieldCache = make(map[uint64]map[string]float64) + m.nameCache = make(map[uint64]string) + m.tagCache = make(map[uint64]map[string]string) } func convert(in interface{}) (float64, bool) { - switch v := in.(type) { - case float64: - return v, true - case int64: - return float64(v), true - default: - return 0, false - } + switch v := in.(type) { + case float64: + return v, true + case int64: + return float64(v), true + default: + return 0, false + } } func init() { - aggregators.Add("min", func() telegraf.Aggregator { - return NewMin() - }) + aggregators.Add("min", func() telegraf.Aggregator { + return NewMin() + }) } ``` diff --git a/docs/AGGREGATORS_AND_PROCESSORS.md b/docs/AGGREGATORS_AND_PROCESSORS.md index 934a4b0cf..389138cec 100644 --- a/docs/AGGREGATORS_AND_PROCESSORS.md +++ b/docs/AGGREGATORS_AND_PROCESSORS.md @@ -5,7 +5,7 @@ As of release 1.1.0, Telegraf has the concept of Aggregator and Processor Plugin These plugins sit in-between Input & Output plugins, aggregating and processing metrics as they pass through Telegraf: -``` +```text ┌───────────┐ │ │ │ CPU │───┐ @@ -44,12 +44,14 @@ to control which metrics are passed through a processor or aggregator. If a metric is filtered out the metric bypasses the plugin and is passed downstream to the next plugin. -### Processor +## Processor + Processor plugins process metrics as they pass through and immediately emit results based on the values they process. For example, this could be printing all metrics or adding a tag to all metrics that pass through. -### Aggregator +## Aggregator + Aggregator plugins, on the other hand, are a bit more complicated. Aggregators are typically for emitting new _aggregate_ metrics, such as a running mean, minimum, maximum, or standard deviation. For this reason, all _aggregator_ diff --git a/docs/COMMANDS_AND_FLAGS.md b/docs/COMMANDS_AND_FLAGS.md index cb0c31268..babccb54b 100644 --- a/docs/COMMANDS_AND_FLAGS.md +++ b/docs/COMMANDS_AND_FLAGS.md @@ -1,27 +1,27 @@ # Telegraf Commands & Flags -### Usage +## Usage -``` +```shell telegraf [commands] telegraf [flags] ``` -### Commands +## Commands |command|description| |--------|-----------------------------------------------| |`config` |print out full sample configuration to stdout| |`version`|print the version to stdout| -### Flags +## Flags |flag|description| |-------------------|------------| |`--aggregator-filter ` |filter the aggregators to enable, separator is `:`| |`--config ` |configuration file to load| |`--config-directory ` |directory containing additional *.conf files| -|`--watch-config` |Telegraf will restart on local config changes.
Monitor changes using either fs notifications or polling. Valid values: `inotify` or `poll`.
Monitoring is off by default.| +|`--watch-config` |Telegraf will restart on local config changes. Monitor changes using either fs notifications or polling. Valid values: `inotify` or `poll`. Monitoring is off by default.| |`--plugin-directory` |directory containing *.so files, this directory will be searched recursively. Any Plugin found will be loaded and namespaced.| |`--debug` |turn on debug logging| |`--input-filter ` |filter the inputs to enable, separator is `:`| @@ -32,7 +32,7 @@ telegraf [flags] |`--pprof-addr
` |pprof address to listen on, don't activate pprof if empty| |`--processor-filter ` |filter the processors to enable, separator is `:`| |`--quiet` |run in quiet mode| -|`--section-filter` |filter config sections to output, separator is `:`
Valid values are `agent`, `global_tags`, `outputs`, `processors`, `aggregators` and `inputs`| +|`--section-filter` |filter config sections to output, separator is `:`. Valid values are `agent`, `global_tags`, `outputs`, `processors`, `aggregators` and `inputs`| |`--sample-config` |print out full sample configuration| |`--once` |enable once mode: gather metrics once, write them, and exit| |`--test` |enable test mode: gather metrics once and print them| @@ -40,7 +40,7 @@ telegraf [flags] |`--usage ` |print usage for a plugin, ie, `telegraf --usage mysql`| |`--version` |display the version and exit| -### Examples +## Examples **Generate a telegraf config file:** @@ -55,7 +55,7 @@ telegraf [flags] `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:** diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 9af88b669..25d10a90b 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -1,3 +1,5 @@ + + # Configuration Telegraf's configuration file is written using [TOML][] and is composed of @@ -5,9 +7,10 @@ three sections: [global tags][], [agent][] settings, and [plugins][]. View the default [telegraf.conf][] config file with all available plugins. -### Generating a Configuration File +## Generating a Configuration File A default config file can be generated by telegraf: + ```sh telegraf config > telegraf.conf ``` @@ -21,7 +24,7 @@ telegraf --input-filter cpu:mem:net:swap --output-filter influxdb:kafka config [View the full list][flags] of Telegraf commands and flags or by running `telegraf --help`. -### Configuration Loading +## Configuration Loading The location of the configuration file can be set via the `--config` command line flag. @@ -34,7 +37,7 @@ On most systems, the default locations are `/etc/telegraf/telegraf.conf` for the main configuration file and `/etc/telegraf/telegraf.d` for the directory of configuration files. -### Environment Variables +## Environment Variables Environment variables can be used anywhere in the config file, simply surround them with `${}`. Replacement occurs before file parsing. For strings @@ -49,14 +52,17 @@ in the `/etc/default/telegraf` file. `/etc/default/telegraf`: For InfluxDB 1.x: -``` + +```shell USER="alice" INFLUX_URL="http://localhost:8086" INFLUX_SKIP_DATABASE_CREATION="true" INFLUX_PASSWORD="monkey123" ``` + For InfluxDB OSS 2: -``` + +```shell INFLUX_HOST="http://localhost:8086" # used to be 9999 INFLUX_TOKEN="replace_with_your_token" INFLUX_ORG="your_username" @@ -64,7 +70,8 @@ INFLUX_BUCKET="replace_with_your_bucket_name" ``` For InfluxDB Cloud 2: -``` + +```shell # For AWS West (Oregon) INFLUX_HOST="https://us-west-2-1.aws.cloud2.influxdata.com" # Other Cloud URLs at https://v2.docs.influxdata.com/v2.0/reference/urls/#influxdb-cloud-urls @@ -74,6 +81,7 @@ INFLUX_BUCKET="replace_with_your_bucket_name" ``` `/etc/telegraf.conf`: + ```toml [global_tags] user = "${USER}" @@ -103,6 +111,7 @@ INFLUX_BUCKET="replace_with_your_bucket_name" The above files will produce the following effective configuration file to be parsed: + ```toml [global_tags] user = "alice" @@ -132,17 +141,18 @@ parsed: bucket = "replace_with_your_bucket_name" ``` -### Intervals +## Intervals Intervals are durations of time and can be specified for supporting settings by combining an integer value and time unit as a string value. Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. + ```toml [agent] interval = "10s" ``` -### Global Tags +## Global Tags Global tags can be specified in the `[global_tags]` table in key="value" format. All metrics that are gathered will be tagged with the tags specified. @@ -153,7 +163,7 @@ Global tags are overriden by tags set by plugins. dc = "us-east-1" ``` -### Agent +## Agent The agent table configures Telegraf and the defaults used across all plugins. @@ -209,7 +219,6 @@ The agent table configures Telegraf and the defaults used across all plugins. Name of the file to be logged to when using the "file" logtarget. If set to the empty string then logs are written to stderr. - - **logfile_rotation_interval**: The logfile will be rotated after the time interval specified. When set to 0 no time based rotation is performed. @@ -231,7 +240,7 @@ The agent table configures Telegraf and the defaults used across all plugins. - **omit_hostname**: If set to true, do no set the "host" tag in the telegraf agent. -### Plugins +## Plugins Telegraf plugins are divided into 4 types: [inputs][], [outputs][], [processors][], and [aggregators][]. @@ -287,6 +296,7 @@ emitted from the input plugin. #### Examples Use the name_suffix parameter to emit measurements with the name `cpu_total`: + ```toml [[inputs.cpu]] name_suffix = "_total" @@ -295,6 +305,7 @@ Use the name_suffix parameter to emit measurements with the name `cpu_total`: ``` Use the name_override parameter to emit measurements with the name `foobar`: + ```toml [[inputs.cpu]] name_override = "foobar" @@ -307,6 +318,7 @@ Emit measurements with two additional tags: `tag1=foo` and `tag2=bar` > **NOTE**: With TOML, order matters. Parameters belong to the last defined > table header, place `[inputs.cpu.tags]` table at the _end_ of the plugin > definition. + ```toml [[inputs.cpu]] percpu = false @@ -318,6 +330,7 @@ Emit measurements with two additional tags: `tag1=foo` and `tag2=bar` Utilize `name_override`, `name_prefix`, or `name_suffix` config options to avoid measurement collisions when defining multiple plugins: + ```toml [[inputs.cpu]] percpu = false @@ -357,6 +370,7 @@ emitted from the output plugin. #### Examples Override flush parameters for a single output: + ```toml [agent] flush_interval = "10s" @@ -394,6 +408,7 @@ processor. If the order processors are applied matters you must set order on all involved processors: + ```toml [[processors.rename]] order = 1 @@ -445,6 +460,7 @@ aggregator. Collect and emit the min/max of the system load1 metric every 30s, dropping the originals. + ```toml [[inputs.system]] fieldpass = ["load1"] # collects system load1 metric. @@ -460,6 +476,7 @@ the originals. Collect and emit the min/max of the swap metrics every 30s, dropping the originals. The aggregator will not be applied to the system load metrics due to the `namepass` parameter. + ```toml [[inputs.swap]] @@ -475,14 +492,13 @@ to the `namepass` parameter. files = ["stdout"] ``` - -### Metric Filtering +## Metric Filtering Metric filtering can be configured per plugin on any input, output, processor, and aggregator plugin. Filters fall under two categories: Selectors and Modifiers. -#### Selectors +### Selectors Selector filters include or exclude entire metrics. When a metric is excluded from a Input or an Output plugin, the metric is dropped. If a metric is @@ -510,7 +526,7 @@ is tested on metrics after they have passed the `tagpass` test. defined at the *_end_* of the plugin definition, otherwise subsequent plugin config options will be interpreted as part of the tagpass/tagdrop tables. -#### Modifiers +### Modifiers Modifier filters remove tags and fields from a metric. If all fields are removed the metric is removed. @@ -536,9 +552,10 @@ The inverse of `taginclude`. Tags with a tag key matching one of the patterns will be discarded from the metric. Any tag can be filtered including global tags and the agent `host` tag. -#### Filtering Examples +### Filtering Examples + +#### Using tagpass and tagdrop -##### Using tagpass and tagdrop: ```toml [[inputs.cpu]] percpu = true @@ -571,7 +588,8 @@ tags and the agent `host` tag. instance = ["isatap*", "Local*"] ``` -##### Using fieldpass and fielddrop: +#### Using fieldpass and fielddrop + ```toml # Drop all metrics for guest & steal CPU usage [[inputs.cpu]] @@ -584,7 +602,8 @@ tags and the agent `host` tag. fieldpass = ["inodes*"] ``` -##### Using namepass and namedrop: +#### Using namepass and namedrop + ```toml # Drop all metrics about containers for kubelet [[inputs.prometheus]] @@ -597,7 +616,8 @@ tags and the agent `host` tag. namepass = ["rest_client_*"] ``` -##### Using taginclude and tagexclude: +#### Using taginclude and tagexclude + ```toml # Only include the "cpu" tag in the measurements for the cpu plugin. [[inputs.cpu]] @@ -610,7 +630,8 @@ tags and the agent `host` tag. tagexclude = ["fstype"] ``` -##### Metrics can be routed to different outputs using the metric name and tags: +#### Metrics can be routed to different outputs using the metric name and tags + ```toml [[outputs.influxdb]] urls = [ "http://localhost:8086" ] @@ -632,7 +653,7 @@ tags and the agent `host` tag. cpu = ["cpu0"] ``` -##### Routing metrics to different outputs based on the input. +#### Routing metrics to different outputs based on the input Metrics are tagged with `influxdb_database` in the input, which is then used to select the output. The tag is removed in the outputs before writing. @@ -656,7 +677,7 @@ select the output. The tag is removed in the outputs before writing. influxdb_database = "other" ``` -### Transport Layer Security (TLS) +## Transport Layer Security (TLS) Reference the detailed [TLS][] documentation. diff --git a/docs/EXTERNAL_PLUGINS.md b/docs/EXTERNAL_PLUGINS.md index 83759ed72..f3dc0699c 100644 --- a/docs/EXTERNAL_PLUGINS.md +++ b/docs/EXTERNAL_PLUGINS.md @@ -1,8 +1,8 @@ -### External Plugins +# External Plugins -[External plugins](/EXTERNAL_PLUGINS.md) are external programs that are built outside -of Telegraf that can run through an `execd` plugin. These external plugins allow for -more flexibility compared to internal Telegraf plugins. +[External plugins](/EXTERNAL_PLUGINS.md) are external programs that are built outside +of Telegraf that can run through an `execd` plugin. These external plugins allow for +more flexibility compared to internal Telegraf plugins. - External plugins can be written in any language (internal Telegraf plugins can only written in Go) - External plugins can access to libraries not written in Go @@ -11,7 +11,8 @@ more flexibility compared to internal Telegraf plugins. - You don't need to wait on the Telegraf team to publish your plugin and start working with it. - using the [shim](/plugins/common/shim) you can easily convert plugins between internal and external use -### External Plugin Guidelines +## External Plugin Guidelines + The guidelines of writing external plugins would follow those for our general [input](/docs/INPUTS.md), [output](/docs/OUTPUTS.md), [processor](/docs/PROCESSORS.md), and [aggregator](/docs/AGGREGATORS.md) plugins. Please reference the documentation on how to create these plugins written in Go. @@ -19,51 +20,55 @@ Please reference the documentation on how to create these plugins written in Go. _For listed [external plugins](/EXTERNAL_PLUGINS.md), the author of the external plugin is also responsible for the maintenance and feature development of external plugins. Expect to have users open plugin issues on its respective GitHub repository._ -#### Execd Go Shim +### Execd Go Shim + For Go plugins, there is a [Execd Go Shim](/plugins/common/shim/) that will make it trivial to extract an internal input, processor, or output plugin from the main Telegraf repo out to a stand-alone repo. This shim allows anyone to build and run it as a separate app using one of the `execd`plugins: + - [inputs.execd](/plugins/inputs/execd) - [processors.execd](/plugins/processors/execd) - [outputs.execd](/plugins/outputs/execd) Follow the [Steps to externalize a plugin](/plugins/common/shim#steps-to-externalize-a-plugin) and [Steps to build and run your plugin](/plugins/common/shim#steps-to-build-and-run-your-plugin) to properly with the Execd Go Shim -#### Step-by-Step guidelines -This is a guide to help you set up your plugin to use it with `execd` -1. Write your Telegraf plugin. Depending on the plugin, follow the guidelines on how to create the plugin itself using InfluxData's best practices: +### Step-by-Step guidelines + +This is a guide to help you set up your plugin to use it with `execd`: + +1. Write your Telegraf plugin. Depending on the plugin, follow the guidelines on how to create the plugin itself using InfluxData's best practices: - [Input Plugins](/docs/INPUTS.md) - [Processor Plugins](/docs/PROCESSORS.md) - [Aggregator Plugins](/docs/AGGREGATORS.md) - [Output Plugins](/docs/OUTPUTS.md) 2. If your plugin is written in Go, include the steps for the [Execd Go Shim](/plugins/common/shim#steps-to-build-and-run-your-plugin) - 1. Move the project to an external repo, it's recommended to preserve the path - structure, (but not strictly necessary). eg if your plugin was at - `plugins/inputs/cpu`, it's recommended that it also be under `plugins/inputs/cpu` - in the new repo. For a further example of what this might look like, take a - look at [ssoroka/rand](https://github.com/ssoroka/rand) or - [danielnelson/telegraf-execd-openvpn](https://github.com/danielnelson//telegraf-execd-openvpn) - 1. Copy [main.go](/plugins/common/shim/example/cmd/main.go) into your project under the `cmd` folder. - This will be the entrypoint to the plugin when run as a stand-alone program, and - it will call the shim code for you to make that happen. It's recommended to - have only one plugin per repo, as the shim is not designed to run multiple - plugins at the same time (it would vastly complicate things). - 1. Edit the main.go file to import your plugin. Within Telegraf this would have - been done in an all.go file, but here we don't split the two apart, and the change - just goes in the top of main.go. If you skip this step, your plugin will do nothing. - eg: `_ "github.com/me/my-plugin-telegraf/plugins/inputs/cpu"` - 1. Optionally add a [plugin.conf](./example/cmd/plugin.conf) for configuration - specific to your plugin. Note that this config file **must be separate from the - rest of the config for Telegraf, and must not be in a shared directory where - Telegraf is expecting to load all configs**. If Telegraf reads this config file - it will not know which plugin it relates to. Telegraf instead uses an execd config - block to look for this plugin. - 1. Add usage and development instructions in the homepage of your repository for running - your plugin with its respective `execd` plugin. Please refer to - [openvpn](https://github.com/danielnelson/telegraf-execd-openvpn#usage) and [awsalarms](https://github.com/vipinvkmenon/awsalarms#installation) - for examples. Include the following steps: + - Move the project to an external repo, it's recommended to preserve the path + structure, (but not strictly necessary). eg if your plugin was at + `plugins/inputs/cpu`, it's recommended that it also be under `plugins/inputs/cpu` + in the new repo. For a further example of what this might look like, take a + look at [ssoroka/rand](https://github.com/ssoroka/rand) or + [danielnelson/telegraf-execd-openvpn](https://github.com/danielnelson//telegraf-execd-openvpn) + - Copy [main.go](/plugins/common/shim/example/cmd/main.go) into your project under the `cmd` folder. + This will be the entrypoint to the plugin when run as a stand-alone program, and + it will call the shim code for you to make that happen. It's recommended to + have only one plugin per repo, as the shim is not designed to run multiple + plugins at the same time (it would vastly complicate things). + - Edit the main.go file to import your plugin. Within Telegraf this would have + been done in an all.go file, but here we don't split the two apart, and the change + just goes in the top of main.go. If you skip this step, your plugin will do nothing. + eg: `_ "github.com/me/my-plugin-telegraf/plugins/inputs/cpu"` + - Optionally add a [plugin.conf](./example/cmd/plugin.conf) for configuration + specific to your plugin. Note that this config file **must be separate from the + rest of the config for Telegraf, and must not be in a shared directory where + Telegraf is expecting to load all configs**. If Telegraf reads this config file + it will not know which plugin it relates to. Telegraf instead uses an execd config + block to look for this plugin. + - Add usage and development instructions in the homepage of your repository for running + your plugin with its respective `execd` plugin. Please refer to + [openvpn](https://github.com/danielnelson/telegraf-execd-openvpn#usage) and [awsalarms](https://github.com/vipinvkmenon/awsalarms#installation) + for examples. Include the following steps: 1. How to download the release package for your platform or how to clone the binary for your external plugin 1. The commands to build your binary 1. Location to edit your `telegraf.conf` - 1. Configuration to run your external plugin with [inputs.execd](/plugins/inputs/execd), + 1. Configuration to run your external plugin with [inputs.execd](/plugins/inputs/execd), [processors.execd](/plugins/processors/execd) or [outputs.execd](/plugins/outputs/execd) - 1. Submit your plugin by opening a PR to add your external plugin to the [/EXTERNAL_PLUGINS.md](/EXTERNAL_PLUGINS.md) - list. Please include the plugin name, link to the plugin repository and a short description of the plugin. + - Submit your plugin by opening a PR to add your external plugin to the [/EXTERNAL_PLUGINS.md](/EXTERNAL_PLUGINS.md) + list. Please include the plugin name, link to the plugin repository and a short description of the plugin. diff --git a/docs/FAQ.md b/docs/FAQ.md index 40a101fdf..c702a9156 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,24 +1,23 @@ # Frequently Asked Questions -### Q: How can I monitor the Docker Engine Host from within a container? +## Q: How can I monitor the Docker Engine Host from within a container? You will need to setup several volume mounts as well as some environment variables: -``` + +```shell docker run --name telegraf \ - -v /:/hostfs:ro \ - -e HOST_ETC=/hostfs/etc \ - -e HOST_PROC=/hostfs/proc \ - -e HOST_SYS=/hostfs/sys \ - -e HOST_VAR=/hostfs/var \ - -e HOST_RUN=/hostfs/run \ - -e HOST_MOUNT_PREFIX=/hostfs \ - telegraf + -v /:/hostfs:ro \ + -e HOST_ETC=/hostfs/etc \ + -e HOST_PROC=/hostfs/proc \ + -e HOST_SYS=/hostfs/sys \ + -e HOST_VAR=/hostfs/var \ + -e HOST_RUN=/hostfs/run \ + -e HOST_MOUNT_PREFIX=/hostfs \ + telegraf ``` - -### Q: Why do I get a "no such host" error resolving hostnames that other -programs can resolve? +## Q: Why do I get a "no such host" error resolving hostnames that other programs can resolve? Go uses a pure Go resolver by default for [name resolution](https://golang.org/pkg/net/#hdr-Name_Resolution). This resolver behaves differently than the C library functions but is more @@ -29,16 +28,18 @@ that are unsupported by the pure Go resolver, you can switch to the cgo resolver. If running manually set: -``` + +```shell export GODEBUG=netdns=cgo ``` If running as a service add the environment variable to `/etc/default/telegraf`: -``` + +```shell GODEBUG=netdns=cgo ``` -### Q: How can I manage series cardinality? +## Q: How can I manage series cardinality? High [series cardinality][], when not properly managed, can cause high load on your database. Telegraf attempts to avoid creating series with high diff --git a/docs/INPUTS.md b/docs/INPUTS.md index 679c24e28..6f553b060 100644 --- a/docs/INPUTS.md +++ b/docs/INPUTS.md @@ -1,4 +1,4 @@ -### Input Plugins +# Input Plugins This section is for developers who want to create new collection inputs. Telegraf is entirely plugin driven. This interface allows for operators to @@ -8,7 +8,7 @@ to create new ways of generating metrics. Plugin authorship is kept as simple as possible to promote people to develop and submit new inputs. -### Input Plugin Guidelines +## Input Plugin Guidelines - A plugin must conform to the [telegraf.Input][] interface. - Input Plugins should call `inputs.Add` in their `init` function to register @@ -25,7 +25,7 @@ and submit new inputs. Let's say you've written a plugin that emits metrics about processes on the current host. -### Input Plugin Example +## Input Plugin Example ```go package simple @@ -55,7 +55,7 @@ func (s *Simple) SampleConfig() string { // Init is for setup, and validating config. func (s *Simple) Init() error { - return nil + return nil } func (s *Simple) Gather(acc telegraf.Accumulator) error { @@ -75,9 +75,9 @@ func init() { ### Development -* Run `make static` followed by `make plugin-[pluginName]` to spin up a docker +- Run `make static` followed by `make plugin-[pluginName]` to spin up a docker dev environment using docker-compose. -* ***[Optional]*** When developing a plugin, add a `dev` directory with a +- ***[Optional]*** When developing a plugin, add a `dev` directory with a `docker-compose.yml` and `telegraf.conf` as well as any other supporting files, where sensible. diff --git a/docs/INTEGRATION_TESTS.md b/docs/INTEGRATION_TESTS.md index b7af82958..ef7633295 100644 --- a/docs/INTEGRATION_TESTS.md +++ b/docs/INTEGRATION_TESTS.md @@ -1,61 +1,62 @@ # Integration Tests -To run our current integration test suite: +To run our current integration test suite: Running the integration tests requires several docker containers to be running. You can start the containers with: -``` + +```shell docker-compose up ``` To run only the integration tests use: -``` +```shell make test-integration ``` Use `make docker-kill` to stop the containers. -Contributing integration tests: +Contributing integration tests: - Add Integration to the end of the test name so it will be run with the above command. - Writes tests where no library is being used in the plugin - There is poor code coverage - It has dynamic code that only gets run at runtime eg: SQL -Current areas we have integration tests: +Current areas we have integration tests: | Area | What it does | |------------------------------------|-------------------------------------------| | Inputs: Aerospike | | | Inputs: Disque | | -| Inputs: Dovecot | | -| Inputs: Mcrouter | | -| Inputs: Memcached | | -| Inputs: Mysql | | -| Inputs: Opcua | | -| Inputs: Openldap | | -| Inputs: Pgbouncer | | -| Inputs: Postgresql | | -| Inputs: Postgresql extensible | | -| Inputs: Procstat / Native windows | | -| Inputs: Prometheus | | -| Inputs: Redis | | -| Inputs: Sqlserver | | -| Inputs: Win perf counters | | -| Inputs: Win services | | -| Inputs: Zookeeper | | -| Outputs: Cratedb / Postgres | | -| Outputs: Elasticsearch | | -| Outputs: Kafka | | -| Outputs: MQTT | | -| Outputs: Nats | | -| Outputs: NSQ | | +| Inputs: Dovecot | | +| Inputs: Mcrouter | | +| Inputs: Memcached | | +| Inputs: Mysql | | +| Inputs: Opcua | | +| Inputs: Openldap | | +| Inputs: Pgbouncer | | +| Inputs: Postgresql | | +| Inputs: Postgresql extensible | | +| Inputs: Procstat / Native windows | | +| Inputs: Prometheus | | +| Inputs: Redis | | +| Inputs: Sqlserver | | +| Inputs: Win perf counters | | +| Inputs: Win services | | +| Inputs: Zookeeper | | +| Outputs: Cratedb / Postgres | | +| Outputs: Elasticsearch | | +| Outputs: Kafka | | +| Outputs: MQTT | | +| Outputs: Nats | | +| Outputs: NSQ | | Areas we would benefit most from new integration tests: | Area | |------------------------------------| -| SNMP | -| MYSQL | -| SQLSERVER | +| SNMP | +| MYSQL | +| SQLSERVER | diff --git a/docs/OUTPUTS.md b/docs/OUTPUTS.md index db8383126..b9baa69a9 100644 --- a/docs/OUTPUTS.md +++ b/docs/OUTPUTS.md @@ -1,10 +1,10 @@ -### Output Plugins +# Output Plugins This section is for developers who want to create a new output sink. Outputs are created in a similar manner as collection plugins, and their interface has similar constructs. -### Output Plugin Guidelines +## Output Plugin Guidelines - An output must conform to the [telegraf.Output][] interface. - Outputs should call `outputs.Add` in their `init` function to register @@ -17,7 +17,7 @@ similar constructs. - The `Description` function should say in one line what this output does. - Follow the recommended [Code Style][]. -### Output Plugin Example +## Output Plugin Example ```go package simpleoutput @@ -46,7 +46,7 @@ func (s *Simple) SampleConfig() string { // Init is for setup, and validating config. func (s *Simple) Init() error { - return nil + return nil } func (s *Simple) Connect() error { @@ -103,6 +103,7 @@ You should also add the following to your `SampleConfig()`: ## Flushing Metrics to Outputs Metrics are flushed to outputs when any of the following events happen: + - `flush_interval + rand(flush_jitter)` has elapsed since start or the last flush interval - At least `metric_batch_size` count of metrics are waiting in the buffer - The telegraf process has received a SIGUSR1 signal