Merge branch 'main' into migrating-to-stable-http-semconv

CHANGELOG.md

@@ -9,6 +9,9 @@ release.
 
 ### Breaking
 
+- Rename `system.processes.*` namespace to `system.process.*`
+  ([#484](https://github.com/open-telemetry/semantic-conventions/pull/484))
+
 ### Features
 
 ### Fixes

docs/attributes-registry/README.md

@@ -27,6 +27,7 @@ All registered attributes are listed by namespace in this registry.
 
 Currently, the following namespaces exist:
 
+* [Browser](browser.md)
 * [Client](client.md)
 * [Cloud](cloud.md)
 * [Code](code.md)

docs/attributes-registry/browser.md

@@ -0,0 +1,24 @@
+<!--- Hugo front matter used to generate the website version of this page:
+--->
+
+# Browser
+
+## Browser Attributes
+
+<!-- semconv registry.browser(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `browser.brands` | string[] | Array of brand name and version separated by a space [1] | `[ Not A;Brand 99, Chromium 99, Chrome 99]` |
+| `browser.language` | string | Preferred language of the user using the browser [2] | `en`; `en-US`; `fr`; `fr-FR` |
+| `browser.mobile` | boolean | A boolean that is true if the browser is running on a mobile device [3] |  |
+| `browser.platform` | string | The platform on which the browser is running [4] | `Windows`; `macOS`; `Android` |
+
+**[1]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.brands`).
+
+**[2]:** This value is intended to be taken from the Navigator API `navigator.language`.
+
+**[3]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.mobile`). If unavailable, this attribute SHOULD be left unset.
+
+**[4]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.platform`). If unavailable, the legacy `navigator.platform` API SHOULD NOT be used instead and this attribute SHOULD be left unset in order for the values to be consistent.
+The list of possible values is defined in the [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform). Note that some (but not all) of these values can overlap with values in the [`os.type` and `os.name` attributes](./os.md). However, for consistency, the values in the `browser.platform` attribute should capture the exact value that the user agent provides.
+<!-- endsemconv -->

docs/attributes-registry/exception.md

@@ -8,10 +8,10 @@
 <!-- semconv registry.exception(omit_requirement_level) -->
 | Attribute  | Type | Description  | Examples  |
 |---|---|---|---|
-| `exception.escaped` | boolean | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [1] |  |
-| `exception.message` | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` |
-| `exception.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` |
-| `exception.type` | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` |
+| `exception.escaped` | boolean | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [1] |  |
+| `exception.message` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` |
+| `exception.stacktrace` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` |
+| `exception.type` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` |
 
 **[1]:** An exception is considered to have escaped (or left) the scope of a span,
 if that span is ended while the exception is still logically "in flight".

docs/exceptions/exceptions-logs.md

@@ -4,7 +4,7 @@ linkTitle: Logs
 
 # Semantic Conventions for Exceptions in Logs
 
-**Status**: [Experimental][DocumentStatus]
+**Status**: [Stable][DocumentStatus]
 
 This document defines semantic conventions for recording exceptions on
 [logs](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/logs/bridge-api.md#emit-a-logrecord) and [events](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/logs/event-api.md#emit-event)

docs/exceptions/exceptions-spans.md

@@ -4,7 +4,7 @@ linkTitle: Spans
 
 # Semantic Conventions for Exceptions on Spans
 
-**Status**: [Experimental][DocumentStatus]
+**Status**: [Stable][DocumentStatus]
 
 This document defines semantic conventions for recording application
 exceptions associated with spans.

docs/resource/README.md

@@ -82,8 +82,8 @@ as specified in the [Resource SDK specification](https://github.com/open-telemet
 <!-- semconv service -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `service.name` | string | Logical name of the service. [1] | `shoppingcart` | Required |
-| `service.version` | string | The version string of the service API or implementation. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | Recommended |
+| `service.name` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Logical name of the service. [1] | `shoppingcart` | Required |
+| `service.version` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>The version string of the service API or implementation. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | Recommended |
 
 **[1]:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md#process), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`.
 <!-- endsemconv -->
@@ -132,9 +132,9 @@ service.name = Shop.shoppingcart
 <!-- semconv telemetry -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `telemetry.sdk.language` | string | The language of the telemetry SDK. | `cpp` | Required |
-| `telemetry.sdk.name` | string | The name of the telemetry SDK as defined above. [1] | `opentelemetry` | Required |
-| `telemetry.sdk.version` | string | The version string of the telemetry SDK. | `1.2.3` | Required |
+| `telemetry.sdk.language` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>The language of the telemetry SDK. | `cpp` | Required |
+| `telemetry.sdk.name` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>The name of the telemetry SDK as defined above. [1] | `opentelemetry` | Required |
+| `telemetry.sdk.version` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>The version string of the telemetry SDK. | `1.2.3` | Required |
 
 **[1]:** The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`.
 If another SDK, like a fork or a vendor-provided implementation, is used, this SDK MUST set the

docs/resource/browser.md

@@ -11,10 +11,10 @@ All of these attributes can be provided by the user agent itself in the form of
 <!-- semconv browser -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `browser.brands` | string[] | Array of brand name and version separated by a space [1] | `[ Not A;Brand 99, Chromium 99, Chrome 99]` | Recommended |
-| `browser.language` | string | Preferred language of the user using the browser [2] | `en`; `en-US`; `fr`; `fr-FR` | Recommended |
-| `browser.mobile` | boolean | A boolean that is true if the browser is running on a mobile device [3] |  | Recommended |
-| `browser.platform` | string | The platform on which the browser is running [4] | `Windows`; `macOS`; `Android` | Recommended |
+| [`browser.brands`](../attributes-registry/browser.md) | string[] | Array of brand name and version separated by a space [1] | `[ Not A;Brand 99, Chromium 99, Chrome 99]` | Recommended |
+| [`browser.language`](../attributes-registry/browser.md) | string | Preferred language of the user using the browser [2] | `en`; `en-US`; `fr`; `fr-FR` | Recommended |
+| [`browser.mobile`](../attributes-registry/browser.md) | boolean | A boolean that is true if the browser is running on a mobile device [3] |  | Recommended |
+| [`browser.platform`](../attributes-registry/browser.md) | string | The platform on which the browser is running [4] | `Windows`; `macOS`; `Android` | Recommended |
 | [`user_agent.original`](../attributes-registry/user-agent.md) | string | Full user-agent string provided by the browser [5] | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.54 Safari/537.36` | Recommended |
 
 **[1]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.brands`).

docs/runtime/jvm-metrics.md

@@ -283,7 +283,7 @@ This metric is obtained from [`ClassLoadingMXBean#getLoadedClassCount()`](https:
 This metric is [recommended][MetricRecommended].
 
 This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getProcessCpuTime()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuTime()) on HotSpot
-and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuTime()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html#getProcessCpuTime--) on J9.
+and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuTime()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html#getProcessCpuTime--) on OpenJ9.
 
 <!-- semconv metric.jvm.cpu.time(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
@@ -313,7 +313,7 @@ Note that this is always an integer value (i.e. fractional or millicores are not
 
 This metric is [recommended][MetricRecommended].
 This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getProcessCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuLoad()) on HotSpot
-and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html#getProcessCpuLoad--) on J9.
+and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html#getProcessCpuLoad--) on OpenJ9.
 Note that the JVM does not provide a definition of what "recent" means.
 
 <!-- semconv metric.jvm.cpu.recent_utilization(metric_table) -->
@@ -364,7 +364,7 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle
 
 This metric is [Opt-In][MetricOptIn].
 This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getSystemCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getSystemCpuLoad()) on Java version 8..13, [`com.sun.management.OperatingSystemMXBean#getCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getCpuLoad()) on Java version 14+,
-and [`com.ibm.lang.management.OperatingSystemMXBean#getSystemCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html) on J9.
+and [`com.ibm.lang.management.OperatingSystemMXBean#getSystemCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html) on OpenJ9.
 
 <!-- semconv metric.jvm.system.cpu.utilization(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |

docs/system/system-metrics.md

@@ -52,8 +52,8 @@ Resource attributes related to a host, SHOULD be reported under the `host.*` nam
   * [Metric: `system.network.io`](#metric-systemnetworkio)
   * [Metric: `system.network.connections`](#metric-systemnetworkconnections)
 - [Aggregate System Process Metrics](#aggregate-system-process-metrics)
-  * [Metric: `system.processes.count`](#metric-systemprocessescount)
-  * [Metric: `system.processes.created`](#metric-systemprocessescreated)
+  * [Metric: `system.process.count`](#metric-systemprocesscount)
+  * [Metric: `system.process.created`](#metric-systemprocesscreated)
 - [`system.{os}.` - OS Specific System Metrics](#systemos---os-specific-system-metrics)
   * [Metric: `system.linux.memory.available`](#metric-systemlinuxmemoryavailable)
 
@@ -718,22 +718,22 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
 **Description:** System level aggregate process metrics captured under the namespace `system.process`.
 For metrics at the individual process level, see [process metrics](process-metrics.md).
 
-### Metric: `system.processes.count`
+### Metric: `system.process.count`
 
 This metric is [recommended][MetricRecommended].
 
-<!-- semconv metric.system.processes.count(metric_table) -->
+<!-- semconv metric.system.process.count(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
 | -------- | --------------- | ----------- | -------------- |
-| `system.processes.count` | UpDownCounter | `{process}` | Total number of processes in each state |
+| `system.process.count` | UpDownCounter | `{process}` | Total number of processes in each state |
 <!-- endsemconv -->
 
-<!-- semconv metric.system.processes.count(full) -->
+<!-- semconv metric.system.process.count(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `system.processes.status` | string | The process state, e.g., [Linux Process State Codes](https://man7.org/linux/man-pages/man1/ps.1.html#PROCESS_STATE_CODES) | `running` | Recommended |
+| `system.process.status` | string | The process state, e.g., [Linux Process State Codes](https://man7.org/linux/man-pages/man1/ps.1.html#PROCESS_STATE_CODES) | `running` | Recommended |
 
-`system.processes.status` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
+`system.process.status` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
 
 | Value  | Description |
 |---|---|
@@ -743,17 +743,17 @@ This metric is [recommended][MetricRecommended].
 | `defunct` | defunct |
 <!-- endsemconv -->
 
-### Metric: `system.processes.created`
+### Metric: `system.process.created`
 
 This metric is [recommended][MetricRecommended].
 
-<!-- semconv metric.system.processes.created(metric_table) -->
+<!-- semconv metric.system.process.created(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
 | -------- | --------------- | ----------- | -------------- |
-| `system.processes.created` | Counter | `{process}` | Total number of processes created over uptime of the host |
+| `system.process.created` | Counter | `{process}` | Total number of processes created over uptime of the host |
 <!-- endsemconv -->
 
-<!-- semconv metric.system.processes.created(full) -->
+<!-- semconv metric.system.process.created(full) -->
 <!-- endsemconv -->
 
 ## `system.{os}.` - OS Specific System Metrics

model/metrics/system-metrics.yaml

@@ -447,9 +447,9 @@ groups:
       - ref: system.network.state
       - ref: network.transport
 
-  # system.processes.* metrics and attribute group
-  - id: attributes.system.processes
-    prefix: system.processes
+  # system.process.* metrics and attribute group
+  - id: attributes.system.process
+    prefix: system.process
     type: attribute_group
     brief: "Describes System Process metric attributes"
     attributes:
@@ -470,18 +470,18 @@ groups:
         examples: ["running"]
 
 
-  - id: metric.system.processes.count
+  - id: metric.system.process.count
     type: metric
-    metric_name: system.processes.count
+    metric_name: system.process.count
     brief: "Total number of processes in each state"
     instrument: updowncounter
     unit: "{process}"
     attributes:
-      - ref: system.processes.status
+      - ref: system.process.status
 
-  - id: metric.system.processes.created
+  - id: metric.system.process.created
     type: metric
-    metric_name: system.processes.created
+    metric_name: system.process.created
     brief: "Total number of processes created over uptime of the host"
     instrument: counter
     unit: "{process}"

model/registry/browser.yaml

@@ -0,0 +1,47 @@
+groups:
+  - id: registry.browser
+    prefix: browser
+    type: resource
+    brief: >
+      The web browser attributes
+    attributes:
+      - id: brands
+        type: string[]
+        brief: 'Array of brand name and version separated by a space'
+        note: >
+          This value is intended to be taken from the
+          [UA client hints API](https://wicg.github.io/ua-client-hints/#interface)
+          (`navigator.userAgentData.brands`).
+        examples: [ " Not A;Brand 99", "Chromium 99", "Chrome 99" ]
+      - id: platform
+        type: string
+        brief: 'The platform on which the browser is running'
+        note: >
+          This value is intended to be taken from the
+          [UA client hints API](https://wicg.github.io/ua-client-hints/#interface)
+          (`navigator.userAgentData.platform`). If unavailable, the legacy
+          `navigator.platform` API SHOULD NOT be used instead and this attribute
+          SHOULD be left unset in order for the values to be consistent.
+
+          The list of possible values is defined in the
+          [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform).
+          Note that some (but not all) of these values can overlap with values
+          in the [`os.type` and `os.name` attributes](./os.md).
+          However, for consistency, the values in the `browser.platform` attribute
+          should capture the exact value that the user agent provides.
+        examples: ['Windows', 'macOS', 'Android']
+      - id: mobile
+        type: boolean
+        brief: 'A boolean that is true if the browser is running on a mobile device'
+        note: >
+          This value is intended to be taken from the
+          [UA client hints API](https://wicg.github.io/ua-client-hints/#interface)
+          (`navigator.userAgentData.mobile`). If unavailable, this attribute
+          SHOULD be left unset.
+      - id: language
+        type: string
+        brief: 'Preferred language of the user using the browser'
+        note: >
+          This value is intended to be taken from the Navigator API
+          `navigator.language`.
+        examples: ["en", "en-US", "fr", "fr-FR"]