CL-Softwares
/
telegraf
8
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

chore: clean up all markdown lint errors in first half of docs directory (#10152)

This commit is contained in:
Joshua Powers 2021-11-24 11:45:19 -07:00 committed by GitHub
parent 96e939a082
commit 0036757afe
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 220 additions and 189 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
docs/AGGREGATORS.md
View File

@ -1,15 +1,15 @@
### Aggregator Plugins # Aggregator Plugins
This section is for developers who want to create a new aggregator plugin. 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. * A aggregator must conform to the [telegraf.Aggregator][] interface.
* Aggregators should call `aggregators.Add` in their `init` function to * Aggregators should call `aggregators.Add` in their `init` function to
register themselves. See below for a quick example. register themselves. See below for a quick example.
* To be available within Telegraf itself, plugins must add themselves to the * To be available within Telegraf itself, plugins must add themselves to the
`github.com/influxdata/telegraf/plugins/aggregators/all/all.go` file. `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 plugin can be configured. This is included in `telegraf config`. Please
consult the [Sample Config][] page for the latest style guidelines. consult the [Sample Config][] page for the latest style guidelines.
* The `Description` function should say in one line what this aggregator does. * 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 through it. This should be done using the builtin `HashID()` function of
each metric. each metric.
* When the `Reset()` function is called, all caches should be cleared. * When the `Reset()` function is called, all caches should be cleared.
- Follow the recommended [Code Style][]. * Follow the recommended [Code Style][].
### Aggregator Plugin Example ### Aggregator Plugin Example

8
docs/AGGREGATORS_AND_PROCESSORS.md
View File

@ -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 These plugins sit in-between Input & Output plugins, aggregating and processing
metrics as they pass through Telegraf: metrics as they pass through Telegraf:
``` ```text
┌───────────┐ ┌───────────┐
│ │ │ │
│ CPU │───┐ │ 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 metric is filtered out the metric bypasses the plugin and is passed downstream
to the next plugin. to the next plugin.
### Processor ## Processor
Processor plugins process metrics as they pass through and immediately emit Processor plugins process metrics as they pass through and immediately emit
results based on the values they process. For example, this could be printing 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. 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 Aggregator plugins, on the other hand, are a bit more complicated. Aggregators
are typically for emitting new _aggregate_ metrics, such as a running mean, are typically for emitting new _aggregate_ metrics, such as a running mean,
minimum, maximum, or standard deviation. For this reason, all _aggregator_ minimum, maximum, or standard deviation. For this reason, all _aggregator_

14
docs/COMMANDS_AND_FLAGS.md
View File

@ -1,27 +1,27 @@
# Telegraf Commands & Flags # Telegraf Commands & Flags
### Usage ## Usage
``` ```shell
telegraf [commands] telegraf [commands]
telegraf [flags] telegraf [flags]
``` ```
### Commands ## Commands
|command|description| |command|description|
|--------|-----------------------------------------------| |--------|-----------------------------------------------|
|`config` |print out full sample configuration to stdout| |`config` |print out full sample configuration to stdout|
|`version`|print the version to stdout| |`version`|print the version to stdout|
### Flags ## Flags
|flag|description| |flag|description|
|-------------------|------------| |-------------------|------------|
|`--aggregator-filter <filter>` |filter the aggregators to enable, separator is `:`| |`--aggregator-filter <filter>` |filter the aggregators to enable, separator is `:`|
|`--config <file>` |configuration file to load| |`--config <file>` |configuration file to load|
|`--config-directory <directory>` |directory containing additional *.conf files| |`--config-directory <directory>` |directory containing additional *.conf files|
|`--watch-config` |Telegraf will restart on local config changes. <br> Monitor changes using either fs notifications or polling. Valid values: `inotify` or `poll`.<br> 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.| |`--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| |`--debug` |turn on debug logging|
|`--input-filter <filter>` |filter the inputs to enable, separator is `:`| |`--input-filter <filter>` |filter the inputs to enable, separator is `:`|
@ -32,7 +32,7 @@ telegraf [flags]
|`--pprof-addr <address>` |pprof address to listen on, don't activate pprof if empty| |`--pprof-addr <address>` |pprof address to listen on, don't activate pprof if empty|
|`--processor-filter <filter>` |filter the processors to enable, separator is `:`| |`--processor-filter <filter>` |filter the processors to enable, separator is `:`|
|`--quiet` |run in quiet mode| |`--quiet` |run in quiet mode|
|`--section-filter` |filter config sections to output, separator is `:` <br> 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| |`--sample-config` |print out full sample configuration|
|`--once` |enable once mode: gather metrics once, write them, and exit| |`--once` |enable once mode: gather metrics once, write them, and exit|
|`--test` |enable test mode: gather metrics once and print them| |`--test` |enable test mode: gather metrics once and print them|
@ -40,7 +40,7 @@ telegraf [flags]
|`--usage <plugin>` |print usage for a plugin, ie, `telegraf --usage mysql`| |`--usage <plugin>` |print usage for a plugin, ie, `telegraf --usage mysql`|
|`--version` |display the version and exit| |`--version` |display the version and exit|
### Examples ## Examples
**Generate a telegraf config file:** **Generate a telegraf config file:**

67
docs/CONFIGURATION.md
View File

@ -1,3 +1,5 @@
<!-- markdownlint-disable MD024 -->
# Configuration # Configuration
Telegraf's configuration file is written using [TOML][] and is composed of 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. 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: A default config file can be generated by telegraf:
```sh ```sh
telegraf config > telegraf.conf 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`. [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 The location of the configuration file can be set via the `--config` command
line flag. 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 the main configuration file and `/etc/telegraf/telegraf.d` for the directory of
configuration files. configuration files.
### Environment Variables ## Environment Variables
Environment variables can be used anywhere in the config file, simply surround Environment variables can be used anywhere in the config file, simply surround
them with `${}`. Replacement occurs before file parsing. For strings them with `${}`. Replacement occurs before file parsing. For strings
@ -49,14 +52,17 @@ in the `/etc/default/telegraf` file.
`/etc/default/telegraf`: `/etc/default/telegraf`:
For InfluxDB 1.x: For InfluxDB 1.x:
```
```shell
USER="alice" USER="alice"
INFLUX_URL="http://localhost:8086" INFLUX_URL="http://localhost:8086"
INFLUX_SKIP_DATABASE_CREATION="true" INFLUX_SKIP_DATABASE_CREATION="true"
INFLUX_PASSWORD="monkey123" INFLUX_PASSWORD="monkey123"
``` ```
For InfluxDB OSS 2: For InfluxDB OSS 2:
```
```shell
INFLUX_HOST="http://localhost:8086" # used to be 9999 INFLUX_HOST="http://localhost:8086" # used to be 9999
INFLUX_TOKEN="replace_with_your_token" INFLUX_TOKEN="replace_with_your_token"
INFLUX_ORG="your_username" INFLUX_ORG="your_username"
@ -64,7 +70,8 @@ INFLUX_BUCKET="replace_with_your_bucket_name"
``` ```
For InfluxDB Cloud 2: For InfluxDB Cloud 2:
```
```shell
# For AWS West (Oregon) # For AWS West (Oregon)
INFLUX_HOST="https://us-west-2-1.aws.cloud2.influxdata.com" 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 # 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`: `/etc/telegraf.conf`:
```toml ```toml
[global_tags] [global_tags]
user = "${USER}" 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 The above files will produce the following effective configuration file to be
parsed: parsed:
```toml ```toml
[global_tags] [global_tags]
user = "alice" user = "alice"
@ -132,17 +141,18 @@ parsed:
bucket = "replace_with_your_bucket_name" bucket = "replace_with_your_bucket_name"
``` ```
### Intervals ## Intervals
Intervals are durations of time and can be specified for supporting settings by 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 combining an integer value and time unit as a string value. Valid time units are
`ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`.
```toml ```toml
[agent] [agent]
interval = "10s" interval = "10s"
``` ```
### Global Tags ## Global Tags
Global tags can be specified in the `[global_tags]` table in key="value" 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. 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" dc = "us-east-1"
``` ```
### Agent ## Agent
The agent table configures Telegraf and the defaults used across all plugins. 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 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. the empty string then logs are written to stderr.
- **logfile_rotation_interval**: - **logfile_rotation_interval**:
The logfile will be rotated after the time interval specified. When set to The logfile will be rotated after the time interval specified. When set to
0 no time based rotation is performed. 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**: - **omit_hostname**:
If set to true, do no set the "host" tag in the telegraf agent. 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][], Telegraf plugins are divided into 4 types: [inputs][], [outputs][],
[processors][], and [aggregators][]. [processors][], and [aggregators][].
@ -287,6 +296,7 @@ emitted from the input plugin.
#### Examples #### Examples
Use the name_suffix parameter to emit measurements with the name `cpu_total`: Use the name_suffix parameter to emit measurements with the name `cpu_total`:
```toml ```toml
[[inputs.cpu]] [[inputs.cpu]]
name_suffix = "_total" 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`: Use the name_override parameter to emit measurements with the name `foobar`:
```toml ```toml
[[inputs.cpu]] [[inputs.cpu]]
name_override = "foobar" 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 > **NOTE**: With TOML, order matters. Parameters belong to the last defined
> table header, place `[inputs.cpu.tags]` table at the _end_ of the plugin > table header, place `[inputs.cpu.tags]` table at the _end_ of the plugin
> definition. > definition.
```toml ```toml
[[inputs.cpu]] [[inputs.cpu]]
percpu = false 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 Utilize `name_override`, `name_prefix`, or `name_suffix` config options to
avoid measurement collisions when defining multiple plugins: avoid measurement collisions when defining multiple plugins:
```toml ```toml
[[inputs.cpu]] [[inputs.cpu]]
percpu = false percpu = false
@ -357,6 +370,7 @@ emitted from the output plugin.
#### Examples #### Examples
Override flush parameters for a single output: Override flush parameters for a single output:
```toml ```toml
[agent] [agent]
flush_interval = "10s" flush_interval = "10s"
@ -394,6 +408,7 @@ processor.
If the order processors are applied matters you must set order on all involved If the order processors are applied matters you must set order on all involved
processors: processors:
```toml ```toml
[[processors.rename]] [[processors.rename]]
order = 1 order = 1
@ -445,6 +460,7 @@ aggregator.
Collect and emit the min/max of the system load1 metric every 30s, dropping Collect and emit the min/max of the system load1 metric every 30s, dropping
the originals. the originals.
```toml ```toml
[[inputs.system]] [[inputs.system]]
fieldpass = ["load1"] # collects system load1 metric. 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 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 originals. The aggregator will not be applied to the system load metrics due
to the `namepass` parameter. to the `namepass` parameter.
```toml ```toml
[[inputs.swap]] [[inputs.swap]]
@ -475,14 +492,13 @@ to the `namepass` parameter.
files = ["stdout"] files = ["stdout"]
``` ```
<a id="measurement-filtering"></a> ## Metric Filtering
### Metric Filtering
Metric filtering can be configured per plugin on any input, output, processor, Metric filtering can be configured per plugin on any input, output, processor,
and aggregator plugin. Filters fall under two categories: Selectors and and aggregator plugin. Filters fall under two categories: Selectors and
Modifiers. Modifiers.
#### Selectors ### Selectors
Selector filters include or exclude entire metrics. When a metric is excluded 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 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 defined at the *_end_* of the plugin definition, otherwise subsequent plugin config
options will be interpreted as part of the tagpass/tagdrop tables. 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 Modifier filters remove tags and fields from a metric. If all fields are
removed the metric is removed. 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 will be discarded from the metric. Any tag can be filtered including global
tags and the agent `host` tag. tags and the agent `host` tag.
#### Filtering Examples ### Filtering Examples
#### Using tagpass and tagdrop
##### Using tagpass and tagdrop:
```toml ```toml
[[inputs.cpu]] [[inputs.cpu]]
percpu = true percpu = true
@ -571,7 +588,8 @@ tags and the agent `host` tag.
instance = ["isatap*", "Local*"] instance = ["isatap*", "Local*"]
``` ```
##### Using fieldpass and fielddrop: #### Using fieldpass and fielddrop
```toml ```toml
# Drop all metrics for guest & steal CPU usage # Drop all metrics for guest & steal CPU usage
[[inputs.cpu]] [[inputs.cpu]]
@ -584,7 +602,8 @@ tags and the agent `host` tag.
fieldpass = ["inodes*"] fieldpass = ["inodes*"]
``` ```
##### Using namepass and namedrop: #### Using namepass and namedrop
```toml ```toml
# Drop all metrics about containers for kubelet # Drop all metrics about containers for kubelet
[[inputs.prometheus]] [[inputs.prometheus]]
@ -597,7 +616,8 @@ tags and the agent `host` tag.
namepass = ["rest_client_*"] namepass = ["rest_client_*"]
``` ```
##### Using taginclude and tagexclude: #### Using taginclude and tagexclude
```toml ```toml
# Only include the "cpu" tag in the measurements for the cpu plugin. # Only include the "cpu" tag in the measurements for the cpu plugin.
[[inputs.cpu]] [[inputs.cpu]]
@ -610,7 +630,8 @@ tags and the agent `host` tag.
tagexclude = ["fstype"] 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 ```toml
[[outputs.influxdb]] [[outputs.influxdb]]
urls = [ "http://localhost:8086" ] urls = [ "http://localhost:8086" ]
@ -632,7 +653,7 @@ tags and the agent `host` tag.
cpu = ["cpu0"] 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 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. 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" influxdb_database = "other"
``` ```
### Transport Layer Security (TLS) ## Transport Layer Security (TLS)
Reference the detailed [TLS][] documentation. Reference the detailed [TLS][] documentation.

27
docs/EXTERNAL_PLUGINS.md
View File

@ -1,4 +1,4 @@
### External Plugins # External Plugins
[External plugins](/EXTERNAL_PLUGINS.md) are external programs that are built outside [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 of Telegraf that can run through an `execd` plugin. These external plugins allow for
@ -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. - 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 - 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), 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. [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. Please reference the documentation on how to create these plugins written in Go.
@ -19,44 +20,48 @@ 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 _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._ 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: 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) - [inputs.execd](/plugins/inputs/execd)
- [processors.execd](/plugins/processors/execd) - [processors.execd](/plugins/processors/execd)
- [outputs.execd](/plugins/outputs/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 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 ### Step-by-Step guidelines
This is a guide to help you set up your plugin to use it with `execd`
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: 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) - [Input Plugins](/docs/INPUTS.md)
- [Processor Plugins](/docs/PROCESSORS.md) - [Processor Plugins](/docs/PROCESSORS.md)
- [Aggregator Plugins](/docs/AGGREGATORS.md) - [Aggregator Plugins](/docs/AGGREGATORS.md)
- [Output Plugins](/docs/OUTPUTS.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) 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 - 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 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` `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 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 look at [ssoroka/rand](https://github.com/ssoroka/rand) or
[danielnelson/telegraf-execd-openvpn](https://github.com/danielnelson//telegraf-execd-openvpn) [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. - 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 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 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 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). 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 - 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 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. 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"` eg: `_ "github.com/me/my-plugin-telegraf/plugins/inputs/cpu"`
1. Optionally add a [plugin.conf](./example/cmd/plugin.conf) for configuration - 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 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 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 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 it will not know which plugin it relates to. Telegraf instead uses an execd config
block to look for this plugin. block to look for this plugin.
1. Add usage and development instructions in the homepage of your repository for running - Add usage and development instructions in the homepage of your repository for running
your plugin with its respective `execd` plugin. Please refer to 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) [openvpn](https://github.com/danielnelson/telegraf-execd-openvpn#usage) and [awsalarms](https://github.com/vipinvkmenon/awsalarms#installation)
for examples. Include the following steps: for examples. Include the following steps:
@ -65,5 +70,5 @@ This is a guide to help you set up your plugin to use it with `execd`
1. Location to edit your `telegraf.conf` 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) [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) - 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. list. Please include the plugin name, link to the plugin repository and a short description of the plugin.

17
docs/FAQ.md
View File

@ -1,10 +1,11 @@
# Frequently Asked Questions # 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 You will need to setup several volume mounts as well as some environment
variables: variables:
```
```shell
docker run --name telegraf \ docker run --name telegraf \
-v /:/hostfs:ro \ -v /:/hostfs:ro \
-e HOST_ETC=/hostfs/etc \ -e HOST_ETC=/hostfs/etc \
@ -16,9 +17,7 @@ docker run --name telegraf \
telegraf 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). 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 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. resolver.
If running manually set: If running manually set:
```
```shell
export GODEBUG=netdns=cgo export GODEBUG=netdns=cgo
``` ```
If running as a service add the environment variable to `/etc/default/telegraf`: If running as a service add the environment variable to `/etc/default/telegraf`:
```
```shell
GODEBUG=netdns=cgo 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 High [series cardinality][], when not properly managed, can cause high load on
your database. Telegraf attempts to avoid creating series with high your database. Telegraf attempts to avoid creating series with high

10
docs/INPUTS.md
View File

@ -1,4 +1,4 @@
### Input Plugins # Input Plugins
This section is for developers who want to create new collection inputs. This section is for developers who want to create new collection inputs.
Telegraf is entirely plugin driven. This interface allows for operators to 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 Plugin authorship is kept as simple as possible to promote people to develop
and submit new inputs. and submit new inputs.
### Input Plugin Guidelines ## Input Plugin Guidelines
- A plugin must conform to the [telegraf.Input][] interface. - A plugin must conform to the [telegraf.Input][] interface.
- Input Plugins should call `inputs.Add` in their `init` function to register - 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 Let's say you've written a plugin that emits metrics about processes on the
current host. current host.
### Input Plugin Example ## Input Plugin Example
```go ```go
package simple package simple
@ -75,9 +75,9 @@ func init() {
### Development ### 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. 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 `docker-compose.yml` and `telegraf.conf` as well as any other supporting
files, where sensible. files, where sensible.

5
docs/INTEGRATION_TESTS.md
View File

@ -4,13 +4,14 @@ To run our current integration test suite:
Running the integration tests requires several docker containers to be Running the integration tests requires several docker containers to be
running. You can start the containers with: running. You can start the containers with:
```
```shell
docker-compose up docker-compose up
``` ```
To run only the integration tests use: To run only the integration tests use:
``` ```shell
make test-integration make test-integration
``` ```

7
docs/OUTPUTS.md
View File

@ -1,10 +1,10 @@
### Output Plugins # Output Plugins
This section is for developers who want to create a new output sink. Outputs 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 are created in a similar manner as collection plugins, and their interface has
similar constructs. similar constructs.
### Output Plugin Guidelines ## Output Plugin Guidelines
- An output must conform to the [telegraf.Output][] interface. - An output must conform to the [telegraf.Output][] interface.
- Outputs should call `outputs.Add` in their `init` function to register - 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. - The `Description` function should say in one line what this output does.
- Follow the recommended [Code Style][]. - Follow the recommended [Code Style][].
### Output Plugin Example ## Output Plugin Example
```go ```go
package simpleoutput package simpleoutput
@ -103,6 +103,7 @@ You should also add the following to your `SampleConfig()`:
## Flushing Metrics to Outputs ## Flushing Metrics to Outputs
Metrics are flushed to outputs when any of the following events happen: 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 - `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 - At least `metric_batch_size` count of metrics are waiting in the buffer
- The telegraf process has received a SIGUSR1 signal - The telegraf process has received a SIGUSR1 signal