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