Sort attribute tables by requirement level and attribute name (#260)

Co-authored-by: Liudmila Molkova <limolkova@microsoft.com>

semantic-conventions/CHANGELOG.md

@@ -18,6 +18,8 @@ Please update the changelog as part of any significant pull request.
   ([#271](https://github.com/open-telemetry/build-tools/pull/271))
 - Add link to requirement levels definition from Markdown table title.
   ([#222](https://github.com/open-telemetry/build-tools/pull/222))
+- Sort attribute tables by requirement level and attribute name
+  ([#260](https://github.com/open-telemetry/build-tools/pull/260))
 
 ## v0.23.0
 

semantic-conventions/src/opentelemetry/semconv/model/semantic_convention.py

@@ -24,6 +24,7 @@
 from opentelemetry.semconv.model.exceptions import ValidationError
 from opentelemetry.semconv.model.semantic_attribute import (
     AttributeType,
+    RequirementLevel,
     SemanticAttribute,
 )
 from opentelemetry.semconv.model.unit_member import UnitMember
@@ -125,14 +126,19 @@ def _get_attributes(self, templates: Optional[bool]):
         if not hasattr(self, "attrs_by_name"):
             return []
 
+        def comparison_key(attr):
+            if attr.requirement_level:
+                return attr.requirement_level.value, attr.fqn
+            return RequirementLevel.RECOMMENDED.value, attr.fqn
+
         return sorted(
             [
                 attr
                 for attr in self.attrs_by_name.values()
                 if templates is None
                 or templates == AttributeType.is_template_type(attr.attr_type)
             ],
-            key=lambda attr: attr.fqn,
+            key=comparison_key,
         )
 
     def __init__(self, group, strict_validation=True):

semantic-conventions/src/tests/data/markdown/attribute_group/expected.md

@@ -3,6 +3,6 @@
 <!-- semconv span_attribute_group -->
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
-| `foo.bar` | string | Attribute 1 | `baz` | `Recommended` if available | Experimental |
 | `foo.qux` | int | Attribute 2 | `42` | `Conditionally Required` if available | Experimental |
+| `foo.bar` | string | Attribute 1 | `baz` | `Recommended` if available | Experimental |
 <!-- endsemconv -->

semantic-conventions/src/tests/data/markdown/attribute_templates/expected.md

@@ -3,8 +3,8 @@
 <!-- semconv custom_http(full) -->
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
-| `custom_http.request.header.<key>` | string[] | HTTP request headers, `<key>` being the normalized HTTP Header name (lowercase, with - characters replaced by _), the value being the header values. | ``http.request.header.content_type=["application/json"]`` | `Recommended` | Experimental |
 | `custom_http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | Experimental |
+| `custom_http.request.header.<key>` | string[] | HTTP request headers, `<key>` being the normalized HTTP Header name (lowercase, with - characters replaced by _), the value being the header values. | ``http.request.header.content_type=["application/json"]`` | `Recommended` | Experimental |
 | `general.some_general_attribute.<key>` | string | This is a general attribute. | ``some_general_attribute.some_key="abc"`` | `Recommended` | Experimental |
 | `referenced_http.request.referenced.header.<key>` | string[] | This is a referenced attribute. | ``http.request.header.content_type=["application/json"]`` | `Recommended` | Experimental |
 <!-- endsemconv -->

semantic-conventions/src/tests/data/markdown/deprecated/expected.md

@@ -4,11 +4,11 @@
 <!-- semconv http -->
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
+| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | Experimental |
+| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` if and only if one was received/sent | Experimental |
 | `http.flavor` | string | Kind of HTTP protocol used [1] | `1.0` | `Recommended` | Deprecated: Use attribute `flavor_new` instead. |
 | `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | `Recommended` | Experimental |
-| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | Experimental |
 | `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | `Recommended` | Experimental |
-| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` if and only if one was received/sent | Experimental |
 | `http.status_text` | string | [HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). | `OK` | `Recommended` | Deprecated: Use attribute `status_description` instead. |
 | `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | `Recommended` | Experimental |
 | `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. | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | `Recommended` | Experimental |

semantic-conventions/src/tests/data/markdown/extend_constraint/expected.md

@@ -36,19 +36,19 @@ Some database systems may allow a connection to switch to a different `db.user`,
 <!-- semconv db(tag=connection-level) -->
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
-| `db.connection_string` | string | The connection string used to connect to the database. [1] | `Server=(localdb)\v11.0;Integrated Security=true;` | `Recommended` | Experimental |
 | `db.system` | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | `Required` | Experimental |
+| `net.peer.port` | int | Remote port number. | `80`; `8080`; `443` | `Conditionally Required` [1] | Experimental |
+| `net.transport` | string | Transport protocol used. See note below. | `IP.TCP` | `Conditionally Required` [2] | Experimental |
+| `db.connection_string` | string | The connection string used to connect to the database. [3] | `Server=(localdb)\v11.0;Integrated Security=true;` | `Recommended` | Experimental |
 | `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | `Recommended` | Experimental |
 | `net.peer.ip` | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | See below | Experimental |
 | `net.peer.name` | string | Remote hostname or similar, see note below. | `example.com` | See below | Experimental |
-| `net.peer.port` | int | Remote port number. | `80`; `8080`; `443` | `Conditionally Required` [2] | Experimental |
-| `net.transport` | string | Transport protocol used. See note below. | `IP.TCP` | `Conditionally Required` [3] | Experimental |
 
-**[1]:** It is recommended to remove embedded credentials.
+**[1]:** if using a port other than the default port for this DBMS.
 
-**[2]:** if using a port other than the default port for this DBMS.
+**[2]:** Recommended in general, required for in-process databases (`"inproc"`).
 
-**[3]:** Recommended in general, required for in-process databases (`"inproc"`).
+**[3]:** It is recommended to remove embedded credentials.
 
 **Additional attribute requirements:** At least one of the following sets of attributes is required:
 

semantic-conventions/src/tests/data/markdown/include/expected.md

@@ -3,28 +3,28 @@
 <!-- semconv faas.http(full) -->
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
-| `faas.execution` | string | The execution id of the current function execution. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | `Recommended` | Experimental |
 | `faas.trigger` | string | Type of the trigger on which the function is executed. | `datasource` | `Required` | Experimental |
-| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | See below | Experimental |
 | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | Experimental |
+| [`http.server_name`](input_http.md) | string | The primary server name of the matched virtual host. [1] | `example.com` | `Conditionally Required` [2] | Experimental |
+| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` if and only if one was received/sent | Experimental |
+| `faas.execution` | string | The execution id of the current function execution. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | `Recommended` | Experimental |
+| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | See below | Experimental |
 | `http.recommended_attribute` | string | brief | `foo` | `Recommended` short note | Experimental |
-| `http.recommended_attribute_long_note` | string | brief | `bar` | `Recommended` [1] | Experimental |
+| `http.recommended_attribute_long_note` | string | brief | `bar` | `Recommended` [3] | Experimental |
 | `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | See below | Experimental |
-| [`http.server_name`](input_http.md) | string | The primary server name of the matched virtual host. [2] | `example.com` | `Conditionally Required` [3] | Experimental |
-| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` if and only if one was received/sent | Experimental |
 | `http.status_text` | string | [HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). | `OK` | `Recommended` | Experimental |
 | `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | See below | Experimental |
 | `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. | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | See below | Experimental |
 | `http.user_agent` | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | `Recommended` | Experimental |
 
-**[1]:** some very long note that should be written under the semconv table
-
-**[2]:** This is an example
+**[1]:** This is an example
 
 - of note
 - with list
 
-**[3]:** This should be obtained via configuration. If this attribute can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead).
+**[2]:** This should be obtained via configuration. If this attribute can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead).
+
+**[3]:** some very long note that should be written under the semconv table
 
 **Additional attribute requirements:** At least one of the following sets of attributes is required:
 

semantic-conventions/src/tests/data/markdown/multiple/expected.md

@@ -4,10 +4,10 @@
 <!-- semconv http -->
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
-| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | `Recommended` | Experimental |
 | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | Experimental |
-| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | `Recommended` | Experimental |
 | `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` if and only if one was received/sent | Experimental |
+| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | `Recommended` | Experimental |
+| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | `Recommended` | Experimental |
 | `http.status_text` | string | [HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). | `OK` | `Recommended` | Experimental |
 | `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | `Recommended` | Experimental |
 | `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. | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | `Recommended` | Experimental |
@@ -17,10 +17,10 @@
 <!-- semconv http -->
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
-| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | `Recommended` | Experimental |
 | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | Experimental |
-| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | `Recommended` | Experimental |
 | `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` if and only if one was received/sent | Experimental |
+| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | `Recommended` | Experimental |
+| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | `Recommended` | Experimental |
 | `http.status_text` | string | [HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). | `OK` | `Recommended` | Experimental |
 | `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | `Recommended` | Experimental |
 | `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. | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | `Recommended` | Experimental |

semantic-conventions/src/tests/data/markdown/parameter_full/expected.md

@@ -3,25 +3,25 @@
 <!-- semconv faas.http(full) -->
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
-| `faas.execution` | string | The execution id of the current function execution. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | `Recommended` | Experimental |
 | `faas.trigger` | string | Type of the trigger on which the function is executed. | `datasource` | `Required` | Experimental |
-| [`http.client_ip`](http.md) | string | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). [1] | `83.164.160.102` | `Recommended` | Experimental |
-| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | `Conditionally Required` <condition> | Experimental |
 | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | Experimental |
+| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | `Conditionally Required` <condition> | Experimental |
+| [`http.server_name`](http.md) | string | The primary server name of the matched virtual host. [1] | `example.com` | `Conditionally Required` [2] | Experimental |
+| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` if and only if one was received/sent. | Experimental |
+| `faas.execution` | string | The execution id of the current function execution. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | `Recommended` | Experimental |
+| [`http.client_ip`](http.md) | string | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). [3] | `83.164.160.102` | `Recommended` | Experimental |
 | [`http.route`](http.md) | string | The matched route (path template). | `/users/:userID?` | `Recommended` | Experimental |
 | `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | See below | Experimental |
-| [`http.server_name`](http.md) | string | The primary server name of the matched virtual host. [2] | `example.com` | `Conditionally Required` [3] | Experimental |
-| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` if and only if one was received/sent. | Experimental |
 | `http.status_text` | string | [HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). | `OK` | `Recommended` | Experimental |
 | `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | See below | Experimental |
 | `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. | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | See below | Experimental |
 | `http.user_agent` | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | `Recommended` | Experimental |
 
-**[1]:** This is not necessarily the same as `net.peer.ip`, which would identify the network-level peer, which may be a proxy.
+**[1]:** http.url is usually not readily available on the server side but would have to be assembled in a cumbersome and sometimes lossy process from other information (see e.g. open-telemetry/opentelemetry-python/pull/148). It is thus preferred to supply the raw data that is available.
 
-**[2]:** http.url is usually not readily available on the server side but would have to be assembled in a cumbersome and sometimes lossy process from other information (see e.g. open-telemetry/opentelemetry-python/pull/148). It is thus preferred to supply the raw data that is available.
+**[2]:** This should be obtained via configuration. If this attribute can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead).
 
-**[3]:** This should be obtained via configuration. If this attribute can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead).
+**[3]:** This is not necessarily the same as `net.peer.ip`, which would identify the network-level peer, which may be a proxy.
 
 **Additional attribute requirements:** At least one of the following sets of attributes is required: