[chore] System Semconv OS-exclusive instrumentation philosophy

[braydonk]

Changes

This PR updates our OS-exclusive instrumentation naming philosophy/policy to reflect the group's current standing. This ruling hasn't been fully applied across our instrumentation yet but we are working on it as part of initial stabilization efforts.

Merge requirement checklist

• CONTRIBUTING.md guidelines followed.
• [N/A] 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]
• [N/A] Links to the prototypes or existing instrumentations (when adding or changing conventions)

[thompson-tomo]

Suggested change

	### The OS name should be included in the metric in most cases
	The primary reason for this is for discoverability and disambiguation. Sometimes
	### When to include OS name
	The name of a platform specific metric should by default include the OS name,
	with the primary reason for this is to enable discoverability and disambiguation. Sometimes

[thompson-tomo]

Suggested change

	### The OS name should be after the area of concern
	Our expected usage pattern for these metrics is for a user to have some area of
	concern within their system that they are monitoring (processes, memory,
	filesystem, cpu, network, etc) and for a user with a specific concern to have a
	clear way to discover the instrumentation supporting their area of concern.
	Sometimes that area of concern is not just the absolute root of the namespace,
	but also a number of sub-components in the root. The `system` namespace in
	particular has many examples of this, `system.memory`, `system.network`, etc. If
	we named the instrumentation as `system.linux.memory`, then just as in the
	scenario above it becomes hard to discover all the available "system memory"
	metrics. As a result, the OS name goes after the area of concern, i.e.
	`system.memory.linux`.
	### Where to place OS name in metric name
	Our expectation is that the OS name to appear after the area of
	concern which is being monitored (processes, memory,
	filesystem, cpu, network, etc).
	This means that the OS name should never appear as the root namespace ie `linux.memory.*` and
	often the area of concern will not even be the root namespace,
	but rather a sub-namespace. The `system` root namespace in
	particular has many examples of this, `system.memory.*`, `system.network.*`, etc.
	As a result, the OS name goes after the area of concern, i.e.
	`system.memory.linux.*` with non platform specific metrics being `system.memory.*`.
	### Why we choose this
	To provide a user with a specific concern, a
	clear way to discover the instrumentation supporting their area of concern. If
	we had named the instrumentation as `system.linux.memory.*`, then a user would need to search for `linux.memory.*`,
	`windows.memory.*`, etc. This is bad partially because of complicating queries,
	but it would also require a user to go out of their way to gather all of the
	platforms they need to search for just to get the whole picture on their
	`system memory` metrics.

[thompson-tomo]

Suggested change

	### The OS name should not be the root namespace
	This is for the sake of hierarchical organization of names. We consider the root
	namespace of metrics to be crucial to the typical usage patterns we expect. A
	user who wants to discover all of their `memory` metrics should only need to
	search for `memory.*` to get all metrics related to `memory` in general. If the
	OS was the root namespace, they would need to search for `linux.memory.*`,
	`windows.memory.*`, etc. This is bad partially because of complicating queries,
	but it would also require a user to go out of their way to gather all of the
	platforms they need to search for just to get the whole picture on their
	`memory` metrics.

Has been consolidated into the below section.

[thompson-tomo]

Would be good to add details of what is an area of concern. For instance there is a discussion about memory pressure, in that case would the area of concern be memory or memory.pressure?

[rogercoll]

That's a great point. In this context, the 'area of concern' refers to the high-level resource or term shared across operating systems (like memory).

Since pressure (PSI) is a concept specific to Linux, we place the OS keyword after the shared resource to differentiate between common cross-platform metrics and OS-specific implementations. So, the hierarchy remains system.memory (shared) → linux (specific) → pressure (os unique metrics).

[thompson-tomo]

What happens when we consider that pressure applies to macos as well. Would the area of concern then be pressure?

[mx-psi]

I don't think we are going to be able to create a 'hard' rule for this when it comes to what is the area of concern, if anything we can clarify that the area of concern should be made clear on each semconv area

[thompson-tomo]

Based on #3068 it would be useful to have a section naming platform-exclusive attributes.

This section should cover when the attribute is added with the area ie system root namespace and when it is added with a root namespace = area of concern.

An example would be we currently have system.memory.state but also have cpu.mode both of which relate to area of concerns which applies to multiple to multiple areas.

My initial thought would belong to the area of concern unless they are describing the entity ie system, process producing the telemetry.

[mx-psi]

Suggested change

	### The OS name should be included in the metric in most cases
	### The OS name should be included in the metric name in most cases

We could even rephrase this as "Users should be able to tell if a metric is OS-specific based on the name", which I think is a fair summary of the text?

[mx-psi]

I don't think we are going to be able to create a 'hard' rule for this when it comes to what is the area of concern, if anything we can clarify that the area of concern should be made clear on each semconv area