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.

[trask]

I'd recommend leaving this PR open until December 12 11 (to give us time to raise in the meetings below)

I'd like to give enough community notice, especially since we aren't planning to provide any migration plan

I will post today in #otel-semantic-conventions, #otel-specification, and #otel-maintainers slack channels

and I'll add it to next week's meeting agendas for those SIGs to make sure everyone has a chance to voice any concerns before we merge it

[SylvainJuge]

Is there a general strategy to provide a migration plan when renaming attributes beyond communication ?

Once this is merged and we know it will be included in the next semconv release, I think that I can open issues in the known impacted repositories that have been listed in the description. Please 👍 or reply to this comment if you think it's the right approach and I'll create issues.

Here we deprecate existing attributes, so I think that only the repositories where deprecation warnings are not permitted opentelemetry-java-instrumentation would require to deal with that in the semconv update PR.

[SylvainJuge]

From the related announcement on slack I got what "migration plan" here means: using OTEL_SEMCONV_STABILITY_OPT_IN configuration and keeping it compatible for a while, likely waiting for the next major release of each component before finally doing the change.

[lmolkova]

I believe the consensus is that code namespace is not used wide enough to justify the migration plan (see notes https://docs.google.com/document/d/1pdvPeKjA8v8w_fGKAN68JjWBmVJtPCpqdi9IZrd6eEo/edit?tab=t.0), so we should be good to go.

[brunobat]

It is being used.
If people have to start properly migrating these breaking changes maybe they will be less trigger happy in creating them.

[trask]

@brunobat are you asking to include code attribute breaking changes under a OTEL_SEMCONV_STABILITY_OPT_IN plan similar to http attribute breaking changes? thanks

[trask]

@SylvainJuge probably we should (at least) include language:

Warning Existing instrumentations that are using v1.29.0 of this document (or prior)
SHOULD NOT change the version of the code attribute conventions that they emit by default until the code attribute semantic conventions are marked stable.

to ensure that people only have to deal with a single breaking change from now until stabilization is complete

[SylvainJuge]

@brunobat do you have particular examples that would be problematic here ? Most usages I've found were in producing telemetry, not on the consumption side.

[brunobat]

@trask, I'm ok with your suggestion.

@SylvainJuge, I've only used those properties in PoCs, it's not critical if they change.
This is a matter of principle.
In a public project like this, people shouldn't assume it's not used just because it doesn't show up in a search.
Many projects and libraries outside the OpenTelemetry repository are starting to rely on semantic conventions. Breaking them frequently will put a break on adoption.

[trask]

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

[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.