From a5cbc9d9840fc052bf3c603d242a2e70b1aa75d5 Mon Sep 17 00:00:00 2001 From: Roger Coll Date: Mon, 27 Oct 2025 10:30:48 +0100 Subject: [PATCH 1/7] rename linux.memory.* metrics and attributes to memory.linux.* --- docs/registry/attributes/linux.md | 6 ++-- docs/registry/attributes/system.md | 10 ++++++ docs/system/system-metrics.md | 26 +++++++------- ...registry.yaml => registry-deprecated.yaml} | 10 +++--- .../system/deprecated/metrics-deprecated.yaml | 34 +++++++++++++++++++ model/system/metrics.yaml | 14 ++++---- model/system/registry.yaml | 12 +++++++ 7 files changed, 85 insertions(+), 27 deletions(-) rename model/linux/{registry.yaml => registry-deprecated.yaml} (67%) diff --git a/docs/registry/attributes/linux.md b/docs/registry/attributes/linux.md index 9795b3094b..ae9fe0d0da 100644 --- a/docs/registry/attributes/linux.md +++ b/docs/registry/attributes/linux.md @@ -3,13 +3,13 @@ # Linux -## Linux Memory Attributes +## Deprecated Linux Attributes -Describes Linux Memory attributes +Deprecated Linux attributes. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `linux.memory.slab.state` | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | ![Development](https://img.shields.io/badge/-development-blue) | +| `linux.memory.slab.state` | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `system.memory.linux.slab.state`. | --- diff --git a/docs/registry/attributes/system.md b/docs/registry/attributes/system.md index 42b9508393..72b65fb59c 100644 --- a/docs/registry/attributes/system.md +++ b/docs/registry/attributes/system.md @@ -58,10 +58,20 @@ Describes System Memory attributes | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| +| `system.memory.linux.slab.state` | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | ![Development](https://img.shields.io/badge/-development-blue) | | `system.memory.state` | string | The memory state | `free`; `cached` | ![Development](https://img.shields.io/badge/-development-blue) | --- +`system.memory.linux.slab.state` 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 | Stability | +|---|---|---| +| `reclaimable` | reclaimable | ![Development](https://img.shields.io/badge/-development-blue) | +| `unreclaimable` | unreclaimable | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + `system.memory.state` 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 | Stability | diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 234ec4e162..92f3e588a0 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -57,9 +57,9 @@ Resource attributes related to a host, SHOULD be reported under the `host.*` nam - [Aggregate system process metrics](#aggregate-system-process-metrics) - [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) - - [Metric: `system.linux.memory.slab.usage`](#metric-systemlinuxmemoryslabusage) +- [`system.memory.{os}.` - OS Specific System Memory Metrics](#systemos---os-specific-system-metrics) + - [Metric: `system.memory.linux.available`](#metric-systemmemorylinuxavailable) + - [Metric: `system.memory.linux.slab.usage`](#metric-systemmemorylinuxslabusage) @@ -1149,7 +1149,7 @@ This metric is [recommended][MetricRecommended]. -## `system.{os}.` - OS Specific System Metrics +## `system.memory.{os}.` - OS Specific System Memory Metrics Instrument names for system level metrics that have different and conflicting meaning across multiple OSes should be prefixed with `system.{os}.` and @@ -1181,9 +1181,9 @@ an `{os}` prefix to split this metric across OSes. [MetricRecommended]: /docs/general/metric-requirement-level.md#recommended [MetricOptIn]: /docs/general/metric-requirement-level.md#opt-in -### Metric: `system.linux.memory.available` +### Metric: `system.memory.linux.available` - + @@ -1192,7 +1192,7 @@ an `{os}` prefix to split this metric across OSes. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | -| `system.linux.memory.available` | UpDownCounter | `By` | An estimate of how much memory is available for starting new applications, without causing swapping. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) | +| `system.memory.linux.available` | UpDownCounter | `By` | An estimate of how much memory is available for starting new applications, without causing swapping. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) | **[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. @@ -1205,11 +1205,11 @@ See also `MemAvailable` in [/proc/meminfo](https://man7.org/linux/man-pages/man5 -### Metric: `system.linux.memory.slab.usage` +### Metric: `system.memory.linux.slab.usage` This metric is [recommended][MetricRecommended]. - + @@ -1218,19 +1218,19 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | -| `system.linux.memory.slab.usage` | UpDownCounter | `By` | Reports the memory used by the Linux kernel for managing caches of frequently used objects. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) | +| `system.memory.linux.slab.usage` | UpDownCounter | `By` | Reports the memory used by the Linux kernel for managing caches of frequently used objects. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) | -**[1]:** The sum over the `reclaimable` and `unreclaimable` state values in `linux.memory.slab.usage` SHOULD be equal to the total slab memory available on the system. +**[1]:** The sum over the `reclaimable` and `unreclaimable` state values in `memory.linux.slab.usage` SHOULD be equal to the total slab memory available on the system. Note that the total slab memory is not constant and may vary over time. See also the [Slab allocator](https://blogs.oracle.com/linux/post/understanding-linux-kernel-memory-statistics) and `Slab` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html). | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`linux.memory.slab.state`](/docs/registry/attributes/linux.md) | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`system.memory.linux.slab.state`](/docs/registry/attributes/system.md) | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | --- -`linux.memory.slab.state` 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.memory.linux.slab.state` 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 | Stability | |---|---|---| diff --git a/model/linux/registry.yaml b/model/linux/registry-deprecated.yaml similarity index 67% rename from model/linux/registry.yaml rename to model/linux/registry-deprecated.yaml index 6b585719b3..58db637dfb 100644 --- a/model/linux/registry.yaml +++ b/model/linux/registry-deprecated.yaml @@ -1,9 +1,8 @@ groups: - # linux.memory.* attribute group - - id: registry.linux.memory + - id: registry.linux.deprecated type: attribute_group - display_name: Linux Memory Attributes - brief: "Describes Linux Memory attributes" + display_name: Deprecated Linux Attributes + brief: "Deprecated Linux attributes." attributes: - id: linux.memory.slab.state type: @@ -17,3 +16,6 @@ groups: stability: development brief: "The Linux Slab memory state" examples: ["reclaimable", "unreclaimable"] + deprecated: + reason: renamed + renamed_to: system.memory.linux.slab.state diff --git a/model/system/deprecated/metrics-deprecated.yaml b/model/system/deprecated/metrics-deprecated.yaml index b58ef85bca..4787116524 100644 --- a/model/system/deprecated/metrics-deprecated.yaml +++ b/model/system/deprecated/metrics-deprecated.yaml @@ -58,3 +58,37 @@ groups: - ref: network.io.direction entity_associations: - host + + - id: metric.system.linux.memory.available + type: metric + metric_name: system.linux.memory.available + annotations: + code_generation: + metric_value_type: int + stability: development + deprecated: + reason: renamed + renamed_to: system.memory.linux.available + brief: The number of packets transferred. + instrument: counter + unit: "{packet}" + entity_associations: + - host + + - id: metric.system.linux.memory.slab.usage + type: metric + metric_name: system.linux.memory.slab.usage + annotations: + code_generation: + metric_value_type: int + stability: development + deprecated: + reason: renamed + renamed_to: system.memory.linux.slab.usage + brief: The number of packets transferred. + instrument: counter + unit: "{packet}" + attributes: + - ref: linux.memory.slab.state + entity_associations: + - host diff --git a/model/system/metrics.yaml b/model/system/metrics.yaml index 109e0aecdd..200dbbb8ba 100644 --- a/model/system/metrics.yaml +++ b/model/system/metrics.yaml @@ -524,10 +524,10 @@ groups: entity_associations: - host - # system.linux.* metrics - - id: metric.system.linux.memory.available + # system.memory.linux.* metrics + - id: metric.system.memory.linux.available type: metric - metric_name: system.linux.memory.available + metric_name: system.memory.linux.available annotations: code_generation: metric_value_type: int @@ -545,21 +545,21 @@ groups: entity_associations: - host - - id: metric.system.linux.memory.slab.usage + - id: metric.system.memory.linux.slab.usage type: metric - metric_name: system.linux.memory.slab.usage + metric_name: system.memory.linux.slab.usage annotations: code_generation: metric_value_type: int stability: development brief: "Reports the memory used by the Linux kernel for managing caches of frequently used objects." note: | - The sum over the `reclaimable` and `unreclaimable` state values in `linux.memory.slab.usage` SHOULD be equal to the total slab memory available on the system. + The sum over the `reclaimable` and `unreclaimable` state values in `memory.linux.slab.usage` SHOULD be equal to the total slab memory available on the system. Note that the total slab memory is not constant and may vary over time. See also the [Slab allocator](https://blogs.oracle.com/linux/post/understanding-linux-kernel-memory-statistics) and `Slab` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html). instrument: updowncounter unit: "By" attributes: - - ref: linux.memory.slab.state + - ref: system.memory.linux.slab.state entity_associations: - host diff --git a/model/system/registry.yaml b/model/system/registry.yaml index c93bc24355..e4d2efb1be 100644 --- a/model/system/registry.yaml +++ b/model/system/registry.yaml @@ -47,6 +47,18 @@ groups: stability: development brief: "The memory state" examples: ["free", "cached"] + - id: system.memory.linux.slab.state + type: + members: + - id: reclaimable + value: 'reclaimable' + stability: development + - id: unreclaimable + value: 'unreclaimable' + stability: development + stability: development + brief: "The Linux Slab memory state" + examples: ["reclaimable", "unreclaimable"] # system.paging.* attribute group - id: registry.system.paging type: attribute_group From 8eb104ae7fd96951ac75ba2a2d846f8f6a434bd2 Mon Sep 17 00:00:00 2001 From: Roger Coll Date: Mon, 27 Oct 2025 10:32:57 +0100 Subject: [PATCH 2/7] chore: add changelog file --- .chloggen/rename_system_linux.yaml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100755 .chloggen/rename_system_linux.yaml diff --git a/.chloggen/rename_system_linux.yaml b/.chloggen/rename_system_linux.yaml new file mode 100755 index 0000000000..87d0a8ee8e --- /dev/null +++ b/.chloggen/rename_system_linux.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: breaking + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: system, linux + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Rename `*.linux.memory` metrics and attributes to `*.memory.linux` + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [1661] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: From f8d8d450f4471ee5696a1d4c71e5804ca21b2f5d Mon Sep 17 00:00:00 2001 From: Roger Coll Date: Mon, 27 Oct 2025 10:47:53 +0100 Subject: [PATCH 3/7] fix: markdown dropdown and linx issue template --- .github/ISSUE_TEMPLATE/bug_report.yaml | 1 - .github/ISSUE_TEMPLATE/change_proposal.yaml | 1 - .github/ISSUE_TEMPLATE/new-conventions.yaml | 1 - docs/system/system-metrics.md | 2 +- 4 files changed, 1 insertion(+), 4 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index a187ceb14d..bc47e17aed 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -65,7 +65,6 @@ body: - area:ios - area:jvm - area:k8s - - area:linux - area:log - area:mainframe - area:messaging diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index 7cbe913ab9..22ae1f480c 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -57,7 +57,6 @@ body: - area:ios - area:jvm - area:k8s - - area:linux - area:log - area:mainframe - area:messaging diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index 8955a43f71..b5ba619910 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -68,7 +68,6 @@ body: - area:ios - area:jvm - area:k8s - - area:linux - area:log - area:mainframe - area:messaging diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 92f3e588a0..c30c7d7b3f 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -57,7 +57,7 @@ Resource attributes related to a host, SHOULD be reported under the `host.*` nam - [Aggregate system process metrics](#aggregate-system-process-metrics) - [Metric: `system.process.count`](#metric-systemprocesscount) - [Metric: `system.process.created`](#metric-systemprocesscreated) -- [`system.memory.{os}.` - OS Specific System Memory Metrics](#systemos---os-specific-system-metrics) +- [`system.memory.{os}.` - OS Specific System Memory Metrics](#systemmemoryos---os-specific-system-memory-metrics) - [Metric: `system.memory.linux.available`](#metric-systemmemorylinuxavailable) - [Metric: `system.memory.linux.slab.usage`](#metric-systemmemorylinuxslabusage) From ebd564b54d9d6f4d7e2d834f5cc6a5e9a4025a28 Mon Sep 17 00:00:00 2001 From: Roger Coll Date: Mon, 27 Oct 2025 10:51:16 +0100 Subject: [PATCH 4/7] fix docs section reference --- docs/general/naming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/naming.md b/docs/general/naming.md index 0094813d81..3932ce4877 100644 --- a/docs/general/naming.md +++ b/docs/general/naming.md @@ -426,7 +426,7 @@ attribute use the same system name (`azure.cosmosdb`). ### Known exceptions - Operational system and process-related attributes and metrics [follow a - pattern](/docs/system/system-metrics.md#systemos---os-specific-system-metrics) + pattern](/docs/system/system-metrics.md#systemmemoryos---os-specific-system-memory-metrics) of `system.{os}` and `process.{os}`. - [RPC](/docs/rpc/README.md) and [messaging](/docs/messaging/README.md) semantic From b45cd4730b16a6cfaf761320a7b5a57763e40799 Mon Sep 17 00:00:00 2001 From: Roger Coll Date: Thu, 30 Oct 2025 10:02:52 +0100 Subject: [PATCH 5/7] chore: add linux area codeowners --- .github/CODEOWNERS | 1 + areas.yaml | 1 + 2 files changed, 2 insertions(+) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index a4a60146db..636d070396 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -52,6 +52,7 @@ /model/cpu/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers /model/disk/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers /model/host/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers +/model/linux/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers # /model/network/ is defined in HTTP section /model/os/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers /model/process/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers @open-telemetry/semconv-security-approvers diff --git a/areas.yaml b/areas.yaml index a2ca0801b6..d2055f5762 100644 --- a/areas.yaml +++ b/areas.yaml @@ -14,6 +14,7 @@ areas: - area:cpu - area:disk - area:network + - area:linux status: - accepting_contributions - active From 2edc8d9e9e3e17f85822b60f88f44f4d8abf59a3 Mon Sep 17 00:00:00 2001 From: Roger Coll Date: Thu, 30 Oct 2025 10:04:37 +0100 Subject: [PATCH 6/7] docs: update area docs --- AREAS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AREAS.md b/AREAS.md index 424978f9d0..127c5bae73 100644 --- a/AREAS.md +++ b/AREAS.md @@ -27,7 +27,7 @@ their owners, related project (and project board) as well as its current status. | Name | Owners | Project | Board | Labels | Status | Notes | |------|--------|---------|-------|-------|--------|-------| -| Semantic Conventions: System | [semconv-system-approvers](https://github.com/orgs/open-telemetry/teams/semconv-system-approvers) | https://github.com/open-telemetry/community/blob/main/projects/system-semconv.md | https://github.com/orgs/open-telemetry/projects/55 | `area:system`, `area:host`, `area:process`, `area:nfs`, `area:os`, `area:cpu`, `area:disk`, `area:network` | `accepting_contributions`, `active` | The SIG is looking for contributions! | +| Semantic Conventions: System | [semconv-system-approvers](https://github.com/orgs/open-telemetry/teams/semconv-system-approvers) | https://github.com/open-telemetry/community/blob/main/projects/system-semconv.md | https://github.com/orgs/open-telemetry/projects/55 | `area:system`, `area:host`, `area:process`, `area:nfs`, `area:os`, `area:cpu`, `area:disk`, `area:network`, `area:linux` | `accepting_contributions`, `active` | The SIG is looking for contributions! | | Semantic Conventions: K8s | [semconv-k8s-approvers](https://github.com/orgs/open-telemetry/teams/semconv-k8s-approvers) | https://github.com/open-telemetry/community/blob/main/projects/k8s-semconv.md | https://github.com/orgs/open-telemetry/projects/114 | `area:k8s` | `accepting_contributions`, `active` | The SIG is looking for contributions! | | Semantic Conventions: GenAI | [semconv-genai-approvers](https://github.com/orgs/open-telemetry/teams/semconv-genai-approvers) | https://github.com/open-telemetry/community/blob/main/projects/gen-ai.md | https://github.com/orgs/open-telemetry/projects/82 | `area:gen-ai`, `area:openai` | `accepting_contributions`, `active` | The SIG is looking for contributions! | | Semantic Conventions: CI/CD | [semconv-cicd-approvers](https://github.com/orgs/open-telemetry/teams/semconv-cicd-approvers) | https://github.com/open-telemetry/community/blob/main/projects/ci-cd.md | https://github.com/orgs/open-telemetry/projects/79 | `area:cicd`, `area:artifact`, `area:deployment`, `area:test`, `area:vcs` | `accepting_contributions`, `active` | The SIG is looking for contributions! | From 14a4c234f97eb9022a146a9a198b9014e9b5e924 Mon Sep 17 00:00:00 2001 From: Roger Coll Date: Tue, 4 Nov 2025 18:15:21 +0100 Subject: [PATCH 7/7] docs: add OS name level clarification --- docs/non-normative/groups/system/design-philosophy.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/non-normative/groups/system/design-philosophy.md b/docs/non-normative/groups/system/design-philosophy.md index fd6861be42..a5a51774f6 100644 --- a/docs/non-normative/groups/system/design-philosophy.md +++ b/docs/non-normative/groups/system/design-philosophy.md @@ -213,7 +213,7 @@ 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. +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 @@ -277,6 +277,7 @@ down with more specificity. Relevant discussions: [\#1255](https://github.com/open-telemetry/semantic-conventions/issues/1255), [\#1364](https://github.com/open-telemetry/semantic-conventions/pull/1364#discussion_r1852465994) +[\#2984](https://github.com/open-telemetry/semantic-conventions/pull/2984#discussion_r2466369361) Monitoring operating systems is an old practice, and there are numerous heavily differing approaches within different platforms. There are lots of metrics, even @@ -289,7 +290,7 @@ Thus we have decided that any instrumentation that is: 1. Specific to a particular operating system 2. Not meant to be part of what we consider our most important general use cases -will have the Operating System name as part of the namespace. +will include the Operating System name as part of the namespace. For example, there may be `process.linux`, `process.windows`, or `process.posix` names for metrics and attributes. We will not have root `linux.*`, `windows.*`, @@ -300,4 +301,6 @@ had OS root namespaces, different sources like `system`, `process`, etc. could get very tangled within each OS namespace, defeating the intended design philosophy. +However, to clarify — when we refer to avoiding OS names at the “root namespace” level, we also mean avoiding them at the area level. The OS name should appear after the area of concern (such as `system.memory.linux.*`), not before it. This ensures that users can first navigate by functional area (e.g. memory, CPU, network) and then, if necessary, drill down into OS-specific variants within that area. + [use cases doc]: ./use-cases.md