Database and messaging: system-specific extensions should list all attributes they use

[lmolkova]

Area(s)

area:db, area:messaging

Is your change request related to a problem? Please describe.

System-specific extensions document their own attributes (or attributes they redefine). E.g. mssql lists just two attributes

semantic-conventions/docs/database/mssql.md

Lines 17 to 22 in d8b6c93

	<!-- semconv db.mssql(full,tag=tech-specific) -->
	| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
	|---|---|---|---|---|---|
	| [`db.mssql.instance_name`](../attributes-registry/db.md) | string | The Microsoft SQL Server [instance name](https://docs.microsoft.com/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) connecting to. This name is used to determine the port of a named instance. [1] | `MSSQLSERVER` | `Recommended` |  |
	| [`db.sql.table`](../attributes-registry/db.md) | string | The name of the primary table that the operation is acting upon, including the database name (if applicable). [2] | `public.users`; `customers` | `Recommended` |  |

This creates confusion:

• not all systems populate db.statement or other attributes, so which do?
• what's a complete set of attributes instrumentation authors should record in each language?

Describe the solution you'd like

Markdown tables for specific extensions should list all attributes we expect specific system to populate.

Describe alternatives you've considered

No response

Additional context

No response

[pyohannes]

not all systems populate db.statement or other attributes, so which do?

I wonder how the proposed solution solves that confusion.

If for example db.statement is added to the table with the same requirement level as in the generic conventions ("recommended"), then I think this doesn't really change anything, I still can't rely on the presence of something that's recommended.

Or should it be added with a different requirement level, like "required"?

[lmolkova]

Let's say SQL semconv are fine with db.statement as recommended - they just reference it and recommended appears in markdown. Everyone's happy.

If SQL semconv want a different level, they'd reference statement and override it.

But in both cases, it'd be clear that SQL semconv do use db.statement (and don't use some other attributes like db.instance.id).

[pyohannes]

If SQL semconv want a different level, they'd reference statement and override it.

Do you think we'd need to define which level changes are allowed here? For example:

• I guess if generic conventions define something as "Required", system-specific conventions shouldn't be allowed to change that.
• Changing an attribute from "Recommended" to "Required" should be fine.
• Could an attribute be changed from "Opt-In" to "Required", or "Recommended"?

[lmolkova]

build-tools have a list of things that can't be redefined (name, type, stability) and a list of things that can be rewritten fully (brief, note, req level, examples).

I'd say that we can catch issues during code reviews, but the only problematic change for req level is when base attribute is required - if some system can't populate it, it probably has to add a dummy value like _OTHER (or change the base one if it's not stable yet).

It's a big open question what can be redefined for the scope of semconv, but I feel it's a separate issue. Existing tooling already allows us to do certain things.

[lmolkova]

Fixed in #1018 and #973