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