Separation of attribute definitions from attribute usages: HTTP

[AlexanderWert]

This PR demonstrates how changes will look like when refactoring semantic conventions model files for the purpose of separating attribute definitions from attribute usages in concrete semantic conventions.

The changes here:

• All http.* attributes are defined under /model/registry/http.yaml. Here, all attributes are defined as opt_in.
• All usages of those attributes only reference the attributes and overwrite the requirement level to keep the original requirement level at the place of usage.
• Changes in the markdown files (through table generation) are limited to:
  • adding links to the attributes registry for the individual attributes
  • (because of the way markdown table generation works) the order of attributes (and corresponding notes) changes (which is better because it's in an alphabetical order)
• There's a new section in the markdown docs attributes-dictionary/* that is the place to list all the available attributes in one place, grouped by the namespace (here: only http.md so far).

[Oberon00]

Here, all attributes are defined as opt_in.

I think this is a bit weird. Probably we'd want a specific requirement type like "needs-to-be-defind-on-usage-or-error". Otherwise I'd stay with "recommended" as default, since that is the one with the fewest requirements (opt-in requires you to either not implement it or provide some explicit configuration option if you implement it; recommended requires no implementation, but if you implement it you can do so w/o configuration option)

[AlexanderWert]

Here, all attributes are defined as opt_in.

I think this is a bit weird. Probably we'd want a specific requirement type like "needs-to-be-defind-on-usage-or-error". Otherwise I'd stay with "recommended" as default, since that is the one with the fewest requirements (opt-in requires you to either not implement it or provide some explicit configuration option if you implement it; recommended requires no implementation, but if you implement it you can do so w/o configuration option)

Agree with that! Also see my comment here: #197 (comment)

I just think we could do it in a second step.

[Oberon00]

Then, why use opt-in in the first step instead of the default?

[AlexanderWert]

Then, why use opt-in in the first step instead of the default?

I'm also fine with leaving the default (recommended). We just should make sure later on that the requirement level is not being rendered in the dictionary page (because there it does not make sense).

Similar, to https://opentelemetry.io/docs/specs/semconv/url/url/, where requirement-level doesn't make any sense.

[AlexanderWert]

@open-telemetry/specs-semconv-approvers As discussed in this week's semconv WG, this is the first PR to start refactoring yaml files as described in Step1 of this proposal.

Please also have a look at open-telemetry/build-tools#190, which would help with rendering the registry pages properly (without the requirement level column in the tables).

[joaopgrassi]

I think this looks pretty good!

[AlexanderWert]

@open-telemetry/specs-semconv-approvers Can I get another round of reviews for this? Thanks!

[AlexanderWert]

Added the usage of omit_requirement_level. Now, the registry table doesn't show the requirement level column anymore.

@open-telemetry/specs-semconv-approvers, @open-telemetry/specs-semconv-maintainers Are we good to proceed with that?

[joaopgrassi]

It's probably too soon, but I was thinking if the registry would also benefit to follow the same directory structure as we have now in docs. Not blocking, and we can also adapt later.

[AlexanderWert]

It's probably too soon, but I was thinking if the registry would also benefit to follow the same directory structure as we have now in docs. Not blocking, and we can also adapt later.

I think we have different concerns with the semantic conventions structure and the registry structure. In the semantic conventions we group / structure the content by the logical domain (and that often covers attributes from different namespaces). With the registry we provide an overview of all defined attributes. So the attributes should be easy to find by their name. That's why I think a namespace-based structuring is more beneficial for the registry.

[AlexanderWert]

@open-telemetry/specs-semconv-maintainers anything blocking this?

I'd really like to get this in and then move fast with the refactoring (similar to what we did with the markdown files back then).
My hope is that this will accelerate some contributions (i.e. adding new attributes without directly tying them to semantic conventions).

[AlexanderWert]

Conflict resolution depends on open-telemetry/build-tools#206

[lmolkova]

LGTM!