github.com/influxdata/telegraf@v1.30.3/docs/OUTPUTS.md (about) 1 # Output Plugins 2 3 This section is for developers who want to create a new output sink. Outputs 4 are created in a similar manner as collection plugins, and their interface has 5 similar constructs. 6 7 ## Output Plugin Guidelines 8 9 - An output must conform to the [telegraf.Output][] interface. 10 - Outputs should call `outputs.Add` in their `init` function to register 11 themselves. See below for a quick example. 12 - To be available within Telegraf itself, plugins must register themselves 13 using a file in `github.com/influxdata/telegraf/plugins/outputs/all` named 14 according to the plugin name. Make sure you also add build-tags to 15 conditionally build the plugin. 16 - Each plugin requires a file called `sample.conf` containing the sample 17 configuration for the plugin in TOML format. 18 Please consult the [Sample Config][] page for the latest style guidelines. 19 - Each plugin `README.md` file should include the `sample.conf` file in a 20 section describing the configuration by specifying a `toml` section in the 21 form `toml @sample.conf`. The specified file(s) are then injected 22 automatically into the Readme. 23 - Follow the recommended [Code Style][]. 24 25 [Sample Config]: /docs/developers/SAMPLE_CONFIG.md 26 [Code Style]: /docs/developers/CODE_STYLE.md 27 [telegraf.Output]: https://godoc.org/github.com/influxdata/telegraf#Output 28 29 ## Data Formats 30 31 Some output plugins, such as the [file][] plugin, can write in any supported 32 [output data formats][]. 33 34 In order to enable this, you must specify a 35 `SetSerializer(serializer serializers.Serializer)` 36 function on the plugin object (see the file plugin for an example), as well as 37 defining `serializer` as a field of the object. 38 39 You can then utilize the serializer internally in your plugin, serializing data 40 before it's written. Telegraf's configuration layer will take care of 41 instantiating and creating the `Serializer` object. 42 43 You should also add the following to your `SampleConfig()`: 44 45 ```toml 46 ## Data format to output. 47 ## Each data format has its own unique set of configuration options, read 48 ## more about them here: 49 ## https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_OUTPUT.md 50 data_format = "influx" 51 ``` 52 53 [file]: /plugins/inputs/file 54 [output data formats]: /docs/DATA_FORMATS_OUTPUT.md 55 56 ## Flushing Metrics to Outputs 57 58 Metrics are flushed to outputs when any of the following events happen: 59 60 - `flush_interval + rand(flush_jitter)` has elapsed since start or the last 61 flush interval 62 - At least `metric_batch_size` count of metrics are waiting in the buffer 63 - The telegraf process has received a SIGUSR1 signal 64 65 Note that if the flush takes longer than the `agent.interval` to write the 66 metrics to the output, user will see a message saying the output: 67 68 > did not complete within its flush interval 69 70 This may mean the output is not keeping up with the flow of metrics, and you may 71 want to look into enabling compression, reducing the size of your metrics or 72 investigate other reasons why the writes might be taking longer than expected. 73 74 ## Output Plugin Example 75 76 ## Registration 77 78 Registration of the plugin on `plugins/outputs/all/simpleoutput.go`: 79 80 ```go 81 //go:build !custom || outputs || outputs.simpleoutput 82 83 package all 84 85 import _ "github.com/influxdata/telegraf/plugins/outputs/simpleoutput" // register plugin 86 87 ``` 88 89 The _build-tags_ in the first line allow to selectively include/exclude your 90 plugin when customizing Telegraf. 91 92 ## Plugin 93 94 Content of your plugin file e.g. `simpleoutput.go` 95 96 ```go 97 //go:generate ../../../tools/readme_config_includer/generator 98 package simpleoutput 99 100 // simpleoutput.go 101 102 import ( 103 _ "embed" 104 105 "github.com/influxdata/telegraf" 106 "github.com/influxdata/telegraf/plugins/outputs" 107 ) 108 109 //go:embed sample.conf 110 var sampleConfig string 111 112 type Simple struct { 113 Ok bool `toml:"ok"` 114 Log telegraf.Logger `toml:"-"` 115 } 116 117 func (*Simple) SampleConfig() string { 118 return sampleConfig 119 } 120 121 // Init is for setup, and validating config. 122 func (s *Simple) Init() error { 123 return nil 124 } 125 126 func (s *Simple) Connect() error { 127 // Make any connection required here 128 return nil 129 } 130 131 func (s *Simple) Close() error { 132 // Close any connections here. 133 // Write will not be called once Close is called, so there is no need to synchronize. 134 return nil 135 } 136 137 // Write should write immediately to the output, and not buffer writes 138 // (Telegraf manages the buffer for you). Returning an error will fail this 139 // batch of writes and the entire batch will be retried automatically. 140 func (s *Simple) Write(metrics []telegraf.Metric) error { 141 for _, metric := range metrics { 142 // write `metric` to the output sink here 143 } 144 return nil 145 } 146 147 func init() { 148 outputs.Add("simpleoutput", func() telegraf.Output { return &Simple{} }) 149 } 150 ```