Documenting supported arguments

[kaspergrubbe]

Feature Request

We're using Monit to monitor some parts of our infrastructure, and it prefers to have a pid-file to work with.

First I looked to see if the Telegraf agent supported maintaining its pidfile:

$ /usr/local/sbin/telegraf -h
Telegraf, The plugin-driven server agent for collecting and reporting metrics.

Usage:

  telegraf [commands|flags]

The commands & flags are:

  config              print out full sample configuration to stdout
  version             print the version to stdout

  --config <file>     configuration file to load
  --test              gather metrics once, print them to stdout, and exit
  --config-directory  directory containing additional *.conf files
  --input-filter      filter the input plugins to enable, separator is :
  --output-filter     filter the output plugins to enable, separator is :
  --usage             print usage for a plugin, ie, 'telegraf --usage mysql'
  --debug             print metrics as they're generated to stdout
  --pprof-addr        pprof address to listen on, format: localhost:6060 or :6060
  --quiet             run in quiet mode

Examples:

  # generate a telegraf config file:
  telegraf config > telegraf.conf

  # generate config with only cpu input & influxdb output plugins defined
  telegraf --input-filter cpu --output-filter influxdb config

  # run a single telegraf collection, outputing metrics to stdout
  telegraf --config telegraf.conf --test

  # run telegraf with all plugins defined in config file
  telegraf --config telegraf.conf

  # run telegraf, enabling the cpu & memory input, and influxdb output plugins
  telegraf --config telegraf.conf --input-filter cpu:mem --output-filter influxdb

  # run telegraf with pprof
  telegraf --config telegraf.conf --pprof-addr localhost:6060

Okay, nothing about a pidfile, so I guess not. But just to be sure, I will Google it. I then stumble upon issue #2566 by @visionarywind which I understand that it does not seem to be a supported feature.

Alright, so now I have to write my own init-script to start telegraf and write its pid to a pidfile, I start this, and then decide to look in the telegraf repo to see if someone else have done some of the job for me.

And then I stumble upon this line:

telegraf/scripts/init.sh

Line 145 in 0759c8b

su -s /bin/sh -c "nohup $daemon -pidfile $pidfile -config $config -config-directory $confdir $TELEGRAF_OPTS >>$STDOUT 2>>$STDERR &" $USER

That passes -pidfile $pidfile to telegraf.

Which leads me to this bit of code:

telegraf/cmd/telegraf/telegraf.go

Line 41 in 40fac0a

var fPidfile = flag.String("pidfile", "", "file to write our pid to")

And this:

telegraf/cmd/telegraf/telegraf.go

Lines 175 to 191 in 40fac0a

	if *fPidfile != "" {
	f, err := os.OpenFile(*fPidfile, os.O_CREATE|os.O_WRONLY, 0644)
	if err != nil {
	log.Printf("E! Unable to create pidfile: %s", err)
	} else {
	fmt.Fprintf(f, "%d\n", os.Getpid())
	f.Close()
	defer func() {
	err := os.Remove(*fPidfile)
	if err != nil {
	log.Printf("E! Unable to remove pidfile: %s", err)
	}
	}()
	}
	}

Am I missing some documentation somewhere? How was I supposed to find this argument without looking in the code?

Proposal:

Add tunables and supported arguments to -h.

Current behavior:

-h does not list all supported arguments.

Desired behavior:

-h should list all supported arguments.

Use case: [Why is this important (helps with prioritizing requests)]

Making discoverability hard, wastes time, and turns people off using Telegraf.