Merge branch 'main' into attribute-templates

CHANGELOG.md

@@ -105,9 +105,15 @@ release.
 - BREAKING: Rename `messaging.message.payload_size_bytes` to `messaging.message.body.size`,
   remove `messaging.message.payload_compressed_size_bytes`.
   ([#229](https://github.com/open-telemetry/semantic-conventions/pull/229))
+- Add `system.linux.memory.available` metric.
+  ([#323](https://github.com/open-telemetry/semantic-conventions/pull/323))
 - BREAKING: Rename `http.server.request.size` metric to `http.server.request.body.size`
   and `http.server.response.size` metric to `http.server.response.body.size`
   ([#247](https://github.com/open-telemetry/semantic-conventions/pull/247))
+- Move non-`network.*` attributes out of network.yaml.
+  ([#296](https://github.com/open-telemetry/semantic-conventions/pull/296))
+- Introducing Android `android.os.api_level` resource attribute.
+  ([#328](https://github.com/open-telemetry/semantic-conventions/pull/328))
 
 ## v1.21.0 (2023-07-13)
 

CONTRIBUTING.md

@@ -21,18 +21,18 @@ key, but non-obvious, aspects:
 - All descriptions, normative language are defined in the `docs/`
   directory.
   - We provide tooling to generate Markdown documentation from the formal
-    YAML definitons.  See [Yaml to Markdown](#yaml-to-markdown).
+    YAML definitons. See [Yaml to Markdown](#yaml-to-markdown).
   - We use Hugo to render [semantic conventions on our website](https://opentelemetry.io/docs/specs/semconv/).
     You will see `<!--- Hugo front matter used to generate ...` sections
-    in markdown.  See [Hugo frontmatter](#hugo-frontmatter) for details.
+    in markdown. See [Hugo frontmatter](#hugo-frontmatter) for details.
 - All changes to existing attributes, metrics, etc. MUST be allowed as
   per our [stability guarantees](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/versioning-and-stability.md#semantic-conventions-stability) and
-  defined in a schema file.  As part of any contribution, you should
+  defined in a schema file. As part of any contribution, you should
   include attribute changes defined in the `schema-next.yaml` file.
   For details, please read [the schema specification](https://opentelemetry.io/docs/specs/otel/schemas/).
 - After creating a pull request, please update the [CHANGELOG](CHANGELOG.md) file with
   a description of your changes.
-  
+
 Please make sure all Pull Requests are compliant with these rules!
 
 ### Hugo frontmatter

docs/resource/android.md

@@ -0,0 +1,15 @@
+# Android
+
+**Status**: [Experimental][DocumentStatus]
+
+**type:** `android`
+
+**Description**: The Android platform on which the Android application is running.
+
+<!-- semconv android -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `android.os.api_level` | string | Uniquely identifies the framework API revision offered by a version (`os.version`) of the android operating system. More information can be found [here](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels). | `33`; `32` | Recommended |
+<!-- endsemconv -->
+
+[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md

docs/system/system-metrics.md

@@ -47,6 +47,7 @@ instruments not explicitly defined in the specification.
   * [Metric: `system.processes.count`](#metric-systemprocessescount)
   * [Metric: `system.processes.created`](#metric-systemprocessescreated)
 - [`system.{os}.` - OS Specific System Metrics](#systemos---os-specific-system-metrics)
+  * [Metric: `system.linux.memory.available`](#metric-systemlinuxmemoryavailable)
 
 <!-- tocstop -->
 
@@ -739,3 +740,17 @@ an `{os}` prefix to split this metric across OSes.
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.22.0/specification/document-status.md
 [MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.22.0/specification/metrics/metric-requirement-level.md#recommended
+
+### Metric: `system.linux.memory.available`
+
+<!-- semconv metric.system.linux.memory.available(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    |
+| -------- | --------------- | ----------- | -------------- |
+| `system.linux.memory.available` | UpDownCounter | `By` | An estimate of how much memory is available for starting new applications, without causing swapping [1] |
+
+**[1]:** This is an alternative to `system.memory.usage` metric with `state=free`.
+Linux starting from 3.14 exports "available" memory. It takes "free" memory as a baseline, and then factors in kernel-specific values.
+This is supposed to be more accurate than just "free" memory.
+For reference, see the calculations [here](https://superuser.com/a/980821).
+See also `MemAvailable` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html).
+<!-- endsemconv -->

model/general.yaml

@@ -0,0 +1,89 @@
+groups:
+  - id: peer
+    prefix: peer
+    type: span
+    brief: "Operations that access some remote service."
+    attributes:
+      - id: service
+        type: string
+        brief: >
+          The [`service.name`](/docs/resource/README.md#service)
+          of the remote service. SHOULD be equal to the actual `service.name`
+          resource attribute of the remote service if any.
+        examples: "AuthTokenCache"
+  - id: identity
+    prefix: enduser
+    type: span
+    brief: >
+      These attributes may be used for any operation with an authenticated and/or authorized enduser.
+    attributes:
+      - id: id
+        type: string
+        brief: >
+          Username or client_id extracted from the access token or
+          [Authorization](https://tools.ietf.org/html/rfc7235#section-4.2)
+          header in the inbound request from outside the system.
+        examples: 'username'
+      - id: role
+        type: string
+        brief: 'Actual/assumed role the client is making the request under extracted from token or application security context.'
+        examples: 'admin'
+      - id: scope
+        type: string
+        brief: >
+          Scopes or granted authorities the client currently possesses extracted from token
+          or application security context. The value would come from the scope associated
+          with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3)
+          or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html).
+        examples: 'read:message, write:files'
+  - id: thread
+    prefix: thread
+    type: span
+    brief: >
+      These attributes may be used for any operation to store information about a thread that started a span.
+    attributes:
+      - id: id
+        type: int
+        brief: >
+          Current "managed" thread ID (as opposed to OS thread ID).
+        examples: 42
+      - id: name
+        type: string
+        brief: >
+          Current thread name.
+        examples: main
+      - id: daemon
+        brief: "Whether the thread is daemon or not."
+        type: boolean
+  - id: code
+    prefix: code
+    type: span
+    brief: >
+      These attributes allow to report this unit of code and therefore to provide more context about the span.
+    attributes:
+      - id: function
+        type: string
+        brief: >
+          The method or function name, or equivalent (usually rightmost part of the code unit's name).
+        examples: serveRequest
+      - id: namespace
+        type: string
+        brief: >
+          The "namespace" within which `code.function` is defined. Usually the qualified class or module name,
+          such that `code.namespace` + some separator + `code.function` form a unique identifier for the code unit.
+        examples: com.example.MyHttpService
+      - id: filepath
+        type: string
+        brief: >
+          The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path).
+        examples: /usr/local/MyApplication/content_root/app/index.php
+      - id: lineno
+        type: int
+        brief: >
+          The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`.
+        examples: 42
+      - id: column
+        type: int
+        brief: >
+          The column number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`.
+        examples: 16

model/metrics/system-metrics.yaml

@@ -490,3 +490,17 @@ groups:
     brief: "Total number of processes created over uptime of the host"
     instrument: counter
     unit: "{process}"
+
+  # system.linux.* metrics
+  - id: metric.system.linux.memory.available
+    type: metric
+    metric_name: system.linux.memory.available
+    brief: "An estimate of how much memory is available for starting new applications, without causing swapping"
+    note: |
+      This is an alternative to `system.memory.usage` metric with `state=free`.
+      Linux starting from 3.14 exports "available" memory. It takes "free" memory as a baseline, and then factors in kernel-specific values.
+      This is supposed to be more accurate than just "free" memory.
+      For reference, see the calculations [here](https://superuser.com/a/980821).
+      See also `MemAvailable` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html).
+    instrument: updowncounter
+    unit: "By"

model/network.yaml

@@ -162,91 +162,3 @@ groups:
         type: string
         brief: "The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network."
         examples: "DE"
-  - id: peer
-    prefix: peer
-    type: span
-    brief: "Operations that access some remote service."
-    attributes:
-      - id: service
-        type: string
-        brief: >
-          The [`service.name`](/docs/resource/README.md#service)
-          of the remote service. SHOULD be equal to the actual `service.name`
-          resource attribute of the remote service if any.
-        examples: "AuthTokenCache"
-  - id: identity
-    prefix: enduser
-    type: span
-    brief: >
-        These attributes may be used for any operation with an authenticated and/or authorized enduser.
-    attributes:
-      - id: id
-        type: string
-        brief: >
-          Username or client_id extracted from the access token or
-          [Authorization](https://tools.ietf.org/html/rfc7235#section-4.2)
-          header in the inbound request from outside the system.
-        examples: 'username'
-      - id: role
-        type: string
-        brief: 'Actual/assumed role the client is making the request under extracted from token or application security context.'
-        examples: 'admin'
-      - id: scope
-        type: string
-        brief: >
-          Scopes or granted authorities the client currently possesses extracted from token
-          or application security context. The value would come from the scope associated
-          with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3)
-          or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html).
-        examples: 'read:message, write:files'
-  - id: thread
-    prefix: thread
-    type: span
-    brief: >
-      These attributes may be used for any operation to store information about a thread that started a span.
-    attributes:
-      - id: id
-        type: int
-        brief: >
-          Current "managed" thread ID (as opposed to OS thread ID).
-        examples: 42
-      - id: name
-        type: string
-        brief: >
-          Current thread name.
-        examples: main
-      - id: daemon
-        brief: "Whether the thread is daemon or not."
-        type: boolean
-  - id: code
-    prefix: code
-    type: span
-    brief: >
-      These attributes allow to report this unit of code and therefore to provide more context about the span.
-    attributes:
-      - id: function
-        type: string
-        brief: >
-          The method or function name, or equivalent (usually rightmost part of the code unit's name).
-        examples: serveRequest
-      - id: namespace
-        type: string
-        brief: >
-          The "namespace" within which `code.function` is defined. Usually the qualified class or module name,
-          such that `code.namespace` + some separator + `code.function` form a unique identifier for the code unit.
-        examples: com.example.MyHttpService
-      - id: filepath
-        type: string
-        brief: >
-          The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path).
-        examples: /usr/local/MyApplication/content_root/app/index.php
-      - id: lineno
-        type: int
-        brief: >
-          The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`.
-        examples: 42
-      - id: column
-        type: int
-        brief: >
-          The column number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`.
-        examples: 16

model/resource/android.yaml

@@ -0,0 +1,14 @@
+groups:
+  - id: android
+    prefix: android
+    type: resource
+    brief: >
+      The Android platform on which the Android application is running.
+    attributes:
+      - id: os.api_level
+        type: string
+        brief: >
+          Uniquely identifies the framework API revision offered by a version
+          (`os.version`) of the android operating system. More information can be found
+          [here](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels).
+        examples: ['33', '32']