Document patterns and suggestions for semconv code generation

[lmolkova]

Follow up on #551

Merge requirement checklist

• CONTRIBUTING.md guidelines followed.
• Change log entry added, according to the guidelines in When to add a changelog entry.
  • If your PR does not need a change log, start the PR title with [chore]
• schema-next.yaml updated with changes to existing conventions.

[jsuereth]

This LGTM - Think we should merge and promote this.

I think it may be possible to document weaver here as well, but I'd prefer one recommended solution. Would like to hear from @lquerel if we think weaver is ready for this level of codegen. If weaver is our long-term play for codegen, would be nice to have it be the base recommendation when we reach out beyond java/python.

[lquerel]

@lmolkova and @jsuereth I think Weaver can certainly be used for code generation (this was in fact the first use). I believe that the solution currently proposed in Weaver is more flexible than that supported by a raw Ninja version.

For example, in Weaver, it is possible to generate multiple code files from the same template. It is also possible to define the name of the generated file programmatically. To make life a little easier for those in charge of generating code for semconv in different programming languages, we could go even further by adding some Jinja filters and tests like to_doc_brief and others to be defined based on existing templates.

[lmolkova]

@lquerel @jsuereth

My main goal with this is to document what code generation should produce in terms of stability, structure, naming, etc which should not depend on the tooling.

I've moved the tooling section to be the last and added this note:

Note:
The tooling used for code generation may change to opentelemetry-weaver,
without any breaking changes in the generated code and with minimal changes to generation process and templates.

WDYT?

[Update] we should definitely look into moving codegen to weaver, would be great to have a example similar to #917 but with code.

[lquerel]

@lmolkova

[Update] we should definitely look into moving codegen to weaver, would be great to have a example similar to #917 but with code.

Which repo will be a good example for codegen ?

UPDATE: I can create a PR for the Rust client SDK semconv section.

[lmolkova]

@lquerel

Which repo will be a good example for codegen ?

Java one is the most advanced one that follows the guidance in this doc.

UPDATE: I can create a PR for the Rust client SDK semconv section.

That would be awesome 🙌

Rust is following old undocumented patterns :)

[lquerel]

Java one is the most advanced one that follows the guidance in this doc.

UPDATE: I can create a PR for the Rust client SDK semconv section.

That would be awesome 🙌

Rust is following old undocumented patterns :)

Okay, I will review the Java version and use this experiment as an opportunity to propose a more up-to-date version of the Rust implementation.