diff --git a/CHANGELOG.md b/CHANGELOG.md index 39fcf53427..5dd4e7098a 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5721670ffa..3bfe45c930 100644 --- a/CONTRIBUTING.md +++ b/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 ` +| 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 | + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index f17b799050..37b14608a1 100644 --- a/docs/system/system-metrics.md +++ b/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) @@ -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` + + +| 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). + diff --git a/model/general.yaml b/model/general.yaml new file mode 100644 index 0000000000..4f387bac6f --- /dev/null +++ b/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 diff --git a/model/metrics/system-metrics.yaml b/model/metrics/system-metrics.yaml index 2759d1f66f..cfd20979f2 100644 --- a/model/metrics/system-metrics.yaml +++ b/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" diff --git a/model/network.yaml b/model/network.yaml index 478937c110..fa83e62099 100644 --- a/model/network.yaml +++ b/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 diff --git a/model/resource/android.yaml b/model/resource/android.yaml new file mode 100644 index 0000000000..dcc236d846 --- /dev/null +++ b/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']