linters

semantic_conventions/README.md

@@ -15,7 +15,7 @@ i.e.:
 ## Writing semantic conventions
 
 Semantic conventions for the spec MUST adhere to the
-[attribute naming conventions](../specification/common/attribute-naming.md).
+[attribute naming](../specification/common/attribute-naming.md) and [requirement level](../specification/common/attribute-requirement-level.md) conventions.
 
 Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.11.0/semantic-conventions/syntax.md)
 for how to write the YAML files for semantic conventions and what the YAML properties mean.

semantic_conventions/trace/http.yaml

@@ -88,19 +88,16 @@ groups:
       - ref: net.peer.name
         required: always
         sampling_relevant: true
-        note: >
+        note: |
           Best known HTTP remote hostname is identified according with the following order:
 
-
           - Host header
-
           - Host component of the absolute [Request-URL](https://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html)
 
-
           MUST NOT be set if capturing it would require an extra DNS lookup.
       - ref: net.peer.port
         required:
-          conditional: if not default (`80` for `http`` scheme, `443` for `https`).
+          conditional: if not default (`80` for `http` scheme, `443` for `https`).
         sampling_relevant: true
       - id: retry_count
         type: int
@@ -126,14 +123,11 @@ groups:
         required: always
         sampling_relevant: true
         brief: The best known HTTP server name, see note below
-        note: >
+        note: |
           Best known HTTP server name is identified according with the following order:
 
-
           - The primary server name of the matched virtual host. This should be obtained via configuration.
-
           - `Host` header
-
           - Host component of the absolute [Request-URL](https://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html)
       - ref: net.host.port
         required:
@@ -152,7 +146,7 @@ groups:
         brief: >
             The matched route (path template in the format used by the respective server framework). See note below
         examples: ['/users/:userID?', '{controller}/{action}/{id?}']
-        note: > 
+        note: >
           'http.route' MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
       - id: client_ip
         type: string
@@ -174,4 +168,4 @@ groups:
         examples: '83.164.160.102'
       - ref: net.peer.port
       - ref: net.host.ip
-        required: opt-in
+        required: opt-in

specification/common/README.md

@@ -51,6 +51,8 @@ both containing an array of strings to represent a mapping
 
 See [Attribute Naming](attribute-naming.md) for naming guidelines.
 
+See [Requirement Level](attribute-requirement-level.md) for requirement levels guidelines.
+
 See [this document](attribute-type-mapping.md) to find out how to map values obtained
 outside OpenTelemetry into OpenTelemetry attribute values.
 

specification/common/attribute-requirement-level.md

@@ -6,8 +6,9 @@
 <summary>Table of Contents</summary>
 
 <!-- toc -->
-- [Attribute Requirement Level](#attribute-requirement-level)
-  - [Performance considerations](#performance-considerations)
+
+- [Performance considerations](#performance-considerations)
+
 <!-- tocstop -->
 
 </details>

specification/trace/semantic_conventions/http.md

@@ -10,6 +10,19 @@ and various HTTP versions like 1.1, 2 and SPDY.
 
 <!-- toc -->
 
+- [Name](#name)
+- [Status](#status)
+- [Common Attributes](#common-attributes)
+  * [HTTP request and response headers](#http-request-and-response-headers)
+- [HTTP client](#http-client)
+  * [HTTP request retries and redirects](#http-request-retries-and-redirects)
+- [HTTP server](#http-server)
+  * [HTTP server definitions](#http-server-definitions)
+  * [HTTP Server semantic conventions](#http-server-semantic-conventions)
+- [HTTP client-server example](#http-client-server-example)
+- [HTTP retries examples](#http-retries-examples)
+- [HTTP redirects examples](#http-redirects-examples)
+
 <!-- tocstop -->
 
 ## Name
@@ -106,7 +119,7 @@ before any HTTP-redirects that may happen when executing the request.
 | `http.url` | string | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | Yes |
 | `http.retry_count` | int | The ordinal number of request re-sending attempt. | `3` | Recommended if and only if request was retried. |
 | [`net.peer.name`](span-general.md) | string | Remote hostname or similar, see note below. [2] | `example.com` | Yes |
-| [`net.peer.port`](span-general.md) | int | Remote port number. | `80`; `8080`; `443` | Required if not default. |
+| [`net.peer.port`](span-general.md) | int | Remote port number. | `80`; `8080`; `443` | Required conditionally [3] |
 
 **[1]:** `http.url` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case the attribute's value should be `https://www.example.com/`.
 
@@ -117,6 +130,8 @@ before any HTTP-redirects that may happen when executing the request.
 
 MUST NOT be set if capturing it would require an extra DNS lookup.
 
+**[3]:** if not default (`80` for `http` scheme, `443` for `https`).
+
 Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions:
 
 * `http.url`