Add metrics storage support to auto-generated CLI documentation

[albertteoh]

Signed-off-by: albertteoh see.kwang.teoh@gmail.com

Which problem is this PR solving?

• Relates to "Monitor" tab for service health metrics jaeger#2954

Short description of the changes

• Adds support for metrics-storage to the auto-generated documentation.
• Minor improvements:
  • Taking advantage of python 3 features such as f-strings along with some simplifications.
  • Fix variable names and titles in template.

Testing

Generated CLI docs against version 1.28 to allow output comparison.

# Only prometheus-related files were added.
$ diff -q /home/go/src/github.com/albertteoh/documentation/data/cli/1.28/ /tmp/docs/data/cli/1.28
Files /home/go/src/github.com/albertteoh/documentation/data/cli/1.28/config.json and /tmp/docs/data/cli/1.28/config.json differ
Only in /tmp/docs/data/cli/1.28: jaeger-all-in-one-prometheus.yaml
Only in /tmp/docs/data/cli/1.28: jaeger-query-prometheus.yaml

# Only prometheus flags added to these files.
$ diff /home/go/src/github.com/albertteoh/documentation/data/cli/1.28/jaeger-all-in-one.yaml /tmp/docs/data/cli/1.28/jaeger-all-in-one-prometheus.yaml
150a151,177
> - name: prometheus.connect-timeout
>   default_value: 30s
>   usage: |
>     The period to wait for a connection to Prometheus when executing queries.
> - name: prometheus.server-url
>   default_value: http://localhost:9090
>   usage: |
>     The Prometheus server's URL, must include the protocol scheme e.g. http://localhost:9090
> - name: prometheus.tls.ca
>   usage: |
>     Path to a TLS CA (Certification Authority) file used to verify the remote server(s) (by default will use the system truststore)
> - name: prometheus.tls.cert
>   usage: |
>     Path to a TLS Certificate file, used to identify this process to the remote server(s)
> - name: prometheus.tls.enabled
>   default_value: "false"
>   usage: Enable TLS when talking to the remote server(s)
> - name: prometheus.tls.key
>   usage: |
>     Path to a TLS Private Key file, used to identify this process to the remote server(s)
> - name: prometheus.tls.server-name
>   usage: |
>     Override the TLS server name we expect in the certificate of the remote server(s)
> - name: prometheus.tls.skip-host-verify
>   default_value: "false"
>   usage: |
>     (insecure) Skip server's certificate chain and host name verification

Copied generated doc files to documentation/data/cli/1.28/ and ran make develop. The following are relevant screenshots of the rendered changes made in this PR:

[albertteoh]

Before: "... with adaptive"
After: "... with adaptive sampling"

[albertteoh]

Before: "... with adaptive sampling type"
After: "... with adaptive sampling"

[albertteoh]

These ifs were redundant as a "zero" value of a list just means the body of the for loop won't be executed.

[albertteoh]

I think using kwargs would be simpler and cleaner than adding another "optional" parameter to support metrics storage, especially avoiding the need to extend the storageOrSampling variable.

[yurishkuro]

I think we need to rethink the organization of this doc. Each entry repeats a lot of options not related to the given storage type. It was sort of ok when there was only one dimension we could vary, now we have three.

What if we had a "core flags" section first and then each storage type would only list additional flags it enables? Could we isolate those extra flags by a common prefix?

[jpkrohling]

I think we need to rethink the organization of this doc.

For this PR, or for the future? Should I wait on this one to release the new docs for 1.29.0?

[yurishkuro]

For this PR, or for the future? Should I wait on this one to release the new docs for 1.29.0?

Well, I guess since we're right in the middle of the release we should merge this as is and refactor later.

[albertteoh]

I think we need to rethink the organization of this doc. Each entry repeats a lot of options not related to the given storage type. It was sort of ok when there was only one dimension we could vary, now we have three.

What if we had a "core flags" section first and then each storage type would only list additional flags it enables? Could we isolate those extra flags by a common prefix?

I agree that the page has a lot of duplicated flags; I'd originally thought that was by design so all possible flags are localised to that particular configuration to avoid jumping around different sections of the document.

I've created a follow-up ticket to discuss and/or address this concern: #541