Clarify use of double colon (::) notation in Collector config YAML paths

[tiffany76]

Desired feature or idea: The use of a double colon (::) is valid syntax for configuring nested settings in a Collector config (for example, service::telemetry::metrics::level: detailed), but the double colon is not standard YAML notation. The use of the double colon should be explained in the Collector Configuration page.

Additional context: For reference, see #4322 (comment).

[svrnm]

@open-telemetry/collector-approvers @open-telemetry/collector-maintainers please take a look

[mx-psi]

To be clear: service.telemetry.metrics.level is also not standard YAML notation. There is no standard to refer to nested keys in a YAML document as far as I am aware.

[theletterf]

I'd rather use the dot notation, which is more Pythonesque and hence closer to Python? Although depending on the language one might recognize :: as a namespace notation. Slashes are another option.

See https://github.com/wwkimball/yamlpath/wiki/Segments-of-a-YAML-Path

[mx-psi]

The main downside of dot notation I see (which is the reason we use :: for referring to nested keys) is that OpenTelemetry semantic conventions use dots for namespacing and we occasionally use semantic conventions as the name of configuration settings.

To put a concrete example, take the following dockerstats receiver configuration from its README:

receivers:
  docker_stats:
    metrics:
      container.cpu.percent:
        enabled: false
      container.cpu.utilization:
        enabled: true

This configuration disables the container.cpu.percent metric and enables the container.cpu.utilization metric. How do you refer to the setting that does this? Using ::, you have receivers::docker_stats::metrics::container.cpu.percent, but if you use dots it becomes ambiguous (receivers.docker_stats.metrics.container.cpu.percent) and one doesn't know where to split for nesting

[svrnm]

The main downside of dot notation I see (which is the reason we use :: for referring to nested keys) is that OpenTelemetry semantic conventions use dots for namespacing and we occasionally use semantic conventions as the name of configuration settings.

That's a great reason and we should put it that way in the doc, what do you think @tiffany76 ?

[tiffany76]

Sounds good to me, @svrnm, @mx-psi . I will make the addition today. Thanks!