Demo - remove root namespace from system-specific attributes and metrics

[lmolkova]

Demonstrates #1708 (comment) and #1618 (comment)

• we're inconsistent when naming system-specific attributes and metrics. E.g. we have
  • jvm.* and not runtime.jvm.*
  • db.cosmosdb and not cosmosdb
  • messaging.kafka and not kafka
  • gcp and not cloud.gcp
  • ...
• Any system, even if designed for a specific domain, is wider that this domain. E.g.
  • redis is mostly used as a cache, we call it a database, but it's also a messaging system - would we provide cache.redis, db.redis and messaging.redis?
  • Azure EventHubs is a messaging system, but we need metrics for connection management, load balancing, etc - having everything in eventhubs (or az.eventhubs) makes more sense.

This PR shows how the world would look like if we (in general) removed domain prefix from all system-specific things.

The naming guidance would be:

• if metric/event/attribute describes a general concept applicable to multiple system within this domain, it should start with this domain (e.g. db.namespace or db.client.operation.duration)
• if metrics/event/attribute is specific to a certain system, it should start with this system name (e.g. jvm.cpu.time, cosmosdb.client.request_charge)

[lmolkova]

curious what Elastic folks think

@AlexanderWert @gregkalapos

[gregkalapos]

elasticsearch.node.name seems ok to me. I think for Elasticsearch the proposed change would not make a significant difference, because it naturally falls under the db domain - so there was no discrepancy there anyways. E.g. the redis example in the PR description shows the problem very well - I'd say we haven't had this issue with Elasticsearch - definitely not to that extent.

So, having said that, I'd say, for consistency (if we go with this proposal and drop it due to other use-cases, e.g. redis), it'd be ok to drop db. for the Elasticsearch specific attributes.

[lmolkova]

curious what CosmosDB folks would think about this (removing db in front of cosmosdb everywhere)

@jcocchi @sourabh1007

[lmolkova]

curious what messaging folks think (about removing messaging prefix from system-specific attributes and metrics)

@joaopgrassi @pyohannes @carlosalberto @trask

[lmolkova]

as the owner of the corresponding instrumentations, I'd be really excited about this change - I struggle with trying to fit everything about specific messaging lib/system into messaging namespace.

[lmolkova]

curious what gen_ai folks think about removing gen_ai prefix from system-specific conventions like openai.

E.g. what good does gen_ai prefix does for something like file upload - would we want to report gen_ai.client.openai.uploaded_files vs openai.client.uploaded_files metric?

@open-telemetry/semconv-genai-approvers @xrmx @aabmass @codefromthecrypt @trentm @lzchen

[codefromthecrypt]

hmm gut feel is that we want the dimension/correlation of the source type vs embed it inside a naming convention, right?

[codefromthecrypt]

above comment was about the attribute in general, but now noticing your question was limited to if it should be prefixed or not (nothing else changes except the prefixing).

Answer is similar, I think the attribute name should be owned by the blob upload component, not gen_ai. However, if this is about bascially all openai related properties becoming top-level and not being under gen_ai, main concern is it crowds the top-level namespace.

• This puts a lot more pressure to pick names top-level names that are not ambiguous across domains. This might work for trademarked names better than non-trademarked ones.
• This can help when other types of attributes are considered, like do we feel like saying GENAI_OPENAI_API_VERSION vs OPENAI_API_VERSION
• semconv ownership is easier to figure out when it is prefixed, e.g. this team owns openai attributes, however, this is maybe not very useful to end users vs us

Gut feel is that removing the top-level namespaces for trademarked names, ones that don't have registry clash risk, sounds like it helps more than hurts.

I know it is a different issue, but in any text, most of these attributes are about the api or library in use, not necessarily the LLM provider (e.g xAI provider has openai compat support and would use these attributes for those traffic). We would need to keep that in mind when attributing to what's currently called "system". This clarification may not end up in this PR

[lmolkova]

this is a question whether gen_ai prefix add any value for any attribute that describes something specific to a certain library/system/api/provider/whatever. If something is specific to openai API, we'd still use openai somewhere in the name.

[michaelsafyan]

It does add some value in hinting that the span or event contains information pertinent to the topic of generative AI. Without the category prefix, it is harder to do things like "Show users all spans that involved the use of GenAI".

[lmolkova]

@jsuereth what would be your thoughts on getting rid of rpc. prefix from rpc.grpc? (and other similar changes in PR)

[trask]

Any system, even if designed for a specific domain, is wider that this domain.

how big of a problem do we think this is, and are there other mitigations we could consider?

as we are looking at tradeoffs, it feels like there's some tradeoff to promoting all of these (many) database systems to top-level namespaces, over keeping them scoped under db.*

[lmolkova]

as we are looking at tradeoffs, it feels like there's some tradeoff to promoting all of these (many) database systems to top-level namespaces, over keeping them scoped under db.*

I think consistent naming is a problem regardless of the top-level namespace. We need to make a choice between db.ibm.db2.* and db.db2.* anyway (and I'd prefer db2).

[michaelsafyan]

A potential concern with moving specific systems attributes outside the prefix of the general category to which they belong: it makes it difficult to know which attributes are topically relevant.

For example, let's suppose that you are implementing the display of telemetry collection data and you want to give users the ability to filter down to information that is focused on "Databases" or "GenAI" or etc.

Being able to map that to a prefix filter on "db." or a prefix filter on "gen_ai." makes it possible to provide such a topic-focused experience. If specific vendor implementation of a general concept are hoisted up a level where they are no longer prefixed with the category, then it makes it harder to match attributes related to the topic.

A potential way to address this concern might be to record in the OTel SemConv metadata information about the attributes that can connect them to the topics that they are about. For example:

 - key: `myvendorspecificdb.foo`
   categories:
    - databases

That would (albeit with significantly more effort) at least make it technically achievable to provide this kind of topical filtering. But it would still involve much more effort than having the category be a consistent prefix.

[lmolkova]

@michaelsafyan

The filtering can also be applied in the following way:

• look at gen_ai.system.name let's say it's foo.bar
• if you care deeply about gen_ai, you can also show all attributes starting with foo.bar
• you can also decide if there are some systems you care more about and show them in a certain way.

Qualifying an attribute as relevant to a domain is not trivial (and which domains):

1. when you upload a file to VertexAI, would you call it gen_ai, db or maybe rag?
2. when you do function call to search for embedding in a database - how would you classify those?

The fact that attribute name starts with gen_ai does not mean it's important (it can still describe some nitty-gritty detail about specific system) and the opposite is also not true. E.g. presence of error.type on gen_ai telemetry item is very important.

---

To summarize pros and cons:

Having the {domain} prefix has the following cons:

• things that don't clearly fit into one domain, would be artificial. Would we use db.redis when talking to DB, cache.redis when talking to cache and messaging.redis when using redis as a messaging system and finally use redis when describing control-plane and cluster operations? Using just redis solves these problems
• once we can have decentralized semantic conventions, root namespace becomes a governance entity (Google should be able to manage everything in gcp namespace instead of gen_ai.gcp.vertex_ai, messaging.gcp.pubsub and open set of other namespaces)

I'd argue that those are more important than topical filtering.

Given that we still provide consistency for *.system.name = foo and foo.* system-specific attributes, topical filtering can still be done.

[michaelsafyan]

@lmolkova is it guaranteed that the value in gen_ai.system.name will always match the prefix of the vendor-specific attributes? And is it guaranteed that the vendor-specific attributes will always be accompanied by one of the more general category-specific attributes? [Is this stated anywhere explicitly in the spec?]

My concern is mainly having to keep abreast of all possible vendor-specific systems that belong to some domain. I agree that categorization is hard, but it would be more scalable if contributors to the conventions self-categorize.

If there were metadata about each attribute specifying relevant categories, it may be possible to specify more than one category, which would eliminate the concerns about having to choose the ideal category.

I don't think it is necessarily a blocker to the proposed renaming, but I did want to raise it to attention that the naming prefixes do provide a useful way of topical filtering that is a tradeoff/loss as a result of this transformation (and that, out of band of this change, it may be worth thinking about how topical filtering might be enabled scalably).