docs(outputs): Clean up, reorder (#15358)
This commit is contained in:
Joshua Powers
GitHub
parent
8a93207967
commit
24b9efe746
131
docs/OUTPUTS.md
131
docs/OUTPUTS.md
|
|
@ -16,12 +16,81 @@ similar constructs.
|
|||
- Each plugin requires a file called `sample.conf` containing the sample
|
||||
configuration for the plugin in TOML format.
|
||||
Please consult the [Sample Config][] page for the latest style guidelines.
|
||||
- Each plugin `README.md` file should include the `sample.conf` file in a section
|
||||
describing the configuration by specifying a `toml` section in the form `toml @sample.conf`. The specified file(s) are then injected automatically into the Readme.
|
||||
- Each plugin `README.md` file should include the `sample.conf` file in a
|
||||
section describing the configuration by specifying a `toml` section in the
|
||||
form `toml @sample.conf`. The specified file(s) are then injected
|
||||
automatically into the Readme.
|
||||
- Follow the recommended [Code Style][].
|
||||
|
||||
[Sample Config]: /docs/developers/SAMPLE_CONFIG.md
|
||||
[Code Style]: /docs/developers/CODE_STYLE.md
|
||||
[telegraf.Output]: https://godoc.org/github.com/influxdata/telegraf#Output
|
||||
|
||||
## Data Formats
|
||||
|
||||
Some output plugins, such as the [file][] plugin, can write in any supported
|
||||
[output data formats][].
|
||||
|
||||
In order to enable this, you must specify a
|
||||
`SetSerializer(serializer serializers.Serializer)`
|
||||
function on the plugin object (see the file plugin for an example), as well as
|
||||
defining `serializer` as a field of the object.
|
||||
|
||||
You can then utilize the serializer internally in your plugin, serializing data
|
||||
before it's written. Telegraf's configuration layer will take care of
|
||||
instantiating and creating the `Serializer` object.
|
||||
|
||||
You should also add the following to your `SampleConfig()`:
|
||||
|
||||
```toml
|
||||
## Data format to output.
|
||||
## Each data format has its own unique set of configuration options, read
|
||||
## more about them here:
|
||||
## https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_OUTPUT.md
|
||||
data_format = "influx"
|
||||
```
|
||||
|
||||
[file]: /plugins/inputs/file
|
||||
[output data formats]: /docs/DATA_FORMATS_OUTPUT.md
|
||||
|
||||
## 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
|
||||
|
||||
Note that if the flush takes longer than the `agent.interval` to write the
|
||||
metrics to the output, user will see a message saying the output:
|
||||
|
||||
> did not complete within its flush interval
|
||||
|
||||
This may mean the output is not keeping up with the flow of metrics, and you may
|
||||
want to look into enabling compression, reducing the size of your metrics or
|
||||
investigate other reasons why the writes might be taking longer than expected.
|
||||
|
||||
## Output Plugin Example
|
||||
|
||||
## Registration
|
||||
|
||||
Registration of the plugin on `plugins/outputs/all/simpleoutput.go`:
|
||||
|
||||
```go
|
||||
//go:build !custom || outputs || outputs.simpleoutput
|
||||
|
||||
package all
|
||||
|
||||
import _ "github.com/influxdata/telegraf/plugins/outputs/simpleoutput" // register plugin
|
||||
|
||||
```
|
||||
|
||||
The _build-tags_ in the first line allow to selectively include/exclude your
|
||||
plugin when customizing Telegraf.
|
||||
|
||||
## Plugin
|
||||
|
||||
Content of your plugin file e.g. `simpleoutput.go`
|
||||
|
||||
```go
|
||||
|
|
@ -79,61 +148,3 @@ func init() {
|
|||
outputs.Add("simpleoutput", func() telegraf.Output { return &Simple{} })
|
||||
}
|
||||
```
|
||||
|
||||
Registration of the plugin on `plugins/outputs/all/simpleoutput.go`:
|
||||
|
||||
```go
|
||||
//go:build !custom || outputs || outputs.simpleoutput
|
||||
|
||||
package all
|
||||
|
||||
import _ "github.com/influxdata/telegraf/plugins/outputs/simpleoutput" // register plugin
|
||||
|
||||
```
|
||||
|
||||
The _build-tags_ in the first line allow to selectively include/exclude your
|
||||
plugin when customizing Telegraf.
|
||||
|
||||
## Data Formats
|
||||
|
||||
Some output plugins, such as the [file][] plugin, can write in any supported
|
||||
[output data formats][].
|
||||
|
||||
In order to enable this, you must specify a
|
||||
`SetSerializer(serializer serializers.Serializer)`
|
||||
function on the plugin object (see the file plugin for an example), as well as
|
||||
defining `serializer` as a field of the object.
|
||||
|
||||
You can then utilize the serializer internally in your plugin, serializing data
|
||||
before it's written. Telegraf's configuration layer will take care of
|
||||
instantiating and creating the `Serializer` object.
|
||||
|
||||
You should also add the following to your `SampleConfig()`:
|
||||
|
||||
```toml
|
||||
## Data format to output.
|
||||
## Each data format has its own unique set of configuration options, read
|
||||
## more about them here:
|
||||
## https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_OUTPUT.md
|
||||
data_format = "influx"
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
Note that if the flush takes longer than the `agent.interval` to write the metrics
|
||||
to the output, you'll see a message saying the output `did not complete within its
|
||||
flush interval`. This may mean your output is not keeping up with the flow of metrics,
|
||||
and you may want to look into enabling compression, reducing the size of your metrics,
|
||||
or investigate other reasons why the writes might be taking longer than expected.
|
||||
|
||||
[file]: https://github.com/influxdata/telegraf/tree/master/plugins/inputs/file
|
||||
[output data formats]: https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_OUTPUT.md
|
||||
[Sample Config]: https://github.com/influxdata/telegraf/blob/master/docs/developers/SAMPLE_CONFIG.md
|
||||
[Code Style]: https://github.com/influxdata/telegraf/blob/master/docs/developers/CODE_STYLE.md
|
||||
[telegraf.Output]: https://godoc.org/github.com/influxdata/telegraf#Output
|
||||
|
|
|
|||
Loading…
Reference in New Issue