-
Notifications
You must be signed in to change notification settings - Fork 5.6k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Create external plugins doc file and update contributing guide (#8001)
- v1.33.2
- v1.33.1
- v1.33.0
- v1.32.3
- v1.32.2
- v1.32.1
- v1.32.0
- v1.31.3
- v1.31.2
- v1.31.1
- v1.31.0
- v1.30.3
- v1.30.2
- v1.30.1
- v1.30.0
- v1.29.5
- v1.29.4
- v1.29.3
- v1.29.2
- v1.29.1
- v1.29.0
- v1.28.5
- v1.28.4
- v1.28.3
- v1.28.2
- v1.28.1
- v1.28.0
- v1.27.4
- v1.27.3
- v1.27.2
- v1.27.1
- v1.27.0
- v1.26.3
- v1.26.2
- v1.26.1
- v1.26.0
- v1.25.3
- v1.25.2
- v1.25.1
- v1.25.0
- v1.24.4
- v1.24.3
- v1.24.2
- v1.24.1
- v1.24.0
- v1.23.4
- v1.23.3
- v1.23.2
- v1.23.1
- v1.23.0
- v1.22.4
- v1.22.3
- v1.22.2
- v1.22.1
- v1.22.0
- v1.21.4
- v1.21.3
- v1.21.2
- v1.21.1
- v1.21.0
- v1.21.0-rc1
- v1.21.0-rc0
- v1.20.4
- v1.20.3
- v1.20.2
- v1.20.1
- v1.20.0
- v1.20.0-rc0
- v1.19.3
- v1.19.2
- v1.19.1
- v1.19.0
- v1.19.0-rc1
- v1.19.0-rc0
- v1.18.3
- v1.18.2
- v1.18.1
- v1.18.0
- v1.18.0-rc1
- v1.18.0-rc0
- v1.17.3
- v1.17.2
- v1.17.1
- v1.17.0
- v1.17.0-rc1
- v1.17.0-rc0
- v1.16.3
- v1.16.2
- v1.16.1
- v1.16.0
- v1.16.0-rc2
- v1.16.0-rc1
Showing
2 changed files
with
64 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,60 @@ | ||
### External Plugins | ||
|
||
External plugins are external programs that are built outside of Telegraf that | ||
can run through an `execd` plugin. These external 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 access to libraries not written in Go | ||
- Utilize licensed software that isn't available to the open source community | ||
- Can include large dependencies that would otherwise bloat Telegraf | ||
|
||
### External Plugin Guidelines | ||
The guidelines of writing external plugins would follow those for our general [input](docs/INPUTS.md), | ||
[output](docs/OUTPUTS.md), [processor](docs/PROCESSORS.md), and [aggregator](docs/AGGREGATOR.md) plugins. | ||
Please reference the documentation on how to create these plugins written in Go. | ||
|
||
|
||
#### 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 This allows anyone to build and run it as a separate app using one of the `execd`plugins: | ||
- [inputs.execd](/plugins/inputs/execd) | ||
- [processors.execd](/plugins/processors/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 | ||
|
||
#### Step-by-Step guidelines | ||
This is a guide to help you set up your plugin to use it with `execd` | ||
1. Write your 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) | ||
- [Processor Plugins](/docs/PROCESSORS.md) | ||
- [Aggregator Plugins](/docs/AGGREGATORS.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) | ||
1. Move the project to an external repo, it's recommended to preserve the path | ||
structure, (but not strictly necessary). eg if your plugin was at | ||
`plugins/inputs/cpu`, it's recommended that it also be under `plugins/inputs/cpu` | ||
in the new repo. For a further example of what this might look like, take a | ||
look at [ssoroka/rand](https://github.com/ssoroka/rand) or | ||
[danielnelson/telegraf-execd-openvpn](https://github.com/danielnelson//telegraf-execd-openvpn) | ||
1. Copy [main.go](./example/cmd/main.go) into your project under the `cmd` folder. | ||
This will be the entrypoint to the plugin when run as a stand-alone program, and | ||
it will call the shim code for you to make that happen. It's recommended to | ||
have only one plugin per repo, as the shim is not designed to run multiple | ||
plugins at the same time (it would vastly complicate things). | ||
1. Edit the main.go file to import your plugin. Within Telegraf this would have | ||
been done in an all.go file, but here we don't split the two apart, and the change | ||
just goes in the top of main.go. If you skip this step, your plugin will do nothing. | ||
eg: `_ "github.com/me/my-plugin-telegraf/plugins/inputs/cpu"` | ||
1. 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 | ||
rest of the config for Telegraf, and must not be in a shared directory where | ||
Telegraf is expecting to load all configs**. If Telegraf reads this config file | ||
it will not know which plugin it relates to. Telegraf instead uses an execd config | ||
block to look for this plugin. | ||
|
||
|
||
|
||
|
||
|
||
|