Stop using prefix to define attributes

open-telemetry / semantic-conventions

Defines standards for generating consistent, accessible telemetry across a variety of domains

Apache License 2.0

261 stars 167 forks source link

Stop using prefix to define attributes #1292

Closed lmolkova closed 2 months ago

lmolkova commented 2 months ago

Attributes can be defined in two equivalent ways.

E.g. foo.bar can be defined with prefix foo and id bar

group:
- id: foo
  prefix: foo
  attributes: 
  - id: bar

without prefix and id foo.bar

group:
- id: foo
  attributes: 
  - id: foo.bar

Using prefix is inconvenient:

when searching for attribute definition in yaml files
when reading yaml definitons, it's not obvious what the full attribute name would be generated
tooling needs to resolve full attribute name and we need to be aware of it in some cases when writing policy checks, writing jq filters, generating code

Removing prefix would keep all MD files intact, but would resolve these inconveniences without any obvious downsides.

lmolkova commented 2 months ago

Another option: prefix is only used to validate that attributes start with it

group:
- id: foo
  prefix: foo
  attributes: 
  - id: foo.bar

This allows to embedding #1264 to work and keeps attributes in the same group consistent, but also solves all the problems with partial name in the id.

MadVikingGod commented 2 months ago

I have thought a bit about this problem and want to get a few concepts down, and propose an alternative solution.

First is that Prefix can not be just replaced with the group id, this wasn't suggested but I want to make sure it's clear. Prefix is just a useful tool to reduce repetition in the yaml.

There is a canonical name, made from the <group prefix>.<attribute id>, and right now this has to be globally unique. This is a problem, that we should test for, because neither prefixes nor attribute ids are globally unique so it's possible to create a duplicate attribute. Note we should still test for this if we take the current suggested approach to prevent any duplicate attributes.

What can be done instead of stopping the use of prefix is to make all references globally unique, and my suggestion is to change ref to be a group id and attribute id. While this would still not prevent the introduction of duplicate canonical attributes, we would always be able to refer to the particular attribute we want regardless of the addition of new attributes.

lmolkova commented 2 months ago

The canonical name is globally unique today (within otel semconv) and our tooling tests for it. Do I miss something?

lmolkova commented 2 months ago

I believe it's fixed with #1293.

https://github.com/open-telemetry/weaver/issues/263 stays open to track schema changes