Automated way to expose configuration schema #5006
Comments
|
Definitely. We do this in the SignalFx agent by using the comment associated with the config property along with Go tags for things like default and validation. See https://github.com/signalfx/signalfx-agent/blob/master/pkg/monitors/ntp/ntp.go#L30 for example. I think a similar approach would work here. |
|
@jrcamp +1, struct tags can be a viable way to provide some metadata, although including long description into the tags is pretty inconvenient, those are better as field comments. Did you implement some utility that can extract the schema from structs? To read both tags and comments the tool would be similar to godoc, working off the AST. |
Correct, we use |
|
@jrcamp can we start configuring this for one of the component, and see how will look like? |
|
I've filed a separate issue open-telemetry/opentelemetry-collector#2015 for config validation. Could have some impact on this but don't think it blocks anything, just something to be aware of. |
* POC/Proposal for exposing configuration schemas Issue: https://github.com/open-telemetry/opentelemetry-collector/issues/1995 This change proposes a way to generate metadata for the configuration structs used by Collector components. The generated metadata could be used for documentation and tooling. The way it works is, given a component, its configuration struct is found, and its field names, types, tags, default values, and comments are retrieved and put into a struct. This is done recursively, but respecting "squashed" fields, and any fields omitted with a "-" tag. The final struct is marshaled to a yaml file in the directory of the configuration type. Also included are a simple command line interface and an example metadata file. The CLI lets users create a metadata file for either a given component or for all registered components. Tests have not been included as this change is meant to be exploratory. * Use a map rather than an array for fields * Expose component configuration schemas Issue: https://github.com/open-telemetry/opentelemetry-collector/issues/1995 This change adds a command line utility to generate schema files for each of the configuration structs used by Collector components. The intent is for these generated files to be used by documentation utilities and tooling. The way it works is, given a component, its default configuration struct is retrieved and introspected, producing field names, types, default values, and comments. Those are recursively put into a graph of structs, respecting "squashed" fields and any fields omitted with a "-" tag. Finally, the struct is marshaled to a yaml file in the directory of the configuration type. The CLI lets users create a metadata file for either one component or for all registered components. For reference, preliminary feedback was gathered here #2169 * Create a local go module, don't panic on mapstructure errors * Move code to internal, exclude cfgschema from Makefile * Increase test coverage * Increase test coverage * Fix lint * Reorg so schemagen can be used from contrib * Don't export stuff that no longer needs to be exported
Signed-off-by: Bogdan Drutu <[email protected]>
|
This issue has been inactive for 60 days. It will be closed in 60 days if there is no activity. To ping code owners by adding a component label, see Adding Labels via Comments, or if you are unsure of which component this issue relates to, please ping |
dmitryax
added
never stale
|
This is currently in progress |
Is your feature request related to a problem? Please describe.
Unless I am missing something, there is no authoritative way to generate documentation for the schema of configuration file. There is some manually maintained doc pages with examples, but the authoritative source is the source code of the config structs (e.g. pprof extension). This is pretty difficult for end-users.
For Jaeger binaries built on top of OTEL collector, we could like to do better than that. For example, the current Jaeger configuration can be inspected from the
helpsub-commands and/or auto-generated docs like https://www.jaegertracing.io/docs/1.20/cli/.Describe the solution you'd like
A way to auto-generate readable documentation for configuration options, which means:
.protodefinition or even Go structsThe text was updated successfully, but these errors were encountered: