Implement code-generation hints to drop/rename attributes in case of a collision

[lmolkova]

This is a tracking issue for #1118 (comment) Phase 2

Currently we don't allow collisions between attribute/event/etc names in the code-friendly representation of them (. replaced with _).

But we have some attributes that would benefit from renaming (e.g. db.cosmosdb.client_id should stay consistent with messaging.client.id).

We can resolve it by providing code-generation hints in the yaml that would help code-generator to resolve collisions.

[lmolkova]

Scenarios to consider

1. attribute is deprecated, the replacement has the same constant name (messaging.client_id -> messaging.client.id):
   • code-generator hint could tell to drop it (the decision we made in messaging.client_id -> messaging.client.id rename causes issues with code generation #1031)
2. attribute is deprecated, the replacement has the same constant name, but different type
   1. code generator hint could tell to drop it (same as scenario 1)
   2. OR code-generator may need to generate both attributes, so needs a hint to use a different name for the replacement attribute
3. Attribute name contains non-ASCII characters and needs a code-generator-friendly name
   ...

Proposal

Combining with #1419 to keep it consistent with deprecation if possible.

Scenarios 1 & 2i

- id: registry.foo
  ...
  attributes:
    - id: foo.bar_id
      deprecated:            # not in the scope of this item
        action: rename
        renamed_to: foo.bar.id
      code_generation_hint:  # <-- this is the proposal for scenarios 1 and 2i above
        action: exclude      # <-- this is the proposal for scenarios 1 and 2i above

Scenarios 2ii & 3

- id: registry.foo
  ...
  attributes:
    - id: foo.bar_code
      type: int
      deprecated:
        action: remove
      note: Renamed to `foo.bar.code` and type changed to string
    - id: foo.bar.code
      type: string
      code_generation_hint:                # <-- this is the proposal for scenario 2ii
        code_friendly_name: foo_bar_code2  # <-- this is the proposal for scenario 2ii
    - id: pprof::foo.bar
      code_generation_hint:                # <-- this is the proposal for scenario 3 
        code_friendly_name: pprof_foo_bar  # <-- this is the proposal for scenario 3 

---

Alternative proposal

- id: registry.foo
  ...
  attributes:
    - id: foo.bar_id
      deprecated:                         # not in the scope of this item
        action: rename
        renamed_to: foo.bar.id
      code_generation_hint: exclude       # <-- this is the proposal for scenarios 1 and 2i above
    - id: pprof::foo.bar
      code_friendly_name:  pprof_foo_bar  # <-- this is the proposal for scenario 2ii & 3 

[lmolkova]

The following policies will be necessary:

• code_generator: action: remove or alternatives MUST NOT appear on stable things.
• if code_friendly_name is not set, it's considered to be {id}.replace('.', '_') and MUST NOT change for experimental or stable things in the future version (i.e. code_friendly_name can be specified once at the attribute creation time (or within the same version attribute was defined)
• Same with code_generation_hint: action: exclude or alternatives - it SHOULD NOT be changed for existing attributes. Except current exceptions -

  semantic-conventions/policies/attribute_name_collisions.rego

  Line 82 in 6c1c976

  excluded_const_collisions := {"messaging.client_id"}

[lmolkova]

Based on the discussions on slack there is a preference for option 1:

      code_generation_hint: 
        action: exclude
        code_friendly_name: <>

[SylvainJuge]

#1624 is currently blocked because we are trying to rename code.function to code.function.name and code.column to code.column.number.

I understand from the description of #1614 PR that this PR could provide a solution to this, but it's more about "conflicts with dots to underscores" rather than "adding suffix to an already existing semconv attribute".

For #1613 the rename of db.system.* to db.system.name suggested in #1581 was avoided by using a different attribute prefix: db.provider.name which does not conflict.
In the discussion of #1581 there is no mention adding a .name suffix could be something not allowed, so am I right to assume that this should be something we should be allowed to do ?

[SylvainJuge]

If this change can help with namespace suffix changes, then it could also probably help unblock #1638 where creating a new attribute that reuses the namespace of an existing attribute is not possible (geo.location).