From 8d187b66dcef68106f77eb241a17e1e1d99b400a Mon Sep 17 00:00:00 2001 From: braydonk Date: Mon, 29 Sep 2025 18:47:46 +0000 Subject: [PATCH 1/2] [chore] System Semconv Description Guidance This PR explains how the `brief` and `note` fields will be used in the namespaces covered by the System Semantic Conventions group. The general concept is that we want to assume a baseline level of knowledge for readers of our conventions, as this frees us up to focus the descriptions of our instrumentation on instrumentation details rather than on explaining general concepts. --- .../groups/system/design-philosophy.md | 62 ++++++++++++++++--- 1 file changed, 53 insertions(+), 9 deletions(-) diff --git a/docs/non-normative/groups/system/design-philosophy.md b/docs/non-normative/groups/system/design-philosophy.md index dd408b4f53..98977d550d 100644 --- a/docs/non-normative/groups/system/design-philosophy.md +++ b/docs/non-normative/groups/system/design-philosophy.md @@ -168,15 +168,15 @@ applied in a cross-platform manner. See ### Value -For General Class, the value we can be prescriptive with the value of the -instrumentation. We want to ensure General Class instrumentation most closely -matches our vision for our general use cases, and we want to ensure that users -who are not specialists and just want the most important basic information can -acquire it as easily as possible using out-of-the-box semconv instrumentation. -This means we are more likely within General Class instrumentation to make -judgements about exactly what the value should be, and whether the value should -be reshaped by instrumentation in any case when pulling the values from sources -if it serves general purpose use cases. +For General Class, we can be prescriptive with what the value of the +instrumentation should be. We want to ensure General Class instrumentation most +closely matches our vision for our general use cases, and we want to ensure that +users who are not specialists and just want the most important basic information +can acquire it as easily as possible using out-of-the-box semconv +instrumentation. This means we are more likely within General Class +instrumentation to make judgements about exactly what the value should be, and +whether the value should be reshaped by instrumentation in any case when pulling +the values from sources if it serves general purpose use cases. For Specialist Class, we should strive not to be prescriptive and instead match the concept being modeled as closely as possible. We expect specialist class @@ -184,6 +184,50 @@ instrumentation to be enabled by the people who already understand it. In a System Semconv context, these may be things a user previously gathered manually or through existing OS tools that they want to model as OTLP. +### Descriptions + +The concepts being modeled by System Semantic Conventions can be very complex, +sometimes requiring deeper knowledge of operating system and computing concepts +than most general practitioners would need. As a result, it is tempting to +provide detailed explanations of the concepts we are modelling. However, we feel +that the amount of explanation that would be required to teach these concepts +to a reader with no knowledge would require so much context and nuance that it +would clutter the resulting documentation and obscure the information we really +need to convey, which is not just what the instrumentation is but details about +how and why to instrument it certain ways. + +This means that for System Semantic Conventions documentation, +**we assume a baseline level of knowledge of the concepts being instrumented**. +The `brief` and `note` fields of metrics and attributes should be used to convey +information that is crucial to understanding the instrumentation intention, +i.e.: + +* Differences in the same piece of data when it is instrumented on different + platforms +* When we recommend calculations be done on particular data rather than + surfacing direct values from existing tools +* When particular names or enum values were chosen when there are common + alternate terms for the same concept + +For root metrics and attributes, we will strive to always have a `brief` field. +The `brief` field should explain what the metric/attribute is, and if the +explanation of a value is simple (i.e. simply surfacing a value from a common +source like `procfs`) then the explanation of what the value should be can go +in the brief. If the value needs some calculation explanation and justification, +the information should be moved to the `note` field. +For enum values, it is often the case that the intention of these values is +obvious given whatever `brief` was provided for the attribute as a whole. A +brief can be included in a scenario where we have had to make some choice on the +value that isn't immediately obvious; the most common scenario is when some +terminology differs across platforms and we had to choose one term to represent +all scenarios. In this case, the `brief` can be used to clarify our intention. + +In cases where information about a concept is required to describe our intention +for instrumentation, all information must come with citations to authoritative +documentation (i.e. Linux `man` pages, Win32 API docs, etc). We do not want to +invent any new explanations about existing concepts in our own words within our +convention documentation. + ### Case study: `process.cgroup` Relevant discussions: From 5807ca11c73bd53c3ce409428963f95f42e1e980 Mon Sep 17 00:00:00 2001 From: braydonk Date: Tue, 30 Sep 2025 12:42:28 +0000 Subject: [PATCH 2/2] fix markdownlint --- docs/non-normative/groups/system/design-philosophy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/non-normative/groups/system/design-philosophy.md b/docs/non-normative/groups/system/design-philosophy.md index 98977d550d..110a1a3756 100644 --- a/docs/non-normative/groups/system/design-philosophy.md +++ b/docs/non-normative/groups/system/design-philosophy.md @@ -205,7 +205,7 @@ i.e.: * Differences in the same piece of data when it is instrumented on different platforms * When we recommend calculations be done on particular data rather than - surfacing direct values from existing tools + surfacing direct values from existing tools * When particular names or enum values were chosen when there are common alternate terms for the same concept