diff --git a/semantic-conventions/CHANGELOG.md b/semantic-conventions/CHANGELOG.md index b919527b..269a0cf5 100644 --- a/semantic-conventions/CHANGELOG.md +++ b/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 diff --git a/semantic-conventions/src/opentelemetry/semconv/model/semantic_convention.py b/semantic-conventions/src/opentelemetry/semconv/model/semantic_convention.py index 932cd578..54ed5c58 100644 --- a/semantic-conventions/src/opentelemetry/semconv/model/semantic_convention.py +++ b/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,6 +126,11 @@ 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 @@ -132,7 +138,7 @@ def _get_attributes(self, templates: Optional[bool]): 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): diff --git a/semantic-conventions/src/tests/data/markdown/attribute_group/expected.md b/semantic-conventions/src/tests/data/markdown/attribute_group/expected.md index 09b038e6..e0f847c6 100644 --- a/semantic-conventions/src/tests/data/markdown/attribute_group/expected.md +++ b/semantic-conventions/src/tests/data/markdown/attribute_group/expected.md @@ -3,6 +3,6 @@ | 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 | diff --git a/semantic-conventions/src/tests/data/markdown/attribute_templates/expected.md b/semantic-conventions/src/tests/data/markdown/attribute_templates/expected.md index 41599ce8..c0865815 100644 --- a/semantic-conventions/src/tests/data/markdown/attribute_templates/expected.md +++ b/semantic-conventions/src/tests/data/markdown/attribute_templates/expected.md @@ -3,8 +3,8 @@ | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| `custom_http.request.header.` | string[] | HTTP request headers, `` 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.` | string[] | HTTP request headers, `` 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.` | string | This is a general attribute. | ``some_general_attribute.some_key="abc"`` | `Recommended` | Experimental | | `referenced_http.request.referenced.header.` | string[] | This is a referenced attribute. | ``http.request.header.content_type=["application/json"]`` | `Recommended` | Experimental | diff --git a/semantic-conventions/src/tests/data/markdown/deprecated/expected.md b/semantic-conventions/src/tests/data/markdown/deprecated/expected.md index aac840f0..215a7d4a 100644 --- a/semantic-conventions/src/tests/data/markdown/deprecated/expected.md +++ b/semantic-conventions/src/tests/data/markdown/deprecated/expected.md @@ -4,11 +4,11 @@ | 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 | diff --git a/semantic-conventions/src/tests/data/markdown/extend_constraint/expected.md b/semantic-conventions/src/tests/data/markdown/extend_constraint/expected.md index efa11282..d80bddae 100644 --- a/semantic-conventions/src/tests/data/markdown/extend_constraint/expected.md +++ b/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`, | 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: diff --git a/semantic-conventions/src/tests/data/markdown/include/expected.md b/semantic-conventions/src/tests/data/markdown/include/expected.md index 331d979f..b0462419 100644 --- a/semantic-conventions/src/tests/data/markdown/include/expected.md +++ b/semantic-conventions/src/tests/data/markdown/include/expected.md @@ -3,28 +3,28 @@ | 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: diff --git a/semantic-conventions/src/tests/data/markdown/multiple/expected.md b/semantic-conventions/src/tests/data/markdown/multiple/expected.md index 8eacf0fa..3f8c1196 100644 --- a/semantic-conventions/src/tests/data/markdown/multiple/expected.md +++ b/semantic-conventions/src/tests/data/markdown/multiple/expected.md @@ -4,10 +4,10 @@ | 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 @@ | 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 | diff --git a/semantic-conventions/src/tests/data/markdown/parameter_full/expected.md b/semantic-conventions/src/tests/data/markdown/parameter_full/expected.md index 34b5b5ea..079264a5 100644 --- a/semantic-conventions/src/tests/data/markdown/parameter_full/expected.md +++ b/semantic-conventions/src/tests/data/markdown/parameter_full/expected.md @@ -3,25 +3,25 @@ | 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` | 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` | 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: diff --git a/semantic-conventions/src/tests/data/markdown/parameter_remove_constraint/expected.md b/semantic-conventions/src/tests/data/markdown/parameter_remove_constraint/expected.md index b9b93999..7a6ef541 100644 --- a/semantic-conventions/src/tests/data/markdown/parameter_remove_constraint/expected.md +++ b/semantic-conventions/src/tests/data/markdown/parameter_remove_constraint/expected.md @@ -3,8 +3,8 @@ | 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.type` | string | Database type. For any SQL database, "sql". For others, the lower-case database category. | `sql` | `Required` | Experimental | +| `db.connection_string` | string | The connection string used to connect to the database. [1] | `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` | `Recommended` | Experimental | | `net.peer.name` | string | Remote hostname or similar, see note below. | `example.com` | `Recommended` | Experimental | diff --git a/semantic-conventions/src/tests/data/markdown/parameter_tag/expected.md b/semantic-conventions/src/tests/data/markdown/parameter_tag/expected.md index 38ce374f..f79bb0e4 100644 --- a/semantic-conventions/src/tests/data/markdown/parameter_tag/expected.md +++ b/semantic-conventions/src/tests/data/markdown/parameter_tag/expected.md @@ -3,8 +3,8 @@ | 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.type` | string | Database type. For any SQL database, "sql". For others, the lower-case database category. | `sql` | `Required` | Experimental | +| `db.connection_string` | string | The connection string used to connect to the database. [1] | `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 | diff --git a/semantic-conventions/src/tests/data/markdown/parameter_tag_empty/expected.md b/semantic-conventions/src/tests/data/markdown/parameter_tag_empty/expected.md index bfdee699..05445f02 100644 --- a/semantic-conventions/src/tests/data/markdown/parameter_tag_empty/expected.md +++ b/semantic-conventions/src/tests/data/markdown/parameter_tag_empty/expected.md @@ -4,19 +4,19 @@ | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | `db.dbms` | string | An identifier for the DBMS (database management system) product | `mssql` | `Conditionally Required` for `db.type="sql"` | Experimental | -| `db.jdbc.driver_classname` | string | The fully-qualified class name of the JDBC driver used to connect. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | `Recommended` | Experimental | -| `db.mssql.instance_name` | string | The Microsoft SQL Server [instance name](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) connecting to. This name is used to determine the port of a named instance. [1] | `MSSQLSERVER` | `Recommended` | Experimental | -| `db.name` | string | If no tech-specific attribute is defined below, this attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [2] | `customers`; `master` | `Conditionally Required` [3] | Experimental | +| `db.name` | string | If no tech-specific attribute is defined below, this attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`; `master` | `Conditionally Required` [2] | Experimental | | `db.operation` | string | The type of operation that is executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`. While it would semantically make sense to set this, e.g., to a SQL keyword like `SELECT` or `INSERT`, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property (the back end can do that if required). | `findAndModify` | `Conditionally Required` if `db.statement` is not applicable. | Experimental | -| `db.statement` | string | A database statement for the given database type. [4] | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | `Conditionally Required` if applicable. | Experimental | +| `db.statement` | string | A database statement for the given database type. [3] | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | `Conditionally Required` if applicable. | Experimental | +| `db.jdbc.driver_classname` | string | The fully-qualified class name of the JDBC driver used to connect. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | `Recommended` | Experimental | +| `db.mssql.instance_name` | string | The Microsoft SQL Server [instance name](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) connecting to. This name is used to determine the port of a named instance. [4] | `MSSQLSERVER` | `Recommended` | Experimental | -**[1]:** If setting a `db.mssql.instance_name`, `net.peer.port` is no longer required (but still recommended if non-standard). +**[1]:** In some SQL databases, the database name to be used is called "schema name". Redis does not have a database name to used here. -**[2]:** In some SQL databases, the database name to be used is called "schema name". Redis does not have a database name to used here. +**[2]:** if applicable and no more-specific attribute is defined. -**[3]:** if applicable and no more-specific attribute is defined. +**[3]:** The value may be sanitized to exclude sensitive information. -**[4]:** The value may be sanitized to exclude sensitive information. +**[4]:** If setting a `db.mssql.instance_name`, `net.peer.port` is no longer required (but still recommended if non-standard). **Additional attribute requirements:** At least one of the following sets of attributes is required: diff --git a/semantic-conventions/src/tests/data/markdown/ref/expected.md b/semantic-conventions/src/tests/data/markdown/ref/expected.md index 2fade255..145d9267 100644 --- a/semantic-conventions/src/tests/data/markdown/ref/expected.md +++ b/semantic-conventions/src/tests/data/markdown/ref/expected.md @@ -3,11 +3,11 @@ | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`net.peer.name`](input_general.md) | string | override brief. [1] | `example.com` | `Opt-In` | Experimental | | [`net.peer.port`](input_general.md) | int | It describes the server port the client is connecting to | `80`; `8080`; `443` | `Required` | Experimental | | [`net.sock.peer.addr`](input_general.md) | string | Remote socket peer address. | `127.0.0.1`; `/tmp/mysql.sock` | `Required` | Experimental | -| [`net.sock.peer.port`](input_general.md) | int | Remote socket peer port. | `16456` | `Conditionally Required` | Experimental | | `rpc.service` | string | The service name, must be equal to the $service part in the span name. | `EchoService` | `Required` | Experimental | +| [`net.sock.peer.port`](input_general.md) | int | Remote socket peer port. | `16456` | `Conditionally Required` | Experimental | +| [`net.peer.name`](input_general.md) | string | override brief. [1] | `example.com` | `Opt-In` | Experimental | **[1]:** override note. diff --git a/semantic-conventions/src/tests/data/markdown/sampling_relevant/expected.md b/semantic-conventions/src/tests/data/markdown/sampling_relevant/expected.md index 1bf30abd..260fd99e 100644 --- a/semantic-conventions/src/tests/data/markdown/sampling_relevant/expected.md +++ b/semantic-conventions/src/tests/data/markdown/sampling_relevant/expected.md @@ -3,10 +3,10 @@ | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| `http.host` | string | . | `.` | `Recommended` | Experimental | | `http.method` | string | . | `GET` | `Required` | Experimental | -| `http.scheme` | string | . | `http` | `Recommended` | Experimental | | `http.status_code` | int | . | | `Conditionally Required` | Experimental | +| `http.host` | string | . | `.` | `Recommended` | Experimental | +| `http.scheme` | string | . | `http` | `Recommended` | Experimental | | `http.target` | string | . | `.` | `Recommended` | Experimental | | `http.url` | string | . [1] | `.` | `Recommended` | Experimental | | `http.user_agent` | string | . | `.` | `Recommended` | Experimental | @@ -18,8 +18,8 @@ The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): -* `http.host` * `http.method` +* `http.host` * `http.scheme` * `http.target` * `http.url` diff --git a/semantic-conventions/src/tests/data/markdown/single/expected.md b/semantic-conventions/src/tests/data/markdown/single/expected.md index 212af0eb..88ed09ac 100644 --- a/semantic-conventions/src/tests/data/markdown/single/expected.md +++ b/semantic-conventions/src/tests/data/markdown/single/expected.md @@ -4,10 +4,10 @@ | 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` | `Conditionally Required` | 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.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` | 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.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 | diff --git a/semantic-conventions/src/tests/semconv/model/test_correct_parse.py b/semantic-conventions/src/tests/semconv/model/test_correct_parse.py index 44604676..51ef2112 100644 --- a/semantic-conventions/src/tests/semconv/model/test_correct_parse.py +++ b/semantic-conventions/src/tests/semconv/model/test_correct_parse.py @@ -84,7 +84,7 @@ def test_faas(self): "prefix": "faas", "extends": "", "n_constraints": 0, - "attributes": ["faas.execution", "faas.trigger"], + "attributes": ["faas.trigger", "faas.execution"], } self.semantic_convention_check(list(semconv.models.values())[0], expected) expected = { @@ -94,9 +94,9 @@ def test_faas(self): "n_constraints": 0, "attributes": [ "faas.document.collection", - "faas.document.name", "faas.document.operation", "faas.document.time", + "faas.document.name", ], } self.semantic_convention_check(list(semconv.models.values())[1], expected) @@ -121,7 +121,7 @@ def test_faas(self): "prefix": "faas", "extends": "faas", "n_constraints": 0, - "attributes": ["faas.cron", "faas.time"], + "attributes": ["faas.time", "faas.cron"], } self.semantic_convention_check(list(semconv.models.values())[4], expected) @@ -166,11 +166,11 @@ def test_http(self): "extends": "", "n_constraints": 0, "attributes": [ + "http.method", + "http.status_code", "http.flavor", "http.host", - "http.method", "http.scheme", - "http.status_code", "http.status_text", "http.target", "http.url", @@ -429,11 +429,11 @@ def test_extends(self): "extends": "", "n_constraints": 0, "attributes": [ + "http.method", + "http.status_code", "http.flavor", "http.host", - "http.method", "http.scheme", - "http.status_code", "http.status_text", "http.target", "http.url", @@ -447,11 +447,11 @@ def test_extends(self): "extends": "http", "n_constraints": 1, "attributes": [ + "http.method", + "http.status_code", "http.flavor", "http.host", - "http.method", "http.scheme", - "http.status_code", "http.status_text", "http.target", "http.url", @@ -465,12 +465,12 @@ def test_extends(self): "extends": "http", "n_constraints": 1, "attributes": [ - "http.flavor", - "http.host", "http.method", - "http.scheme", "http.server_name", "http.status_code", + "http.flavor", + "http.host", + "http.scheme", "http.status_text", "http.target", "http.url", @@ -496,16 +496,14 @@ def test_include(self): "extends": "faas", "n_constraints": 2, "attributes": [ - # Parent - "faas.execution", - "faas.trigger", - # Include - "http.flavor", - "http.host", + "faas.trigger", # Parent "http.method", - "http.scheme", "http.server_name", "http.status_code", + "faas.execution", # Parent + "http.flavor", + "http.host", + "http.scheme", "http.status_text", "http.target", "http.url", @@ -667,61 +665,61 @@ def test_inherited_imported(self): self.assertEqual(models[2].semconv_id, "rpc") self.assertEqual(len(attrs), 4) - self.assertEqual(attrs[0].fqn, "net.peer.ip") - self.assertEqual(attrs[0].imported, True) + self.assertEqual(attrs[0].fqn, "rpc.service") + self.assertEqual(attrs[0].imported, False) self.assertEqual(attrs[0].inherited, False) self.assertEqual(attrs[0].ref, None) - self.assertEqual(attrs[1].fqn, "net.peer.name") + self.assertEqual(attrs[1].fqn, "net.peer.ip") self.assertEqual(attrs[1].imported, True) self.assertEqual(attrs[1].inherited, False) self.assertEqual(attrs[1].ref, None) - self.assertEqual(attrs[2].fqn, "net.peer.port") + self.assertEqual(attrs[2].fqn, "net.peer.name") self.assertEqual(attrs[2].imported, True) self.assertEqual(attrs[2].inherited, False) self.assertEqual(attrs[2].ref, None) - self.assertEqual(attrs[2].note, "not override") - self.assertEqual(attrs[3].fqn, "rpc.service") - self.assertEqual(attrs[3].imported, False) + self.assertEqual(attrs[3].fqn, "net.peer.port") + self.assertEqual(attrs[3].imported, True) self.assertEqual(attrs[3].inherited, False) self.assertEqual(attrs[3].ref, None) + self.assertEqual(attrs[3].note, "not override") # Extended - rpc.client attrs = models[3].attributes_and_templates self.assertEqual(models[3].semconv_id, "rpc.client") self.assertEqual(len(attrs), 6) - self.assertEqual(attrs[0].fqn, "http.method") - self.assertEqual(attrs[0].imported, True) + self.assertEqual(attrs[0].fqn, "net.peer.port") + self.assertEqual(attrs[0].imported, False) self.assertEqual(attrs[0].inherited, False) - self.assertEqual(attrs[0].ref, None) + self.assertEqual(attrs[0].ref, "net.peer.port") + self.assertEqual(attrs[0].brief, "override") + self.assertEqual(attrs[0].note, "not override") - self.assertEqual(attrs[1].fqn, "net.peer.ip") - self.assertEqual(attrs[1].imported, True) - self.assertEqual(attrs[1].inherited, True) + self.assertEqual(attrs[1].fqn, "rpc.client.name") + self.assertEqual(attrs[1].imported, False) + self.assertEqual(attrs[1].inherited, False) self.assertEqual(attrs[1].ref, None) - self.assertEqual(attrs[2].fqn, "net.peer.name") - self.assertEqual(attrs[2].imported, True) + self.assertEqual(attrs[2].fqn, "rpc.service") + self.assertEqual(attrs[2].imported, False) self.assertEqual(attrs[2].inherited, True) self.assertEqual(attrs[2].ref, None) - self.assertEqual(attrs[3].fqn, "net.peer.port") - self.assertEqual(attrs[3].imported, False) + self.assertEqual(attrs[3].fqn, "http.method") + self.assertEqual(attrs[3].imported, True) self.assertEqual(attrs[3].inherited, False) - self.assertEqual(attrs[3].ref, "net.peer.port") - self.assertEqual(attrs[3].brief, "override") - self.assertEqual(attrs[3].note, "not override") + self.assertEqual(attrs[3].ref, None) - self.assertEqual(attrs[4].fqn, "rpc.client.name") - self.assertEqual(attrs[4].imported, False) - self.assertEqual(attrs[4].inherited, False) + self.assertEqual(attrs[4].fqn, "net.peer.ip") + self.assertEqual(attrs[4].imported, True) + self.assertEqual(attrs[4].inherited, True) self.assertEqual(attrs[4].ref, None) - self.assertEqual(attrs[5].fqn, "rpc.service") - self.assertEqual(attrs[5].imported, False) + self.assertEqual(attrs[5].fqn, "net.peer.name") + self.assertEqual(attrs[5].imported, True) self.assertEqual(attrs[5].inherited, True) self.assertEqual(attrs[5].ref, None) @@ -740,40 +738,40 @@ def test_inherited_imported(self): self.assertEqual(models[5].semconv_id, "zz.rpc.client") self.assertEqual(len(attrs), 8) - self.assertEqual(attrs[0].fqn, "http.method") - self.assertEqual(attrs[0].imported, True) + self.assertEqual(attrs[0].fqn, "net.peer.port") + self.assertEqual(attrs[0].imported, False) self.assertEqual(attrs[0].inherited, True) - self.assertEqual(attrs[0].ref, None) + self.assertEqual(attrs[0].ref, "net.peer.port") + self.assertEqual(attrs[0].brief, "override") + self.assertEqual(attrs[0].note, "not override") - self.assertEqual(attrs[1].fqn, "net.peer.ip") - self.assertEqual(attrs[1].imported, True) + self.assertEqual(attrs[1].fqn, "rpc.client.name") + self.assertEqual(attrs[1].imported, False) self.assertEqual(attrs[1].inherited, True) self.assertEqual(attrs[1].ref, None) - self.assertEqual(attrs[2].fqn, "net.peer.name") - self.assertEqual(attrs[2].imported, True) - self.assertEqual(attrs[2].inherited, True) + self.assertEqual(attrs[2].fqn, "rpc.client.zz.attr") + self.assertEqual(attrs[2].imported, False) + self.assertEqual(attrs[2].inherited, False) self.assertEqual(attrs[2].ref, None) - self.assertEqual(attrs[3].fqn, "net.peer.port") + self.assertEqual(attrs[3].fqn, "rpc.service") self.assertEqual(attrs[3].imported, False) self.assertEqual(attrs[3].inherited, True) - self.assertEqual(attrs[3].ref, "net.peer.port") - self.assertEqual(attrs[3].brief, "override") - self.assertEqual(attrs[3].note, "not override") + self.assertEqual(attrs[3].ref, None) - self.assertEqual(attrs[4].fqn, "rpc.client.name") - self.assertEqual(attrs[4].imported, False) + self.assertEqual(attrs[4].fqn, "http.method") + self.assertEqual(attrs[4].imported, True) self.assertEqual(attrs[4].inherited, True) self.assertEqual(attrs[4].ref, None) - self.assertEqual(attrs[5].fqn, "rpc.client.zz.attr") - self.assertEqual(attrs[5].imported, False) - self.assertEqual(attrs[5].inherited, False) + self.assertEqual(attrs[5].fqn, "net.peer.ip") + self.assertEqual(attrs[5].imported, True) + self.assertEqual(attrs[5].inherited, True) self.assertEqual(attrs[5].ref, None) - self.assertEqual(attrs[6].fqn, "rpc.service") - self.assertEqual(attrs[6].imported, False) + self.assertEqual(attrs[6].fqn, "net.peer.name") + self.assertEqual(attrs[6].imported, True) self.assertEqual(attrs[6].inherited, True) self.assertEqual(attrs[6].ref, None)