CL-Softwares
/
telegraf
8
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Update external plugin docs (#15370)

This commit is contained in:
Joshua Powers 2024-05-17 02:13:00 -06:00 committed by GitHub
parent 5ec23fbf2a
commit 5239c97ce0
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 76 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

126
docs/EXTERNAL_PLUGINS.md
View File

@ -1,74 +1,100 @@
# External Plugins # External Plugins
[External plugins](/EXTERNAL_PLUGINS.md) are external programs that are built outside [External plugins](/EXTERNAL_PLUGINS.md) are external programs that are built
of Telegraf that can run through an `execd` plugin. These external plugins allow for outside of Telegraf that can run through an `execd` plugin. These external
more flexibility compared to internal Telegraf plugins. plugins allow for more flexibility compared to internal Telegraf plugins.
- External plugins can be written in any language (internal Telegraf plugins can only written in Go) - External plugins can be written in any language (internal Telegraf plugins can
only be written in Go)
- External plugins can access to libraries not written in Go - External plugins can access to libraries not written in Go
- Utilize licensed software that isn't available to the open source community - Utilize licensed software that is not available to the open source community
- Can include large dependencies that would otherwise bloat Telegraf - Can include large dependencies that would otherwise bloat Telegraf
- You don't need to wait on the Telegraf team to publish your plugin and start working with it. - You do not need to wait on the Telegraf team to publish the plugin and start
- using the [shim](/plugins/common/shim) you can easily convert plugins between internal and external use working with it.
- Using the [shim](/plugins/common/shim) you can easily convert plugins between
internal and external use
- Using 3rd-party libraries requiring CGO support
## External Plugin Guidelines ## External Plugin Guidelines
The guidelines of writing external plugins would follow those for our general [input](/docs/INPUTS.md), The guidelines of writing external plugins would follow those for our general
[output](/docs/OUTPUTS.md), [processor](/docs/PROCESSORS.md), and [aggregator](/docs/AGGREGATORS.md) plugins. [input](/docs/INPUTS.md), [output](/docs/OUTPUTS.md),
Please reference the documentation on how to create these plugins written in Go. [processor](/docs/PROCESSORS.md), and [aggregator](/docs/AGGREGATORS.md)
plugins. Please reference the documentation on how to create these plugins
written in Go.
_For listed [external plugins](/EXTERNAL_PLUGINS.md), the author of the external plugin is also responsible for the maintenance _For listed [external plugins](/EXTERNAL_PLUGINS.md), the author of the external
and feature development of external plugins. Expect to have users open plugin issues on its respective GitHub repository._ plugin is also responsible for the maintenance and feature development of
external plugins. Expect to have users open plugin issues on its respective
GitHub repository._
### Execd Go Shim ### Execd Go Shim
For Go plugins, there is a [Execd Go Shim](/plugins/common/shim/) that will make it trivial to extract an internal input, processor, or output plugin from the main Telegraf repo out to a stand-alone repo. This shim allows anyone to build and run it as a separate app using one of the `execd`plugins: For Go plugins, there is a [Execd Go Shim](/plugins/common/shim/) that will make
it trivial to extract an internal input, processor, or output plugin from the
main Telegraf repo out to a stand-alone repo. This shim allows anyone to build
and run it as a separate app using one of the `execd` plugins:
- [inputs.execd](/plugins/inputs/execd) - [inputs.execd](/plugins/inputs/execd)
- [processors.execd](/plugins/processors/execd) - [processors.execd](/plugins/processors/execd)
- [outputs.execd](/plugins/outputs/execd) - [outputs.execd](/plugins/outputs/execd)
Follow the [Steps to externalize a plugin](/plugins/common/shim#steps-to-externalize-a-plugin) and [Steps to build and run your plugin](/plugins/common/shim#steps-to-build-and-run-your-plugin) to properly with the Execd Go Shim Follow the [Steps to externalize a plugin][] and
[Steps to build and run your plugin][] to properly with the Execd Go Shim.
### Step-by-Step guidelines [Steps to externalize a plugin]: /plugins/common/shim#steps-to-externalize-a-plugin
[Steps to build and run your plugin]: /plugins/common/shim#steps-to-build-and-run-your-plugin
This is a guide to help you set up your plugin to use it with `execd`: ## Step-by-Step guidelines
1. Write your Telegraf plugin. Depending on the plugin, follow the guidelines on how to create the plugin itself using InfluxData's best practices: This is a guide to help you set up a plugin to use it with `execd`:
1. Write a Telegraf plugin. Depending on the plugin, follow the guidelines on
how to create the plugin itself using InfluxData's best practices:
- [Input Plugins](/docs/INPUTS.md) - [Input Plugins](/docs/INPUTS.md)
- [Processor Plugins](/docs/PROCESSORS.md) - [Processor Plugins](/docs/PROCESSORS.md)
- [Aggregator Plugins](/docs/AGGREGATORS.md) - [Aggregator Plugins](/docs/AGGREGATORS.md)
- [Output Plugins](/docs/OUTPUTS.md) - [Output Plugins](/docs/OUTPUTS.md)
2. If your plugin is written in Go, include the steps for the [Execd Go Shim](/plugins/common/shim#steps-to-build-and-run-your-plugin) 2. Move the project to an external repo, it is recommended to preserve the
- Move the project to an external repo, it's recommended to preserve the path path structure, but not strictly necessary. For example, if the plugin was
structure, (but not strictly necessary). eg if your plugin was at at `plugins/inputs/cpu`, it is recommended that it also be under
`plugins/inputs/cpu`, it's recommended that it also be under `plugins/inputs/cpu` `plugins/inputs/cpu` in the new repo. For a further example of what this
in the new repo. For a further example of what this might look like, take a might look like, take a look at [ssoroka/rand][] or
look at [ssoroka/rand](https://github.com/ssoroka/rand) or [danielnelson/telegraf-execd-openvpn][].
[danielnelson/telegraf-execd-openvpn](https://github.com/danielnelson//telegraf-execd-openvpn) 3. Copy [main.go](/plugins/common/shim/example/cmd/main.go) into the project
- Copy [main.go](/plugins/common/shim/example/cmd/main.go) into your project under the `cmd` folder. under the `cmd` folder. This will be the entrypoint to the plugin when run as
This will be the entrypoint to the plugin when run as a stand-alone program, and a stand-alone program and it will call the shim code for you to make that
it will call the shim code for you to make that happen. It's recommended to happen. It is recommended to have only one plugin per repo, as the shim is
have only one plugin per repo, as the shim is not designed to run multiple not designed to run multiple plugins at the same time.
plugins at the same time (it would vastly complicate things). 4. Edit the main.go file to import the plugin. Within Telegraf this would have
- Edit the main.go file to import your plugin. Within Telegraf this would have been done in an all.go file, but here we do not split the two apart, and the
been done in an all.go file, but here we don't split the two apart, and the change change just goes in the top of main.go. If you skip this step, the plugin
just goes in the top of main.go. If you skip this step, your plugin will do nothing. will do nothing.
eg: `_ "github.com/me/my-plugin-telegraf/plugins/inputs/cpu"` > `_ "github.com/me/my-plugin-telegraf/plugins/inputs/cpu"`
- Optionally add a [plugin.conf](./example/cmd/plugin.conf) for configuration 5. Optionally add a [plugin.conf](./example/cmd/plugin.conf) for configuration
specific to your plugin. Note that this config file **must be separate from the specific to the plugin. Note that this config file **must be separate from
rest of the config for Telegraf, and must not be in a shared directory where the rest of the config for Telegraf, and must not be in a shared directory
Telegraf is expecting to load all configs**. If Telegraf reads this config file where Telegraf is expecting to load all configs**. If Telegraf reads this
it will not know which plugin it relates to. Telegraf instead uses an execd config config file it will not know which plugin it relates to. Telegraf instead
block to look for this plugin. uses an execd config block to look for this plugin.
- Add usage and development instructions in the homepage of your repository for running 6. Add usage and development instructions in the homepage of the repository
your plugin with its respective `execd` plugin. Please refer to for running the plugin with its respective `execd` plugin. Please refer to
[openvpn](https://github.com/danielnelson/telegraf-execd-openvpn#usage) and [awsalarms](https://github.com/vipinvkmenon/awsalarms#installation) [openvpn install][] and [awsalarms install][] for examples. Include the
for examples. Include the following steps: following steps:
1. How to download the release package for your platform or how to clone the binary for your external plugin 1. How to download the release package for the platform or how to clone the
1. The commands to build your binary binary for the external plugin
1. Location to edit your `telegraf.conf` 1. The commands to build the binary
1. Configuration to run your external plugin with [inputs.execd](/plugins/inputs/execd), 1. Location to edit the `telegraf.conf`
[processors.execd](/plugins/processors/execd) or [outputs.execd](/plugins/outputs/execd) 1. Configuration to run the external plugin with
- Submit your plugin by opening a PR to add your external plugin to the [/EXTERNAL_PLUGINS.md](/EXTERNAL_PLUGINS.md) [inputs.execd](/plugins/inputs/execd),
list. Please include the plugin name, link to the plugin repository and a short description of the plugin. [processors.execd](/plugins/processors/execd), or
[outputs.execd](/plugins/outputs/execd)
7. Submit the plugin by opening a PR to add the external plugin to the
[/EXTERNAL_PLUGINS.md](/EXTERNAL_PLUGINS.md) list. Please include the
plugin name, link to the plugin repository and a short description of the
plugin.
[ssoroka/rand]: https://github.com/ssoroka/rand
[danielnelson/telegraf-execd-openvpn]: https://github.com/danielnelson/telegraf-execd-openvpn
[openvpn install]: https://github.com/danielnelson/telegraf-execd-openvpn#usage
[awsalarms install]: https://github.com/vipinvkmenon/awsalarms#installation