diff --git a/.chloggen/1694.yaml b/.chloggen/1694.yaml
new file mode 100644
index 0000000000..ddf40d60a4
--- /dev/null
+++ b/.chloggen/1694.yaml
@@ -0,0 +1,8 @@
+change_type: enhancement
+component: docs
+note: Update attribute, events, and metrics naming guidance to include new best practices.
+subtext: |
+ - Use namespaces (with `.` delimiter) whenever possible.
+ - Use precise, descriptive, unambiguous names that leave room for expansion.
+
+issues: [1694]
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5f764273a9..4cfc04991c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -399,7 +399,7 @@ exists in some form in ECS, consider the following guidelines:
data, user issue reports, feature requests, examples of prior work on a
different standard or comparable evidence about the alternatives.
- When no suitable alternatives are provided, altering an ECS name solely
- for the purpose of complying with [Name Pluralization guidelines](docs/general/attribute-naming.md#name-pluralization-guidelines)
+ for the purpose of complying with [Name Pluralization guidelines](docs/general/naming.md#attribute-name-pluralization-guidelines)
MAY BE avoided.
- Do not use an existing ECS name as a namespace. If the name must differ, use a
different namespace name to avoid clashes or avoid using the namespace
diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md
index 91df4271b1..4bfe974911 100644
--- a/docs/attributes-registry/README.md
+++ b/docs/attributes-registry/README.md
@@ -102,4 +102,4 @@ Currently, the following namespaces exist:
- [VCS](vcs.md)
- [Webengine](webengine.md)
-[developers recommendations]: ../general/attribute-naming.md#recommendations-for-application-developers
+[developers recommendations]: ../general/naming.md#recommendations-for-application-developers
diff --git a/docs/general/README.md b/docs/general/README.md
index a4bff5597e..83fd3366cb 100644
--- a/docs/general/README.md
+++ b/docs/general/README.md
@@ -17,12 +17,3 @@ The following general Semantic Conventions are defined:
* [Logs](logs.md): General Semantic Conventions for logs.
* [Metrics](metrics.md): General Semantic Conventions for metrics.
* [Spans](trace.md): General Semantic Conventions for traces / spans.
-
-## Event Name Reuse Prohibition
-
-A new event MUST NOT be added with the same name as an event that existed in
-the past but was renamed (with a corresponding schema file).
-
-When introducing a new event name check all existing schema files to make sure
-the name does not appear as a key of any "rename_events" section (keys denote
-old event names in rename operations).
diff --git a/docs/general/attribute-naming.md b/docs/general/attribute-naming.md
deleted file mode 100644
index 34e84d2f9d..0000000000
--- a/docs/general/attribute-naming.md
+++ /dev/null
@@ -1,177 +0,0 @@
-# Attribute Naming
-
-**Status**: [Stable][DocumentStatus]
-
-
-Table of Contents
-
-
-
-- [Name Pluralization Guidelines](#name-pluralization-guidelines)
-- [Name Abbreviation Guidelines](#name-abbreviation-guidelines)
-- [Name Reuse Prohibition](#name-reuse-prohibition)
-- [Recommendations for OpenTelemetry Authors](#recommendations-for-opentelemetry-authors)
-- [Recommendations for Application Developers](#recommendations-for-application-developers)
-- [otel.\* Namespace](#otel-namespace)
-
-
-
-
-
-_This section applies to Resource, Span, Log, and Metric attribute names (also
-known as the "attribute keys"). For brevity within this section when we use the
-term "name" without an adjective it is implied to mean "attribute name"._
-
-Every name MUST be a valid Unicode sequence.
-
-_Note: we merely require that the names are represented as Unicode sequences.
-This specification does not define how exactly the Unicode sequences are
-encoded. The encoding can vary from one programming language to another and from
-one wire format to another. Use the idiomatic way to represent Unicode in the
-particular programming language or wire format._
-
-Names SHOULD follow these rules:
-
-- Names SHOULD be lowercase.
-
-- Use namespacing to avoid name clashes. Delimit the namespaces using a dot
- character. For example `service.version` denotes the service version where
- `service` is the namespace and `version` is an attribute in that namespace.
-
-- Namespaces can be nested. For example `telemetry.sdk` is a namespace inside
- top-level `telemetry` namespace and `telemetry.sdk.name` is an attribute
- inside `telemetry.sdk` namespace. Note: the fact that an entity is located
- within another entity is typically not a sufficient reason for forming nested
- namespaces. The purpose of a namespace is to avoid name clashes, not to
- indicate entity hierarchies. This purpose should primarily drive the decision
- about forming nested namespaces.
-
-- For each multi-word dot-delimited component of the attribute name separate the
- words by underscores (i.e. use snake_case). For example
- `http.response.status_code` denotes the status code in the http namespace.
-
-- Names SHOULD NOT coincide with namespaces. For example if
- `service.instance.id` is an attribute name then it is no longer valid to have
- an attribute named `service.instance` because `service.instance` is already a
- namespace. Because of this rule be careful when choosing names: every existing
- name prohibits existence of an equally named namespace in the future, and vice
- versa: any existing namespace prohibits existence of an equally named
- attribute key in the future.
-
-## Name Pluralization Guidelines
-
-- When an attribute represents a single entity, the attribute name SHOULD be
- singular. Examples: `host.name`, `container.id`.
-
-- When attribute can represent multiple entities, the attribute name SHOULD be
- pluralized and the value type SHOULD be an array. E.g. `process.command_args`
- might include multiple values: the executable name and command arguments.
-
-- When an attribute represents a measurement,
- [Metric Name Pluralization Guidelines](./metrics.md#pluralization) SHOULD be
- followed for the attribute name.
-
-## Name Abbreviation Guidelines
-
-Abbreviations MAY be used when they are widely recognized and commonly used.
-
-Examples include common technical abbreviations such as `IP`, `DB`, `CPU`,
-`HTTP`, `URL`, or product names like `AWS`, `GCP`, `K8s`.
-
-Abbreviations SHOULD be avoided if they are ambiguous, for example, when they apply
-to multiple products or concepts.
-
-## Name Reuse Prohibition
-
-A new attribute MUST NOT be added with the same name as an attribute that
-existed in the past but was renamed (with a corresponding schema file).
-
-When introducing a new attribute name check all existing schema files to make
-sure the name does not appear as a key of any "rename_attributes" section (keys
-denote old attribute names in rename operations).
-
-## Recommendations for OpenTelemetry Authors
-
-- All names that are part of OpenTelemetry semantic conventions SHOULD be part
- of a namespace.
-
-- When coming up with a new semantic convention make sure to check existing
- namespaces ([Semantic Conventions](./README.md)) to see if the new name fits.
-
-- When a new namespace is necessary consider whether it should be a top-level
- namespace (e.g. `service`) or a nested namespace (e.g. `service.instance`).
-
-- Semantic conventions exist for four areas: for Resource, Span, Log, and Metric
- attribute names. In addition, for spans we have two more areas: Event and Link
- attribute names. Identical namespaces or names in all these areas MUST have
- identical meanings. For example the `http.request.method` span attribute name
- denotes exactly the same concept as the `http.request.method` metric
- attribute, has the same data type and the same set of possible values (in both
- cases it records the value of the HTTP protocol's request method as a string).
-
-- Semantic conventions MUST limit names to printable Basic Latin characters
- (more precisely to
- [U+0021 .. U+007E]()
- subset of Unicode code points). It is recommended to further limit names to
- the following Unicode code points: Latin alphabet, Numeric, Underscore, Dot
- (as namespace delimiter).
-
-> Note:
-> Semantic Conventions tooling limits names to lowercase
-> Latin alphabet, Numeric, Underscore, Dot (as namespace delimiter).
-> Names must start with a letter, end with an alphanumeric character, and must not
-> contain two or more consecutive delimiters (Underscore or Dot).
-
-## Recommendations for Application Developers
-
-As an application developer when you need to record an attribute first consult
-existing [semantic conventions](./README.md). If an appropriate name does not
-exists you will need to come up with a new name. To do that consider a few
-options:
-
-- The name is specific to your company and may be possibly used outside the
- company as well. To avoid clashes with names introduced by other companies (in
- a distributed system that uses applications from multiple vendors) it is
- recommended to prefix the new name by your company's reverse domain name, e.g.
- `com.acme.shopname`.
-
-- The name is specific to your application that will be used internally only. If
- you already have an internal company process that helps you to ensure no name
- clashes happen then feel free to follow it. Otherwise it is recommended to
- prefix the attribute name by your application name, provided that the
- application name is reasonably unique within your organization (e.g.
- `myuniquemapapp.longitude` is likely fine). Make sure the application name
- does not clash with an existing semantic convention namespace.
-
-- It is not recommended to use existing OpenTelemetry semantic convention
- namespace as a prefix for a new company- or application-specific attribute
- name. Doing so may result in a name clash in the future, if OpenTelemetry
- decides to use that same name for a different purpose or if some other third
- party instrumentation decides to use that exact same attribute name and you
- combine that instrumentation with your own.
-
-- The name may be generally applicable to applications in the industry. In that
- case consider submitting a proposal to this specification to add a new name to
- the semantic conventions, and if necessary also to add a new namespace.
-
-It is recommended to limit names to printable Basic Latin characters (more
-precisely to
-[U+0021 .. U+007E]()
-subset of Unicode code points).
-
-## otel.\* Namespace
-
-Attribute names that start with `otel.` are reserved to be defined by
-OpenTelemetry specification. These are typically used to express OpenTelemetry
-concepts in formats that don't have a corresponding concept.
-
-For example, the `otel.scope.name` attribute is used to record the
-instrumentation scope name, which is an OpenTelemetry concept that is natively
-represented in OTLP, but does not have an equivalent in other telemetry formats
-and protocols.
-
-Any additions to the `otel.*` namespace MUST be approved as part of
-OpenTelemetry specification.
-
-[DocumentStatus]:
- https://opentelemetry.io/docs/specs/otel/document-status
diff --git a/docs/general/events.md b/docs/general/events.md
index c63aa5904a..4e80862f13 100644
--- a/docs/general/events.md
+++ b/docs/general/events.md
@@ -31,7 +31,7 @@ structure and semantics will also be defined.
## General event semantics
* An event MUST have an [Event name property](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname)
- that uniquely identifies the event. Event names are subject to the same rules as [attribute names](/docs/general/attribute-naming.md).
+ that uniquely identifies the event. Event names are subject to the [Naming guidelines](/docs/general/naming.md).
* Event MAY have [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute)
attributes that provide additional context about the event.
* It MAY contain a _payload_ (body) that describes the specific details of the
diff --git a/docs/general/metrics.md b/docs/general/metrics.md
index fbe38ea7c4..961abaedf4 100644
--- a/docs/general/metrics.md
+++ b/docs/general/metrics.md
@@ -10,15 +10,7 @@ aliases: [metrics-general]
- [General Guidelines](#general-guidelines)
- - [Name Reuse Prohibition](#name-reuse-prohibition)
- - [Metric attributes](#metric-attributes)
- [Units](#units)
- - [Naming rules for Counters and UpDownCounters](#naming-rules-for-counters-and-updowncounters)
- - [Pluralization](#pluralization)
- - [Use `count` Instead of Pluralization for UpDownCounters](#use-count-instead-of-pluralization-for-updowncounters)
- - [Do not use `total`](#do-not-use-total)
-- [General Metric Semantic Conventions](#general-metric-semantic-conventions)
- - [Instrument Naming](#instrument-naming)
- [Instrument Units](#instrument-units)
- [Instrument Types](#instrument-types)
- [Consistent UpDownCounter timeseries](#consistent-updowncounter-timeseries)
@@ -30,12 +22,16 @@ The following semantic conventions surrounding metrics are defined:
* **[General Guidelines](#general-guidelines): General metrics guidelines.**
* [Database](/docs/database/database-metrics.md): For SQL and NoSQL client metrics.
* [FaaS](/docs/faas/faas-metrics.md): For [Function as a Service](https://wikipedia.org/wiki/Function_as_a_service) metrics.
+* [GenAI](/docs/gen-ai/gen-ai-metrics.md): For Generative AI metrics.
* [HTTP](/docs/http/http-metrics.md): For HTTP client and server metrics.
* [Messaging](/docs/messaging/messaging-metrics.md): For messaging systems (queues, publish/subscribe, etc.) metrics.
* [RPC](/docs/rpc/rpc-metrics.md): For RPC client and server metrics.
+* [.NET](/docs/dotnet/README.md): For network-related metrics emitted by .NET runtime components.
* **System metrics**
* [System](/docs/system/system-metrics.md): For standard system metrics.
+ * [Container](/docs/system/container-metrics.md)
* [Hardware](/docs/system/hardware-metrics.md): For hardware-related metrics.
+ * [K8s](/docs/system/k8s-metrics.md): For K8s metrics.
* [Process](/docs/system/process-metrics.md): For standard process metrics.
* [Runtime Environment](/docs/runtime/README.md#metrics): For runtime environment metrics.
@@ -47,11 +43,8 @@ their own [Resource Semantic Conventions](/docs/resource/README.md).
**Status**: [Experimental][DocumentStatus]
-Metric names and attributes exist within a single universe and a single
-hierarchy. Metric names and attributes MUST be considered within the universe of
-all existing metric names. When defining new metric names and attributes,
-consider the prior art of existing standard metrics and metrics from
-frameworks/libraries.
+When defining new metric names and attributes, consider the prior art of
+existing standard metrics and metrics from frameworks/libraries.
Associated metrics SHOULD be nested together in a hierarchy based on their
usage. Define a top-level hierarchy for common metric categories: for OS
@@ -78,41 +71,11 @@ where similar metrics have significantly different implementations across the
breadth of all existing metrics. For example, every garbage collected runtime
has slightly different strategies and measures. Using a single set of metric
names for GC, not divided by the runtime, could create dissimilar comparisons
-and confusion for end users. (For example, prefer `process.runtime.java.gc*` over
-`process.runtime.gc.*`.) Measures of many operating system metrics are similarly
+and confusion for end users. (For example, prefer `jvm.gc*` over
+`gc.*`.) Measures of many operating system metrics are similarly
ambiguous.
-Metric names and attributes SHOULD follow the general
-[name abbreviation guidelines](attribute-naming.md#name-abbreviation-guidelines).
-
-### Name Reuse Prohibition
-
-A new metric MUST NOT be added with the same name as a metric that existed in
-the past but was renamed (with a corresponding schema file).
-
-When introducing a new metric name check all existing schema files to make sure
-the name does not appear as a key of any "rename_metrics" section (keys denote
-old metric names in rename operations).
-
-### Metric attributes
-
-Metric attributes SHOULD follow the general [attribute naming rules](attribute-naming.md).
-In particular, metric attributes SHOULD have a namespace.
-
-Metric attributes SHOULD be added under the metric namespace when their usage and
-semantics are exclusive to the metric.
-
-Examples:
-
-Attributes `mode` and `mountpoint` for metric `system.filesystem.usage`
-should be namespaced as `system.filesystem.mode` and `system.filesystem.mountpoint`.
-
-Metrics can also have attributes outside of their namespace.
-
-Examples:
-
-Metric `http.server.request.duration` uses attributes from the registry such as
-`server.port`, `error.type`.
+Metric names and attributes SHOULD follow the general [naming guidelines](naming.md).
### Units
@@ -126,97 +89,6 @@ When building components that interoperate between OpenTelemetry and a system
using the OpenMetrics exposition format, use the
[OpenMetrics Guidelines](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/compatibility/prometheus_and_openmetrics.md).
-### Naming rules for Counters and UpDownCounters
-
-#### Pluralization
-
-Metric namespaces SHOULD NOT be pluralized.
-
-Metric names SHOULD NOT be pluralized, unless the value being recorded
-represents discrete instances of a
-[countable quantity](https://wikipedia.org/wiki/Count_noun).
-Generally, the name SHOULD be pluralized only if the unit of the metric in
-question is a non-unit (like `{fault}` or `{operation}`).
-
-Examples:
-
-* `system.filesystem.utilization`, `http.server.request.duration`, and `system.cpu.time`
-should not be pluralized, even if many data points are recorded.
-* `system.paging.faults`, `system.disk.operations`, and `system.network.packets`
-should be pluralized, even if only a single data point is recorded.
-
-#### Use `count` Instead of Pluralization for UpDownCounters
-
-If the value being recorded represents the count of concepts signified
-by the namespace then the metric should be named `count` (within its namespace).
-
-For example if we have a namespace `system.process` which contains all metrics related
-to the processes then to represent the count of the processes we can have a metric named
-`system.process.count`.
-
-#### Do not use `total`
-
-UpDownCounters SHOULD NOT use `_total` because then they will look like
-monotonic sums.
-
-Counters SHOULD NOT append `_total` either because then their meaning will
-be confusing in delta backends.
-
-## General Metric Semantic Conventions
-
-**Status**: [Mixed][DocumentStatus]
-
-The following semantic conventions aim to keep naming consistent. They
-provide guidelines for most of the cases in this specification and should be
-followed for other instruments not explicitly defined in this document.
-
-### Instrument Naming
-
-**Status**: [Experimental][DocumentStatus]
-
-- **limit** - an instrument that measures the constant, known total amount of
-something should be called `entity.limit`. For example, `system.memory.limit`
-for the total amount of memory on a system.
-
-- **usage** - an instrument that measures an amount used out of a known total
-(**limit**) amount should be called `entity.usage`. For example,
-`system.memory.usage` with attribute `state = used | cached | free | ...` for the
-amount of memory in a each state. Where appropriate, the sum of **usage**
-over all attribute values SHOULD be equal to the **limit**.
-
- A measure of the amount consumed of an unlimited resource, or of a resource
- whose limit is unknowable, is differentiated from **usage**. For example, the
- maximum possible amount of virtual memory that a process may consume may
- fluctuate over time and is not typically known.
-
-- **utilization** - an instrument that measures the *fraction* of **usage**
-out of its **limit** should be called `entity.utilization`. For example,
-`system.memory.utilization` for the fraction of memory in use. Utilization can
-be with respect to a fixed limit or a soft limit. Utilization values are
-represented as a ratio and are typically in the range `[0, 1]`, but may go above 1
-in case of exceeding a soft limit.
-
-- **time** - an instrument that measures passage of time should be called
-`entity.time`. For example, `system.cpu.time` with attribute `state = idle | user
-| system | ...`. **time** measurements are not necessarily wall time and can
-be less than or greater than the real wall time between measurements.
-
- **time** instruments are a special case of **usage** metrics, where the
- **limit** can usually be calculated as the sum of **time** over all attribute
- values. **utilization** for time instruments can be derived automatically
- using metric event timestamps. For example, `system.cpu.utilization` is
- defined as the difference in `system.cpu.time` measurements divided by the
- elapsed time and number of CPUs.
-
-- **io** - an instrument that measures bidirectional data flow should be
-called `entity.io` and have attributes for direction. For example,
-`system.network.io`.
-
-- Other instruments that do not fit the above descriptions may be named more
-freely. For example, `system.paging.faults` and `system.network.packets`.
-Units do not need to be specified in the names since they are included during
-instrument creation, but can be added if there is ambiguity.
-
### Instrument Units
**Status**: [Stable][DocumentStatus]
diff --git a/docs/general/naming.md b/docs/general/naming.md
new file mode 100644
index 0000000000..51b04cd7af
--- /dev/null
+++ b/docs/general/naming.md
@@ -0,0 +1,312 @@
+# Naming
+
+**Status**: [Stable][DocumentStatus], Unless otherwise specified.
+
+
+Table of Contents
+
+
+
+- [General Naming Considerations](#general-naming-considerations)
+- [Name Abbreviation Guidelines](#name-abbreviation-guidelines)
+- [Name Reuse Prohibition](#name-reuse-prohibition)
+- [Recommendations for OpenTelemetry Authors](#recommendations-for-opentelemetry-authors)
+- [Recommendations for Application Developers](#recommendations-for-application-developers)
+- [Attributes](#attributes)
+ - [otel.\* Namespace](#otel-namespace)
+ - [Attribute Name Pluralization Guidelines](#attribute-name-pluralization-guidelines)
+ - [Signal-specific Attributes](#signal-specific-attributes)
+- [Metrics](#metrics)
+ - [Naming Rules for Counters and UpDownCounters](#naming-rules-for-counters-and-updowncounters)
+ - [Pluralization](#pluralization)
+ - [Use `count` Instead of Pluralization for UpDownCounters](#use-count-instead-of-pluralization-for-updowncounters)
+ - [Do Not Use `total`](#do-not-use-total)
+ - [Instrument Naming](#instrument-naming)
+
+
+
+
+
+## General Naming Considerations
+
+_This section applies to attribute names (also
+known as the "attribute keys"), as well as Metric and Event names. For brevity
+within this section when we use the term "name" without an adjective it is
+implied to mean all of these._
+
+Every name MUST be a valid Unicode sequence.
+
+_Note: we merely require that the names are represented as Unicode sequences.
+This specification does not define how exactly the Unicode sequences are
+encoded. The encoding can vary from one programming language to another and from
+one wire format to another. Use the idiomatic way to represent Unicode in the
+particular programming language or wire format._
+
+Names SHOULD follow these rules:
+
+- Names SHOULD be lowercase.
+
+- Use namespacing. Delimit the namespaces using a dot character.
+ For example `service.version` denotes the service version where
+ `service` is the namespace and `version` is an attribute in that namespace.
+
+- Namespaces can be nested. For example `telemetry.sdk` is a namespace inside
+ top-level `telemetry` namespace and `telemetry.sdk.name` is an attribute
+ inside `telemetry.sdk` namespace.
+
+ Use namespaces (and dot separator) whenever it makes sense. For example
+ when introducing an attribute representing a property of some object, follow
+ `*{object}.{property}` pattern. Avoid using underscore (`*{object}_{property}`)
+ if this object could have other properties.
+
+- For each multi-word dot-delimited component of the name separate the
+ words by underscores (i.e. use snake_case). For example
+ `http.response.status_code` denotes the status code in the http namespace.
+
+ Use underscore only when using dot (namespacing) does not make sense or changes
+ the semantic meaning of the name. For example, use `rate_limiting`
+ instead of `rate.limiting`.
+
+- Be precise. Attribute, event, metric, and other names should be descriptive and
+ unambiguous.
+ - When introducing a name describing a certain property of the object,
+ include the property name. For example, use `file.owner.name` instead of `file.owner`
+ and `system.network.packet.dropped` instead of `system.network.dropped`
+ - Avoid introducing names and namespaces that would mean different things when
+ used by different conventions or instrumentations. For example, use `security_rule`
+ instead of `rule`.
+
+- Use shorter names when it does not compromise clarity. Drop namespace
+ components or words in multi-word components when they are not necessary. For example,
+ `vcs.change.id` describes pull request id as precisely as `vcs.repository.change.id` does.
+
+## Name Abbreviation Guidelines
+
+Abbreviations MAY be used when they are widely recognized and commonly used.
+
+Examples include common technical abbreviations such as `IP`, `DB`, `CPU`,
+`HTTP`, `URL`, or product names like `AWS`, `GCP`, `K8s`.
+
+Abbreviations that are commonly recognized but only within a certain domain MAY
+be used when qualified by the corresponding namespace.
+
+For example, use `container.csi.*` instead of `container.container_storage_interface`
+or `container.oci.*` instead of `container.open_container_initiative.*`
+
+Abbreviations SHOULD be avoided if they are ambiguous, for example, when they apply
+to multiple products or concepts.
+
+## Name Reuse Prohibition
+
+Two attributes, two metrics, or two events MUST NOT share the same name.
+Different entities (attribute and metric, metric and event) MAY share the same name.
+
+Attributes, metrics, and events SHOULD NOT be removed from semantic
+conventions regardless of their maturity level. When the convention is renamed or
+no longer recommended, it SHOULD be deprecated.
+
+## Recommendations for OpenTelemetry Authors
+
+- When coming up with a new semantic convention make sure to check existing
+ namespaces ([Semantic Conventions](/docs/README.md)) to see if a similar namespace
+ already exists.
+
+- All names that are part of OpenTelemetry semantic conventions SHOULD be part
+ of a namespace.
+
+- When a new namespace is necessary consider whether it should be a top-level
+ namespace (e.g. `service`) or a nested namespace (e.g. `service.instance`).
+
+- Semantic conventions MUST limit names to printable Basic Latin characters
+ (more precisely to
+ [U+0021 .. U+007E]()
+ subset of Unicode code points). It is recommended to further limit names to
+ the following Unicode code points: Latin alphabet, Numeric, Underscore, Dot
+ (as namespace delimiter).
+
+> Note:
+> Semantic Conventions tooling limits names to lowercase
+> Latin alphabet, Numeric, Underscore, Dot (as namespace delimiter).
+> Names must start with a letter, end with an alphanumeric character, and must not
+> contain two or more consecutive delimiters (Underscore or Dot).
+
+## Recommendations for Application Developers
+
+As an application developer when you need to record an attribute, metric, event, or
+other signal first consult existing [semantic conventions](./README.md).
+If an appropriate name does not exists you will need to come up with a new name.
+To do that consider a few options:
+
+- The name is specific to your company and may be possibly used outside the
+ company as well. To avoid clashes with names introduced by other companies (in
+ a distributed system that uses applications from multiple vendors) it is
+ recommended to prefix the new name by your company's reverse domain name, e.g.
+ `com.acme.shopname`.
+
+- The name is specific to your application that will be used internally only. If
+ you already have an internal company process that helps you to ensure no name
+ clashes happen then feel free to follow it. Otherwise it is recommended to
+ prefix the attribute name by your application name, provided that the
+ application name is reasonably unique within your organization (e.g.
+ `myuniquemapapp.longitude` is likely fine). Make sure the application name
+ does not clash with an existing semantic convention namespace.
+
+- It is not recommended to use existing OpenTelemetry semantic convention
+ namespace as a prefix for a new company- or application-specific attribute
+ name. Doing so may result in a name clash in the future, if OpenTelemetry
+ decides to use that same name for a different purpose or if some other third
+ party instrumentation decides to use that exact same attribute name and you
+ combine that instrumentation with your own.
+
+- The name may be generally applicable to applications in the industry. In that
+ case consider submitting a proposal to this specification to add a new name to
+ the semantic conventions, and if necessary also to add a new namespace.
+
+It is recommended to limit names to printable Basic Latin characters (more
+precisely to
+[U+0021 .. U+007E]()
+subset of Unicode code points).
+
+## Attributes
+
+### otel.\* Namespace
+
+Attribute names that start with `otel.` are reserved to be defined by
+OpenTelemetry specification. These are typically used to express OpenTelemetry
+concepts in formats that don't have a corresponding concept.
+
+For example, the `otel.scope.name` attribute is used to record the
+instrumentation scope name, which is an OpenTelemetry concept that is natively
+represented in OTLP, but does not have an equivalent in other telemetry formats
+and protocols.
+
+Any additions to the `otel.*` namespace MUST be approved as part of
+OpenTelemetry specification.
+
+### Attribute Name Pluralization Guidelines
+
+- When an attribute represents a single entity, the attribute name SHOULD be
+ singular. Examples: `host.name`, `container.id`.
+
+- When attribute can represent multiple entities, the attribute name SHOULD be
+ pluralized and the value type SHOULD be an array. E.g. `process.command_args`
+ might include multiple values: the executable name and command arguments.
+
+- When an attribute represents a measurement,
+ [Metric Name Pluralization Guidelines](./metrics.md#pluralization) SHOULD be
+ followed for the attribute name.
+
+### Signal-specific Attributes
+
+**Status**: [Experimental][DocumentStatus]
+
+Attributes are defined in semantic conventions in a signal-agnostic way. The same attribute
+is expected to be used on multiple signals.
+
+When an attribute is defined, it is not always clear if it will be applicable outside
+of a certain metric, event, or other convention.
+
+Attributes that are unlikely to have any usage beyond a specific convention,
+SHOULD be added under that metric (event, etc) namespace.
+
+Examples:
+
+Attributes `mode` and `mountpoint` for metric `system.filesystem.usage`
+should be namespaced as `system.filesystem.mode` and `system.filesystem.mountpoint`.
+
+Metrics, events, resources, and other signals are expected and encouraged to use
+applicable attributes from multiple namespaces.
+
+Examples:
+
+Metric `http.server.request.duration` uses attributes from the registry such as
+`server.port`, `error.type`.
+
+## Metrics
+
+**Status**: [Experimental][DocumentStatus]
+
+### Naming Rules for Counters and UpDownCounters
+
+#### Pluralization
+
+Metric namespaces SHOULD NOT be pluralized.
+
+Metric names SHOULD NOT be pluralized, unless the value being recorded
+represents discrete instances of a
+[countable quantity](https://wikipedia.org/wiki/Count_noun).
+Generally, the name SHOULD be pluralized only if the unit of the metric in
+question is a non-unit (like `{fault}` or `{operation}`).
+
+Examples:
+
+* `system.filesystem.utilization`, `http.server.request.duration`, and `system.cpu.time`
+should not be pluralized, even if many data points are recorded.
+* `system.paging.faults`, `system.disk.operations`, and `system.network.packets`
+should be pluralized, even if only a single data point is recorded.
+
+#### Use `count` Instead of Pluralization for UpDownCounters
+
+If the value being recorded represents the count of concepts signified
+by the namespace then the metric should be named `count` (within its namespace).
+
+For example if we have a namespace `system.process` which contains all metrics related
+to the processes then to represent the count of the processes we can have a metric named
+`system.process.count`.
+
+#### Do Not Use `total`
+
+UpDownCounters SHOULD NOT use `_total` because then they will look like
+monotonic sums.
+
+Counters SHOULD NOT append `_total` either because then their meaning will
+be confusing in delta backends.
+
+### Instrument Naming
+
+**Status**: [Experimental][DocumentStatus]
+
+- **limit** - an instrument that measures the constant, known total amount of
+something should be called `entity.limit`. For example, `system.memory.limit`
+for the total amount of memory on a system.
+
+- **usage** - an instrument that measures an amount used out of a known total
+(**limit**) amount should be called `entity.usage`. For example,
+`system.memory.usage` with attribute `state = used | cached | free | ...` for the
+amount of memory in a each state. Where appropriate, the sum of **usage**
+over all attribute values SHOULD be equal to the **limit**.
+
+ A measure of the amount consumed of an unlimited resource, or of a resource
+ whose limit is unknowable, is differentiated from **usage**. For example, the
+ maximum possible amount of virtual memory that a process may consume may
+ fluctuate over time and is not typically known.
+
+- **utilization** - an instrument that measures the _fraction_ of **usage**
+out of its **limit** should be called `entity.utilization`. For example,
+`system.memory.utilization` for the fraction of memory in use. Utilization can
+be with respect to a fixed limit or a soft limit. Utilization values are
+represented as a ratio and are typically in the range `[0, 1]`, but may go above 1
+in case of exceeding a soft limit.
+
+- **time** - an instrument that measures passage of time should be called
+`entity.time`. For example, `system.cpu.time` with attribute `state = idle | user
+| system | ...`. **time** measurements are not necessarily wall time and can
+be less than or greater than the real wall time between measurements.
+
+ **time** instruments are a special case of **usage** metrics, where the
+ **limit** can usually be calculated as the sum of **time** over all attribute
+ values. **utilization** for time instruments can be derived automatically
+ using metric event timestamps. For example, `system.cpu.utilization` is
+ defined as the difference in `system.cpu.time` measurements divided by the
+ elapsed time and number of CPUs.
+
+- **io** - an instrument that measures bidirectional data flow should be
+called `entity.io` and have attributes for direction. For example,
+`system.network.io`.
+
+- Other instruments that do not fit the above descriptions may be named more
+freely. For example, `system.paging.faults` and `system.network.packets`.
+Units do not need to be specified in the names since they are included during
+instrument creation, but can be added if there is ambiguity.
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
diff --git a/docs/system/README.md b/docs/system/README.md
index dc6b643b5d..61c332a22b 100644
--- a/docs/system/README.md
+++ b/docs/system/README.md
@@ -14,6 +14,8 @@ This document defines semantic conventions for systems (such as processes, runti
System semantic conventions are defined for the following metrics:
* [System](system-metrics.md): For standard system metrics.
+* [Container](container-metrics.md): For container-related metrics.
+* [K8s](k8s-metrics.md): For K8s-related metrics.
* [Hardware](hardware-metrics.md): For hardware-related metrics.
* [Process](process-metrics.md): For standard process metrics.
* [Runtime Environment](/docs/runtime/README.md#metrics): For runtime environment metrics.
diff --git a/model/README.md b/model/README.md
index ce6fb75e93..821423416e 100644
--- a/model/README.md
+++ b/model/README.md
@@ -10,7 +10,7 @@ the generated markdown output in the [docs](../docs/README.md) folder.
## Writing semantic conventions
Semantic conventions for the spec MUST adhere to the
-[attribute naming](../docs/general/attribute-naming.md),
+[naming](../docs/general/naming.md),
[attribute requirement level](../docs/general/attribute-requirement-level.md),
and [metric requirement level](../docs/general/metric-requirement-level.md) conventions.
diff --git a/templates/registry/markdown/readme.md.j2 b/templates/registry/markdown/readme.md.j2
index 14438da535..1767f38b2e 100644
--- a/templates/registry/markdown/readme.md.j2
+++ b/templates/registry/markdown/readme.md.j2
@@ -36,5 +36,5 @@ Currently, the following namespaces exist:
{%- set my_file_name = bundle.id | kebab_case ~ ".md" -%}
- [{{ bundle.id | title_case | acronym }}]({{ my_file_name }})
{% endfor %}
-[developers recommendations]: ../general/attribute-naming.md#recommendations-for-application-developers
+[developers recommendations]: ../general/naming.md#recommendations-for-application-developers