Format with prettier

docs/general/attribute-naming.md

@@ -11,7 +11,7 @@
 - [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)
+- [otel.\* Namespace](#otel-namespace)
 
 <!-- tocstop -->
 
@@ -37,15 +37,15 @@ Names SHOULD follow these rules:
 
 - 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.
+  inside `telemetry.sdk` namespace. Note: the fact that an entity is located
-  Note: the fact that an entity is located within another entity is typically
+  within another entity is typically not a sufficient reason for forming nested
-  not a sufficient reason for forming nested namespaces. The purpose of a
+  namespaces. The purpose of a namespace is to avoid name clashes, not to
-  namespace is to avoid name clashes, not to indicate entity hierarchies. This
+  indicate entity hierarchies. This purpose should primarily drive the decision
-  purpose should primarily drive the decision about forming nested namespaces.
+  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`
+  words by underscores (i.e. use snake_case). For example
-  denotes the status code in the http namespace.
+  `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
@@ -57,16 +57,16 @@ Names SHOULD follow these rules:
 
 ## Name Pluralization guidelines
 
-- When an attribute represents a single entity, the attribute name SHOULD be singular.
+- When an attribute represents a single entity, the attribute name SHOULD be
-  Examples: `host.name`, `db.user`, `container.id`.
+  singular. Examples: `host.name`, `db.user`, `container.id`.
 
-- When attribute can represent multiple entities, the attribute name SHOULD be pluralized
+- When attribute can represent multiple entities, the attribute name SHOULD be
-  and the value type SHOULD be an array. E.g. `process.command_args` might include multiple
+  pluralized and the value type SHOULD be an array. E.g. `process.command_args`
-  values: the executable name and command arguments.
+  might include multiple values: the executable name and command arguments.
 
 - When an attribute represents a measurement,
-  [Metric Name Pluralization Guidelines](./metrics.md#pluralization)
+  [Metric Name Pluralization Guidelines](./metrics.md#pluralization) SHOULD be
-  SHOULD be followed for the attribute name.
+  followed for the attribute name.
 
 ## Name Reuse Prohibition
 
@@ -83,8 +83,7 @@ denote old attribute names in rename operations).
   of a namespace.
 
 - When coming up with a new semantic convention make sure to check existing
-  namespaces ([Semantic Conventions](./README.md))
+  namespaces ([Semantic Conventions](./README.md)) to see if the new name fits.
-  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`).
@@ -92,14 +91,14 @@ denote old attribute names in rename operations).
 - 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
+  identical meanings. For example the `http.request.method` span attribute name
-  exactly the same concept as the `http.request.method` metric attribute, has the same
+  denotes exactly the same concept as the `http.request.method` metric
-  data type and the same set of possible values (in both cases it records the
+  attribute, has the same data type and the same set of possible values (in both
-  value of the HTTP protocol's request method as a string).
+  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](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters)
+  [U+0021 .. U+007E](<https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters>)
   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).
@@ -107,9 +106,9 @@ denote old attribute names in rename operations).
 ## Recommendations for Application Developers
 
 As an application developer when you need to record an attribute first consult
-existing [semantic conventions](./README.md).
+existing [semantic conventions](./README.md). If an appropriate name does not
-If an appropriate name does not exists you will need to come up with a new name.
+exists you will need to come up with a new name. To do that consider a few
-To do that consider a few options:
+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
@@ -120,28 +119,28 @@ To do that consider a few options:
 - 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
+  prefix the attribute name by your application name, provided that the
-  the application name is reasonably unique within your organization (e.g.
+  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
+- It is not recommended to use existing OpenTelemetry semantic convention
-  as a prefix for a new company- or application-specific attribute name. Doing so
+  namespace as a prefix for a new company- or application-specific attribute
-  may result in a name clash in the future, if OpenTelemetry decides to use that
+  name. Doing so may result in a name clash in the future, if OpenTelemetry
-  same name for a different purpose or if some other third party instrumentation
+  decides to use that same name for a different purpose or if some other third
-  decides to use that exact same attribute name and you combine that instrumentation
+  party instrumentation decides to use that exact same attribute name and you
-  with your own.
+  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
+It is recommended to limit names to printable Basic Latin characters (more
-(more precisely to
+precisely to
-[U+0021 .. U+007E](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters)
+[U+0021 .. U+007E](<https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters>)
 subset of Unicode code points).
 
-## otel.* Namespace
+## otel.\* Namespace
 
 Attribute names that start with `otel.` are reserved to be defined by
 OpenTelemetry specification. These are typically used to express OpenTelemetry
@@ -155,4 +154,5 @@ and protocols.
 Any additions to the `otel.*` namespace MUST be approved as part of
 OpenTelemetry specification.
 
-[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
+[DocumentStatus]:
+  https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md

docs/general/attribute-requirement-level.md

@@ -17,9 +17,11 @@
 
 </details>
 
-_This section applies to Log, Metric, Resource, and Span, and describes requirement levels for attributes defined in semantic conventions._
+_This section applies to Log, Metric, Resource, and Span, and describes
+requirement levels for attributes defined in semantic conventions._
 
-Attribute requirement levels apply to the [instrumentation library](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/glossary.md#instrumentation-library).
+Attribute requirement levels apply to the
+[instrumentation library](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/glossary.md#instrumentation-library).
 
 The following attribute requirement levels are specified:
 
@@ -28,51 +30,98 @@ The following attribute requirement levels are specified:
 - [Recommended](#recommended)
 - [Opt-In](#opt-in)
 
-The requirement level for an attribute is specified by semantic conventions depending on attribute availability across instrumented entities, performance, security, and other factors. When specifying requirement levels, a semantic convention MUST take into account signal-specific requirements.
+The requirement level for an attribute is specified by semantic conventions
+depending on attribute availability across instrumented entities, performance,
+security, and other factors. When specifying requirement levels, a semantic
+convention MUST take into account signal-specific requirements.
 
-For example, Metric attributes that may have high cardinality can only be defined with `Opt-In` level.
+For example, Metric attributes that may have high cardinality can only be
+defined with `Opt-In` level.
 
-A semantic convention that refers to an attribute from another semantic convention MAY modify the requirement level within its own scope. Otherwise, requirement level from the referred semantic convention applies.
+A semantic convention that refers to an attribute from another semantic
+convention MAY modify the requirement level within its own scope. Otherwise,
+requirement level from the referred semantic convention applies.
 
 <!-- TODO(jsuereth) - make examples not break on changes to semconv -->
-For example, [Database semantic convention](../database/README.md) references `network.transport` attribute defined in [General attributes](./README.md) with `Conditionally Required` level on it.
+
+For example, [Database semantic convention](../database/README.md) references
+`network.transport` attribute defined in [General attributes](./README.md) with
+`Conditionally Required` level on it.
 
 ## Required
 
-All instrumentations MUST populate the attribute. A semantic convention defining a Required attribute expects an absolute majority of instrumentation libraries and applications are able to efficiently retrieve and populate it, and can additionally meet requirements for cardinality, security, and any others specific to the signal defined by the convention. `http.request.method` is an example of a Required attribute.
+All instrumentations MUST populate the attribute. A semantic convention defining
+a Required attribute expects an absolute majority of instrumentation libraries
+and applications are able to efficiently retrieve and populate it, and can
+additionally meet requirements for cardinality, security, and any others
+specific to the signal defined by the convention. `http.request.method` is an
+example of a Required attribute.
 
-_Note: Consumers of telemetry can detect if a telemetry item follows a specific semantic convention by checking for the presence of a `Required` attribute defined by such convention. For example, the presence of the `db.system` attribute on a span can be used as an indication that the span follows database semantics._
+_Note: Consumers of telemetry can detect if a telemetry item follows a specific
+semantic convention by checking for the presence of a `Required` attribute
+defined by such convention. For example, the presence of the `db.system`
+attribute on a span can be used as an indication that the span follows database
+semantics._
 
 ## Conditionally Required
 
-All instrumentations MUST populate the attribute when the given condition is satisfied. The semantic convention of a `Conditionally Required` attribute MUST clarify the condition under which the attribute is to be populated.
+All instrumentations MUST populate the attribute when the given condition is
+satisfied. The semantic convention of a `Conditionally Required` attribute MUST
+clarify the condition under which the attribute is to be populated.
 
-`http.route` is an example of a conditionally required attribute that is populated when the instrumented HTTP framework provides route information for the instrumented request. Some low-level HTTP server implementations do not support routing and corresponding instrumentations can't populate the attribute.
+`http.route` is an example of a conditionally required attribute that is
+populated when the instrumented HTTP framework provides route information for
+the instrumented request. Some low-level HTTP server implementations do not
+support routing and corresponding instrumentations can't populate the attribute.
 
-When a `Conditionally Required` attribute's condition is not satisfied, and there is no requirement to populate the attribute, semantic conventions MAY provide special instructions on how to handle it. If no instructions are given and if instrumentation can populate the attribute, instrumentation SHOULD use the `Opt-In` requirement level on the attribute.
+When a `Conditionally Required` attribute's condition is not satisfied, and
+there is no requirement to populate the attribute, semantic conventions MAY
+provide special instructions on how to handle it. If no instructions are given
+and if instrumentation can populate the attribute, instrumentation SHOULD use
+the `Opt-In` requirement level on the attribute.
 
 <!-- TODO(jsuereth) - make examples not break on changes to semconv -->
-For example, `server.address` is `Conditionally Required` by the [Database convention](../database/README.md) when available. When `network.peer.address` is available instead, instrumentation can do a DNS lookup, cache and populate `server.address`, but only if the user explicitly enables the instrumentation to do so, considering the performance issues that DNS lookups introduce.
+
+For example, `server.address` is `Conditionally Required` by the
+[Database convention](../database/README.md) when available. When
+`network.peer.address` is available instead, instrumentation can do a DNS
+lookup, cache and populate `server.address`, but only if the user explicitly
+enables the instrumentation to do so, considering the performance issues that
+DNS lookups introduce.
 
 ## Recommended
 
-Instrumentations SHOULD add the attribute by default if it's readily available and can be [efficiently populated](#performance-suggestions). Instrumentations MAY offer a configuration option to disable Recommended attributes.
+Instrumentations SHOULD add the attribute by default if it's readily available
+and can be [efficiently populated](#performance-suggestions). Instrumentations
+MAY offer a configuration option to disable Recommended attributes.
 
-Instrumentations that decide not to populate `Recommended` attributes due to [performance](#performance-suggestions), security, privacy, or other consideration by default, SHOULD allow for users to
+Instrumentations that decide not to populate `Recommended` attributes due to
-opt-in to emit them as defined for the `Opt-In` requirement level (if the attributes are logically applicable).
+[performance](#performance-suggestions), security, privacy, or other
+consideration by default, SHOULD allow for users to opt-in to emit them as
+defined for the `Opt-In` requirement level (if the attributes are logically
+applicable).
 
 ## Opt-In
 
-Instrumentations SHOULD populate the attribute if and only if the user configures the instrumentation to do so. Instrumentation that doesn't support configuration MUST NOT populate `Opt-In` attributes.
+Instrumentations SHOULD populate the attribute if and only if the user
+configures the instrumentation to do so. Instrumentation that doesn't support
+configuration MUST NOT populate `Opt-In` attributes.
 
-This attribute requirement level is recommended for attributes that are particularly expensive to retrieve or might pose a security or privacy risk. These should therefore only be enabled explicitly by a user making an informed decision.
+This attribute requirement level is recommended for attributes that are
+particularly expensive to retrieve or might pose a security or privacy risk.
+These should therefore only be enabled explicitly by a user making an informed
+decision.
 
 ## Performance suggestions
 
 Here are several examples of expensive operations to be avoided by default:
 
-- DNS lookups to populate `server.address` when only an IP address is available to the instrumentation. Caching lookup results does not solve the issue for all possible cases and should be avoided by default too.
+- DNS lookups to populate `server.address` when only an IP address is available
+  to the instrumentation. Caching lookup results does not solve the issue for
+  all possible cases and should be avoided by default too.
 - forcing an `http.route` calculation before the HTTP framework calculates it
-- reading response stream to find `http.response.body.size` when `Content-Length` header is not available
+- reading response stream to find `http.response.body.size` when
+  `Content-Length` header is not available
 
-[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
+[DocumentStatus]:
+  https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md