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

124
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.
### 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()
})
}
```

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
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_

16
docs/COMMANDS_AND_FLAGS.md
View File

@ -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>` |filter the aggregators to enable, separator is `:`|
|`--config <file>` |configuration file to load|
|`--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.|
|`--debug` |turn on debug logging|
|`--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|
|`--processor-filter <filter>` |filter the processors to enable, separator is `:`|
|`--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|
|`--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 <plugin>` |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:**

67
docs/CONFIGURATION.md
View File

@ -1,3 +1,5 @@
<!-- markdownlint-disable MD024 -->
# 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"]
```
<a id="measurement-filtering"></a>
### 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.

79
docs/EXTERNAL_PLUGINS.md
View File

@ -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.

33
docs/FAQ.md
View File

@ -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

12
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.
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.

61
docs/INTEGRATION_TESTS.md
View File

@ -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 |

9
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
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