From e3c7c8db975ffccbacbecffdaf2392240083fc39 Mon Sep 17 00:00:00 2001 From: Samantha Wang <32681364+sjwang90@users.noreply.github.com> Date: Thu, 3 Sep 2020 13:31:29 -0700 Subject: [PATCH] add guidelines run to external plugins with execd (#8054) * docs - add guidelines run to external plugins with execd --- EXTERNAL_PLUGINS.md | 4 +++- docs/EXTERNAL_PLUGINS.md | 23 ++++++++++++++++++++--- 2 files changed, 23 insertions(+), 4 deletions(-) diff --git a/EXTERNAL_PLUGINS.md b/EXTERNAL_PLUGINS.md index 07c917e996c68..9b0907e08750b 100644 --- a/EXTERNAL_PLUGINS.md +++ b/EXTERNAL_PLUGINS.md @@ -1,9 +1,11 @@ # External Plugins -This is a list of plugins that can be compiled outside of Telegraf and used via the execd input. +This is a list of plugins that can be compiled outside of Telegraf and used via the `execd` [input](plugins/inputs/execd), [output](plugins/outputs/execd), or [processor](plugins/processors/execd). +Check out the [external plugin documentation](/docs/EXTERNAL_PLUGINS.md) for more information on writing and contributing a plugin. Pull requests welcome. + ## Inputs - [rand](https://github.com/ssoroka/rand) - Generate random numbers - [twitter](https://github.com/inabagumi/twitter-telegraf-plugin) - Gather account information from Twitter accounts diff --git a/docs/EXTERNAL_PLUGINS.md b/docs/EXTERNAL_PLUGINS.md index 33793275f839e..5e9d42b7bdd1f 100644 --- a/docs/EXTERNAL_PLUGINS.md +++ b/docs/EXTERNAL_PLUGINS.md @@ -1,8 +1,8 @@ ### 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](/EXTERNAL_PLUGINS.md) 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 @@ -14,6 +14,8 @@ The guidelines of writing external plugins would follow those for our general [i [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. +_For listed [external plugins](/EXTERNAL_PLUGINS.md), the author of the external 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 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: @@ -52,6 +54,21 @@ This is a guide to help you set up your plugin to use it with `execd` 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. + 1. Add usage and development instructions in the homepage of your repository for running + your plugin with its respective `execd` plugin. Please refer to + [openvpn](/danielnelson/telegraf-execd-openvpn#usage) and [awsalarms](/vipinvkmenon/awsalarms#installation) + for examples. Include the following steps: + 1. How to download the release package for your platform or how to clone the binary for your external plugin + 1. The commands to unpack or build your binary + 1. Location to edit your `telegraf.conf` + 1. Configuration to run your external plugin with [inputs.execd](/plugins/inputs/execd), + [processors.execd](/plugins/processors/execd) or [outputs.execd](/plugins/outputs/execd) + 1. Note that restart or reload of Telegraf is required + 1. Submit your plugin by opening a PR to add your 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. + + +