Opentelemetry-specification: Proposal: Define semantic conventions in JSON/YAML

[bogdandrutu]

This is a proposal to define all semantic conventions in a format that can be automatically parse by every language and generate constants without having to manually sync their constant definitions with the markdown text in this repository:

1. Move definitions in opentelemetry-semantic-conventions - languages can use git submodules to reference to that repository
2. Specificantion will automatically generate tabels like https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-http.md#common-attributes when the git submodule is updated.
3. Languages will automatically re-generate all constants when git submodule is updated.

This will allow us to keep consistency between languages and consistent description for every semantic convention defined.

Open questions:

1. Which format to use JSON/YAML/etc.?
2. Does anyone know about a tool to generate the markdown tables from the JSON? A simple tool can be written, but would like to avoid that.
3. Should languages generate the constant code or read the files at runtime?
   
   
   
   • Personally I prefer generated code - fast initialization, compiler optimizations, etc.
   
   

[dyladan]

Very interested in something like this

[carlosalberto]

Sounds about the right time to implement this one. On the specific points, for 3) I'd also vow for generated code. No strong opinion/feedback on the other two.

[bogdandrutu]

Please +/- 1 the initial comment to count how many lgtms we have

[thisthat]

I like the idea! I am currently working exactly on this based on a yaml representation. Our plan was to propose this once the code generation tool was implemented for multiple languages. We could propose a PR with our current yaml representation and start discussing if the model makes sense to everyone :smile:

[bogdandrutu]

@thisthat would be good to share why you decided on yaml in your experiment? May help us with the decision yaml vs json.

[Oberon00]

I'd say JSON is not usable for human-written code, as it does not support comments. That's a killer-argument, as far as I'm concerned.

[thisthat]

At the current status, it is more than just an experiment since we are close to having the code generation. To answer your question @bogdandrutu: both have the same expressiveness power, are well known by the community, and have great tooling support, but yaml is more compact as a representation and has the possibility to have comments that can aid the readability/maintainability of the semantic convention.

[tedsuo]

Guys this is a great opportunity to write our own config language and custom parser! j/k

@thisthat I'm curious about what metadata you would want included with each entry, if the purpose is for code generation.

An old (partial) implementation from the OpenTracing days: https://github.com/opentracing/specification/blob/master/semantic_conventions.yaml

[thisthat]

@tedsuo for code generation I mean:

• generate constant values, e.g. https://github.com/open-telemetry/opentelemetry-java/blob/master/api/src/main/java/io/opentelemetry/trace/attributes/SemanticAttributes.java
• generate typed spans, e.g. https://github.com/open-telemetry/opentelemetry-java/pull/964 or https://github.com/danielkhan/opencensus-node-typed-span-sample