Rewrite the Telegraf CLI

[powersj]

Feature Request

Opening a feature request kicks off a discussion.

Proposal:

The current CLI options and flags have naturally grown over the 6-7 years as the capabilities of Telegraf have grown. However, there are some best practices and consistencies that Telegraf's CLI could use. For example, having Telegraf follow the format telegraf <subcommand> <options> for all operations.

Internally, options are duplicated across declaration + documentation and it is commonly out of date missing values, or entirely wrong.

In doing this, the Telegraf binary can also grow new features more easily and have them contained to specific subcommands.

Desired behavior:

$ ./telegraf
The plugin-driven server agent for collecting and reporting metrics.

Telegraf is a plugin-driven agent and has the concept of 4 distinct plugin types:
  1. Input Plugins: collect metrics from the system, services, or 3rd party APIs
  2. Output Plugins: write metrics to various destinations
  3. Processor Plugins: transform, decorate, and/or filter metrics
  4. Aggregator Plugins: create aggregate metrics (e.g. mean, min, max, quantiles, etc.)
 
Usage:
  telegraf [flags]
  telegraf [command]

Available Commands:
  config     Get example config
  help       Help about any command
  list       List available plugins
  minify     Build minimal telegraf based on a config
  run        Run telegraf with a provided config
  version    Print version of Telegraf

I would be a big fan of implementing this with urfave/cli as it is lightweight and well documented.

As a part of this effort each option will need to be tested to ensure operation across Windows, macOS, and Linux/BSD environments.

See #9835, #10356 #8854 for other related CLI issues

[powersj]

next steps: flush out all the details of what commands, subcommands, and test matrix for each.

[sjwang90]

We'll want to make sure people who have scripts that are using the current commands won't have too many issues with any rewrite.

[sspaink]

Telegraf is now using urfave/cli, the next step is to begin migrating to use commands over flags. Breaking out the tasks into separate issues:

• Add new command to list deprecation and plugins #11739
• Add new command run to replace --config and --config-directory #11740
• Deprecate global plugin filter flags #11741

I am not sure about adding minify command, this would mean integrating the custom_builder tool somehow into Telegraf.

[sspaink]

Future discussion points:

• Consider deprecate --usage flag in favor of using filtering with sample config
• Consider not doing "run" to avoid causing too much inconvenience for existing users
• Discuss list command, one word (list deprecation) or two words (list-deprecation)
• Discuss design for potential future features that would need flags or commands (example --watch-config remote)

[powersj]

As we are not planning on doing a Telegraf 2.x at this time anymore, I am closing breaking changes issues and PRs. While we have interest in making these improvements we currently, and for the foreseeable future do not have the capital to maintain two major versions while also supporting our users at the same level.