Should there be any attributes marked as stable inside of experimental conventions?

[trask]

E.g. it seems confusing that some attributes are marked as stable in database-spans.md:

[pyohannes]

Good point, I'd conclude that the semantics of the attribute are stable, however, the attribute set is not (thus the attribute could be removed).

It makes me wonder whether stability markers on attributes make sense in experimental conventions at all.

[trask]

I'd conclude that the semantics of the attribute are stable, however, the attribute set is not (thus the attribute could be removed).

The attribute definition could also be further refined (overriding the brief or notes) within the convention.

[lmolkova]

Should we have an experimental badge on the semconv/table then? Instead of individual attributes in the table?

One future case (we don't have yet) is the opposite: stable semconv with experimental attributes (e.g. http is stable, but you can opt-in into url.template which is experimental) - what would that mean?

[lmolkova]

E.g. like this:

DB Client Spans (option 1)

Name	Kind	Stability
{db.operation.name} {db.collection.name} see Span Name for the details	CLIENT

Attributes

Attribute	Type	Description	Examples	Requirement Level
network.peer.address	string	Peer address of the database node where the operation was performed. [8]	10.1.2.80; /tmp/my.sock	Recommended If applicable for this database system.

[lmolkova]

DB Client Spans (option 2)

Name	Kind	Stability
{db.operation.name} {db.collection.name} see Span Name for the details	CLIENT

Attributes

Attribute	Type	Description	Examples	Requirement Level	Stability
network.peer.address	string	Peer address of the database node where the operation was performed. [8]	10.1.2.80; /tmp/my.sock	Recommended If applicable for this database system.

[pyohannes]

One future case (we don't have yet) is the opposite: stable semconv with experimental attributes (e.g. http is stable, but you can opt-in into url.template which is experimental) - what would that mean?

There are two stability markers interacting: the document stability, and the attribute stability marker.

Document	Attribute
		The attribute can be removed from the document, the attribute characteristics (name, type, values) can change.
		The attribute cannot be removed from the document and attribute characteristics cannot change.
		The attribute can be removed from the document, attribute characteristics cannot change.
		This seems to create a conflict for instrumentation authors, and I think it should be avoided.

All combinations except the last are viable. I think having stable attributes in experimental semantic conventions make sense: although it might be a bit confusing for instrumentation authors, it's a helpful hint for semantic conventions authors as it shows that attribute characteristics cannot change.

[lmolkova]

nit: spans have stability markers on its own, so instead of document status, we can use span markers (like http client)

All combinations except the last are viable.

What if we want to add url.template or http.operation.name to http span? There is nothing wrong with adding any attributes to a stable spans.
It could mean that stable artifacts can't add it, experimental can. If my instr library (like Java ones) allows users to enable experimental features, users may opt into the experimental version of semconv.

I.e. this attribute is opt-in until it reaches stability and then its level can change.

[trask]

maybe the yaml should require that all "refs" include explicit stability? and use that on the row instead of the attribute's stability from the global registry?

[lmolkova]

I think we need to define if overriding stability is allowed and what it means. I don't understand how we can redefine attribute stability:

Registry attribute stability (id)	Semconv attribute stability (ref)	Is allowed
stable	experimental	No. Only if we're going to introduce breaking changes to the base registry attribute
experimental	stable	No. Base definition of the attribute can change and it can be deprecated, there is nothing we guarantee about this attribute

Attribute values stability is not guaranteed therefore note and brief can change in reasonable way.

[trask]

Registry attribute stability (id)	Semconv attribute stability (ref)	Is allowed
stable	experimental	No. Only if we're going to introduce breaking changes to the base registry attribute

this one sort of seems ok to me if we read it as "experimental within the given semantic convention" (e.g. it may still be removed from the semantic convention)

the alternative (having a row displayed as stable within an experimental semconv table) feels confusing to me

[lmolkova]

I agree, I mean that not having stability on individual attributes under experimental conventions would convey the same information - everything here is experimental, can be added/removed/replaced:

Name	Kind	Stability
{db.operation.name} {db.collection.name} see Span Name for the details	CLIENT

Attributes

Attribute	Type	Description	Examples	Requirement Level
network.peer.address	string	Peer address of the database node where the operation was performed. [8]	10.1.2.80; /tmp/my.sock	Recommended If applicable for this database system.

While marking stable (in the registry) attribute as experimental (within semconv scope, especially in yaml) seems confusing (to me)

[trask]

makes sense, as long as it doesn't say "stable" in the markdown table, I'm 👍

[pyohannes]

I agree, I mean that not having stability on individual attributes under experimental conventions would convey the same information

That also makes sense to me.