rename some code attributes

[SylvainJuge]

Relates to #1377

In #1599 PR discussion, it was suggested we should probably rename a few code.* attributes before attempting to make them stable (which is the goal of #1599).

• mark code.* attributes as release candidate #1599 (comment)
• mark code.* attributes as release candidate #1599 (comment)

Changes

• rename code.function to code.function.name: it allows to add in the future other function related attributes later like code.function.visibility or code.function.signature.
• rename code.lineno to code.line.number this follows the general recommendation to avoid abbreviations while the lineno term is common, avoiding ambiguity is probably better here, also the code.line might be ambiguous as it could be interpreted as "the line of code".
• rename code.column to code.column.number for consistency/symmetry with code.line.number.
• EDIT: rename code.filepath to code.file.path for consistency with file.path (comment)

Existing usages of those attributes would be impacted (from a GH search, which means some might have been missed due to indirections from the respective generated semconv files):

• opentelemetry-php

  • code.lineno search
  • code.function search

• opentelemetry-rust

  • code.lineno search

• opentelemetry-java-instrumentation

  • code.lineno search
  • code.function search

• opentelemetry-js-contrib

  • code.lineno search
  • code.function search

• opentelemetry-python

  • code.lineno search
  • code.function search

• opentelemetry-cpp-contrib

  • code.function search
  • code.lineno search

• opentelemetry-php-contrib

  • code.lineno search
  • code.function search

I haven't found any usage of code.column which means renaming here should not have any expected impact.

EDIT Renaming code.filepath to code.file.path has been added later in the discussion and potential impacts haven't been evaluated.

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.

[SylvainJuge]

One problem is that renaming with a prefix is not allowed by policy, as a result I get the following error when trying to validate policy:

Violation: Attribute 'code.column' name is used as a namespace in the following attributes '["code.column.number"]'.
  - Category         : naming_collision
  - Type             : semconv_attribute
  - SemConv group    :
  - SemConv attribute: code.column
  - Provenance: /home/weaver/source

Violation: Attribute 'code.function' name is used as a namespace in the following attributes '["code.function.name"]'.
  - Category         : naming_collision
  - Type             : semconv_attribute
  - SemConv group    :
  - SemConv attribute: code.function
  - Provenance: /home/weaver/source

I don't know where does this restriction comes from, is it related to the generated per-language bindings ? From what I've seen so far they are mostly used as strings, so the limitations would be more on the processing/storage side.

[SylvainJuge]

After digging a bit further this kind of limitation comes from the generated code par, where in some cases it could create conflicts, for example foo.bar and foo_bar both being represented with FOO_BAR in some languages.

It seems that #1462 could provide a solution by allowing to provide an explicit code friendly name (which we can ensure does not conflicts), but I definitely lack expertise to know if it would help solve this current issue. @lmolkova do you think this would be covered by the current proposal ?

[jsuereth]

One problem is that renaming with a prefix is not allowed by policy, as a result I get the following error when trying to validate policy:

Violation: Attribute 'code.column' name is used as a namespace in the following attributes '["code.column.number"]'.
  - Category         : naming_collision
  - Type             : semconv_attribute
  - SemConv group    :
  - SemConv attribute: code.column
  - Provenance: /home/weaver/source

Violation: Attribute 'code.function' name is used as a namespace in the following attributes '["code.function.name"]'.
  - Category         : naming_collision
  - Type             : semconv_attribute
  - SemConv group    :
  - SemConv attribute: code.function
  - Provenance: /home/weaver/source

I don't know where does this restriction comes from, is it related to the generated per-language bindings ? From what I've seen so far they are mostly used as strings, so the limitations would be more on the processing/storage side.

We can add exceptions here: https://github.com/open-telemetry/semantic-conventions/blob/main/policies/attribute_name_collisions.rego#L83

This rule is in place to avoid conflicts if we ever "un-flatten" attributes. E.g. if an attribute of x can have an "AnyValue" with field y and this means the same as x.y.

We should ensure we never send the attribute as a namespace and the new attribute in the same signal.

@lmolkova will update policy to avoid this warning if the namespace attribute becomes deprecated.

[SylvainJuge]

Thanks to #1642 this is now unblocked and all the checks are now passing, it should now be ready for review.

[pellared]

Today, I encountered a potential unclarity related to code.function.name and code.namepsace. How anonymous functions (lambdas) should be handled?

For instance, in Go we can have an anonymous function in go.opentelemetry.io/contrib/bridges/otelslog.TestSLogHandler function. The Go runtime will report its name e.g. as go.opentelemetry.io/contrib/bridges/otelslog.TestSLogHandler.func7. I decided to go with code.function.name=func7 and code.namespace=go.opentelemetry.io/contrib/bridges/otelslog.TestSLogHandler given the definition of code.function.name:

usually rightmost part of the code unit's name

I started to have doubts whether the split code.function.name and code.namepsace isn't making more problems than benefits. Maybe we should just have a single attribute denoting the fully qualified name.

[SylvainJuge]

Probably we should also rename code.filepath to code.file.path, for the reasons above and also to match file.path

Done in 9303339, I have also updated this PR description.

[SylvainJuge]

As a reminder, the current state of this PR renames the following fields, there has been some approvals before the code.filepath was also renamed, so it's probably safer to be explicit here:

• code.function renamed to code.function.name
• code.lineno renamed to code.line.number
• code.column renamed to code.column.number
• code.filepath renamed to code.file.path

There is only one unresolved conversation: #1624 (comment), which is mostly about introducing a breaking change, @trask @lmolkova what do you think are the best next steps ? Do you think it's worth doing a proper migration plan ?

[lmolkova]

@SylvainJuge let's follow @trask's proposal in #1624 (comment) to add a warning - this would reduce any additional churn (if any).

Instrumentations that emit existing code attributes may still provide migration plan if necessary, without us requiring everyone to do it.

[SylvainJuge]

@SylvainJuge let's follow @trask's proposal in #1624 (comment) to add a warning - this would reduce any additional churn (if any).

I've added a warning (and a dedicated README.md) in c108ab2, let me know if that's enough for now.