Documentation

Use the `execd` shim

This page documents an earlier version of Telegraf. Telegraf v1.25 is the latest stable version. View this page in the v1.25 documentation.

The shim makes it easy to extract an internal input, processor, or output plugin from the main Telegraf repo out to a stand-alone repo. This allows anyone to build and run it as a separate app using one of the execd plugins:

Extract a plugin using the shim wrapper

  1. Move the project to an external repo. We recommend preserving the path structure: for example, if your plugin was located at plugins/inputs/cpu in the Telegraf repo, move it to plugins/inputs/cpu in the new repo.
  2. Copy main.go into your project under the cmd folder. This serves as the entry point to the plugin when run as a stand-alone program.

    The shim isn’t designed to run multiple plugins at the same time, so include only one plugin per repo.

  3. Edit the main.go file to import your plugin. For example,_ "github.com/me/my-plugin-telegraf/plugins/inputs/cpu". See an example of where to edit main.go here.
  4. Add a plugin.conf for configuration specific to your plugin.

    This config file must be separate from the rest of the config for Telegraf, and must not be in a shared directory with other Telegraf configs.

Test and run your plugin

  1. Build the cmd/main.go using the following command with your plugin name: go build -o plugin-name cmd/main.go
  2. Test the binary:
  3. If you’re building a processor or output, first feed valid metrics in on STDIN. Skip this step if you’re building an input.
  4. Test out the binary by running it (for example, ./project-name -config plugin.conf). Metrics will be written to STDOUT. You might need to hit enter or wait for your poll duration to elapse to see data.
  5. Press Ctrl-C to end your test.
  6. Configure Telegraf to call your new plugin binary. For an input, this would look something like:
[[inputs.execd]]
  command = ["/path/to/rand", "-config", "/path/to/plugin.conf"]
  signal = "none"

Refer to the execd plugin documentation for more information.

Publish your plugin

Publishing your plugin to GitHub and open a Pull Request back to the Telegraf repo letting us know about the availability of your external plugin.


Was this page helpful?

Thank you for your feedback!


Linux Package Signing Key Rotation

All signed InfluxData Linux packages have been resigned with an updated key. If using Linux, you may need to update your package configuration to continue to download and verify InfluxData software packages.

For more information, see the Linux Package Signing Key Rotation blog post.

InfluxDB Cloud backed by InfluxDB IOx

All InfluxDB Cloud organizations created on or after January 31, 2023 are backed by the new InfluxDB IOx storage engine. Check the right column of your InfluxDB Cloud organization homepage to see which InfluxDB storage engine you’re using.

If powered by IOx, this is the correct documentation.

If powered by TSM, see the TSM-based InfluxDB Cloud documentation.

InfluxDB Cloud backed by InfluxDB TSM

All InfluxDB Cloud organizations created on or after January 31, 2023 are backed by the new InfluxDB IOx storage engine which enables nearly unlimited series cardinality and SQL query support. Check the right column of your InfluxDB Cloud organization homepage to see which InfluxDB storage engine you’re using.

If powered by TSM, this is the correct documentation.

If powered by IOx, see the IOx-based InfluxDB Cloud documentation.

State of the InfluxDB Cloud (IOx) documentation

The new documentation for InfluxDB Cloud backed by InfluxDB IOx is a work in progress. We are adding new information and content almost daily. Thank you for your patience!

If there is specific information you’re looking for, please submit a documentation issue.