github.com/influxdata/telegraf@v1.30.3/docs/EXTERNAL_PLUGINS.md (about)

     1  # External Plugins
     2  
     3  [External plugins](/EXTERNAL_PLUGINS.md) are external programs that are built
     4  outside of Telegraf that can run through an `execd` plugin. These external
     5  plugins allow for more flexibility compared to internal Telegraf plugins.
     6  
     7  - External plugins can be written in any language (internal Telegraf plugins can
     8    only be written in Go)
     9  - External plugins can access to libraries not written in Go
    10  - Utilize licensed software that is not available to the open source community
    11  - Can include large dependencies that would otherwise bloat Telegraf
    12  - You do not need to wait on the Telegraf team to publish the plugin and start
    13    working with it.
    14  - Using the [shim](/plugins/common/shim) you can easily convert plugins between
    15    internal and external use
    16  - Using 3rd-party libraries requiring CGO support
    17  
    18  ## External Plugin Guidelines
    19  
    20  The guidelines of writing external plugins would follow those for our general
    21  [input](/docs/INPUTS.md), [output](/docs/OUTPUTS.md),
    22  [processor](/docs/PROCESSORS.md), and [aggregator](/docs/AGGREGATORS.md)
    23  plugins. Please reference the documentation on how to create these plugins
    24  written in Go.
    25  
    26  _For listed [external plugins](/EXTERNAL_PLUGINS.md), the author of the external
    27  plugin is also responsible for the maintenance and feature development of
    28  external plugins. Expect to have users open plugin issues on its respective
    29  GitHub repository._
    30  
    31  ### Execd Go Shim
    32  
    33  For Go plugins, there is a [Execd Go Shim](/plugins/common/shim/) that will make
    34  it trivial to extract an internal input, processor, or output plugin from the
    35  main Telegraf repo out to a stand-alone repo. This shim allows anyone to build
    36  and run it as a separate app using one of the `execd` plugins:
    37  
    38  - [inputs.execd](/plugins/inputs/execd)
    39  - [processors.execd](/plugins/processors/execd)
    40  - [outputs.execd](/plugins/outputs/execd)
    41  
    42  Follow the [Steps to externalize a plugin][] and
    43  [Steps to build and run your plugin][] to properly with the Execd Go Shim.
    44  
    45  [Steps to externalize a plugin]: /plugins/common/shim#steps-to-externalize-a-plugin
    46  [Steps to build and run your plugin]: /plugins/common/shim#steps-to-build-and-run-your-plugin
    47  
    48  ## Step-by-Step guidelines
    49  
    50  This is a guide to help you set up a plugin to use it with `execd`:
    51  
    52  1. Write a Telegraf plugin. Depending on the plugin, follow the guidelines on
    53    how to create the plugin itself using InfluxData's best practices:
    54     - [Input Plugins](/docs/INPUTS.md)
    55     - [Processor Plugins](/docs/PROCESSORS.md)
    56     - [Aggregator Plugins](/docs/AGGREGATORS.md)
    57     - [Output Plugins](/docs/OUTPUTS.md)
    58  2. Move the project to an external repo, it is recommended to preserve the
    59     path structure, but not strictly necessary. For example, if the plugin was
    60     at `plugins/inputs/cpu`, it is recommended that it also be under
    61     `plugins/inputs/cpu` in the new repo. For a further example of what this
    62     might look like, take a look at [ssoroka/rand][] or
    63     [danielnelson/telegraf-execd-openvpn][].
    64  3. Copy [main.go](/plugins/common/shim/example/cmd/main.go) into the project
    65     under the `cmd` folder. This will be the entrypoint to the plugin when run as
    66     a stand-alone program and it will call the shim code for you to make that
    67     happen. It is recommended to have only one plugin per repo, as the shim is
    68     not designed to run multiple plugins at the same time.
    69  4. Edit the main.go file to import the plugin. Within Telegraf this would have
    70     been done in an all.go file, but here we do not split the two apart, and the
    71     change just goes in the top of main.go. If you skip this step, the plugin
    72     will do nothing.
    73     > `_ "github.com/me/my-plugin-telegraf/plugins/inputs/cpu"`
    74  5. Optionally add a [plugin.conf](./example/cmd/plugin.conf) for configuration
    75     specific to the plugin. Note that this config file **must be separate from
    76     the rest of the config for Telegraf, and must not be in a shared directory
    77     where Telegraf is expecting to load all configs**. If Telegraf reads this
    78     config file it will not know which plugin it relates to. Telegraf instead
    79     uses an execd config block to look for this plugin.
    80  6. Add usage and development instructions in the homepage of the repository
    81     for running the plugin with its respective `execd` plugin. Please refer to
    82     [openvpn install][] and [awsalarms install][] for examples. Include the
    83     following steps:
    84       1. How to download the release package for the platform or how to clone the
    85          binary for the external plugin
    86       1. The commands to build the binary
    87       1. Location to edit the `telegraf.conf`
    88       1. Configuration to run the external plugin with
    89       [inputs.execd](/plugins/inputs/execd),
    90       [processors.execd](/plugins/processors/execd), or
    91       [outputs.execd](/plugins/outputs/execd)
    92  7. Submit the plugin by opening a PR to add the external plugin to the
    93     [/EXTERNAL_PLUGINS.md](/EXTERNAL_PLUGINS.md) list. Please include the
    94     plugin name, link to the plugin repository and a short description of the
    95     plugin.
    96  
    97  [ssoroka/rand]: https://github.com/ssoroka/rand
    98  [danielnelson/telegraf-execd-openvpn]: https://github.com/danielnelson/telegraf-execd-openvpn
    99  [openvpn install]: https://github.com/danielnelson/telegraf-execd-openvpn#usage
   100  [awsalarms install]: https://github.com/vipinvkmenon/awsalarms#installation