Grouping flags in help output

[fabxc]

Finding the right flag in prometheus -h is tedious right now. It also doesn't reveal that -config.file is mandatory and Prometheus panics if cannot find one.

Something like below looks way more usable, especially for flags with very long descriptions.
Maybe -config.file should be omittable as well: ./prometheus [options ...] <config_file>.

Usage of ./prometheus [options ...] -config.file=<config_file>:

  -alsologtostderr=false: log to standard error as well as files
  -log_backtrace_at=:0: when logging hits line file:N, emit a stack trace
  - ... 
  - (also, the two flags above are inconsistent)

Alertmanager:
  -alertmanager.http-deadline=10s: Alert manager HTTP API timeout.
  -alertmanager.notification-queue-capacity=100: The capacity of the queue for pending
       alert manager notifications.
  -alertmanager.url=: The URL of the alert manager to send notifications to.

Config:
  -config.file=prometheus.conf: Prometheus configuration file name.

Storage:
  -storage.local.checkpoint-dirty-series-limit=5000: If approx. that many time series are
       in a state that would require a recovery operation after a crash, a checkpoint is
       triggered, even if the checkpoint interval hasn't passed yet. A recovery operation
       requires a disk seek. The default limit intends to keep the recovery time below 1min
       even on spinning disks. With SSD, recovery is much faster, so you might want to
       increase this value in that case to avoid overly frequent checkpoints.
  -storage.local.checkpoint-interval=5m0s: The period at which the in-memory metrics and
       the chunks not yet persisted to series files are checkpointed.
  -storage.local.chunk-encoding-version=1: Which chunk encoding version to use for newly
       created chunks. Currently supported is 0 (delta encoding) and 1 (double-delta
       encoding).
  - ...

...

Web:
  -web.console.libraries=console_libraries: Path to the console library directory.
  -web.console.templates=consoles: Path to the console template directory, available at
       /console.
  - ...

[beorn7]

Unfortunately, the inconsistent flags are coming from glog, so they won't change just because of Prometheus conventions. And changing them just for us doesn't make sense because whoever uses glog in other software should not be surprised here.

A structured usage output needs a re-implementation of the Usage function, and then some code that calls flags.VisitAll and groups the flags by prefix... perhaps a nice warm-up task for our intern... ;-)

[fabxc]

So no objections regarding the general idea, I assume?

[beorn7]

Sounds good. We should just avoid a maintenance nightmare by having to keep a customized usage message up to date. So as long as it still auto-generates the usage message, I'm fine with the above.

[beorn7]

FIxed by #627

[lock]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.