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