Make stability required, fix ref and extends, render badges on metrics (#272)

Author: lmolkova

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

@@ -128,6 +128,12 @@ def parse(
                 if "type" in attribute:
                     msg = f"Ref attribute '{ref}' must not declare a type"
                     raise ValidationError.from_yaml_pos(position, msg)
+                if "stability" in attribute:
+                    msg = f"Ref attribute '{ref}' must not override stability"
+                    raise ValidationError.from_yaml_pos(position, msg)
+                if "deprecated" in attribute:
+                    msg = f"Ref attribute '{ref}' must not override deprecation status"
+                    raise ValidationError.from_yaml_pos(position, msg)
                 brief = attribute.get("brief")
                 examples = attribute.get("examples")
                 ref = ref.strip()
@@ -224,7 +230,7 @@ def parse(
 
     @staticmethod
     def parse_attribute(attribute):
-        check_no_missing_keys(attribute, ["type", "brief"])
+        check_no_missing_keys(attribute, ["type", "brief", "stability"])
         attr_val = attribute["type"]
         try:
             attr_type = EnumAttributeType.parse(attr_val)
@@ -284,7 +290,7 @@ def parse_attribute(attribute):
     @staticmethod
     def parse_stability(stability, position_data, strict_validation=True):
         if stability is None:
-            return StabilityLevel.EXPERIMENTAL
+            return None
 
         stability_value_map = {
             "experimental": StabilityLevel.EXPERIMENTAL,

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

@@ -104,6 +104,7 @@ class BaseSemanticConvention(ValidatableYamlNode):
         "extends",
         "attributes",
         "constraints",
+        "deprecated",
     )
 
     GROUP_TYPE_NAME: str
@@ -268,11 +269,11 @@ def __init__(self, group, strict_validation=True):
         self.validate()
 
     def validate(self):
-        val_tuple = (self.metric_name, self.unit, self.instrument)
+        val_tuple = (self.metric_name, self.unit, self.instrument, self.stability)
         if not all(val_tuple):
             raise ValidationError.from_yaml_pos(
                 self._position,
-                "All of metric_name, units, and instrument must be defined",
+                "All of metric_name, units, instrument, and stability must be defined",
             )
 
         if self.instrument not in self.allowed_instruments:
@@ -483,6 +484,8 @@ def _fill_inherited_attribute(self, attr, semconv):
 
     def _merge_attribute(self, child, parent):
         child.attr_type = parent.attr_type
+        child.stability = parent.stability
+        child.deprecated = parent.deprecated
         if not child.brief:
             child.brief = parent.brief
         if not child.requirement_level:

semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py

@@ -124,25 +124,7 @@ def to_markdown_attr(
             if isinstance(attribute.attr_type, EnumAttributeType)
             else AttributeType.get_instantiated_type(attribute.attr_type)
         )
-        description = ""
-        if attribute.deprecated and self.options.enable_deprecated:
-            if "deprecated" in attribute.deprecated.lower():
-                description = f"**{attribute.deprecated}**<br>"
-            else:
-                deprecated_msg = self.options.deprecated_md_snippet().format(
-                    attribute.deprecated
-                )
-                description = f"{deprecated_msg}<br>"
-        elif (
-            attribute.stability == StabilityLevel.STABLE and self.options.enable_stable
-        ):
-            description = f"{self.options.stable_md_snippet()}<br>"
-        elif (
-            attribute.stability == StabilityLevel.EXPERIMENTAL
-            and self.options.enable_experimental
-        ):
-            description = f"{self.options.experimental_md_snippet()}<br>"
-        description += attribute.brief
+        description = self._description_with_badge(attribute) + attribute.brief
         if attribute.note:
             self.render_ctx.add_note(attribute.note)
             description += f" [{len(self.render_ctx.notes)}]"
@@ -258,7 +240,7 @@ def to_markdown_metric_table(
             "| -------- | --------------- | ----------- | -------------- |\n"
         )
 
-        description = semconv.brief
+        description = self._description_with_badge(semconv) + semconv.brief
         if semconv.note:
             self.render_ctx.add_note(semconv.note)
             description += f" [{len(self.render_ctx.notes)}]"
@@ -544,3 +526,25 @@ def _render_group(self, semconv, parameters, output):
             self.to_markdown_unit_table(semconv.members, output)
 
         output.write("<!-- endsemconv -->")
+
+    def _description_with_badge(
+        self, item: typing.Union[SemanticAttribute | BaseSemanticConvention]
+    ):
+        description = ""
+        if item.deprecated and self.options.enable_deprecated:
+            if "deprecated" in item.deprecated.lower():
+                description = f"**{item.deprecated}**<br>"
+            else:
+                deprecated_msg = self.options.deprecated_md_snippet().format(
+                    item.deprecated
+                )
+                description = f"{deprecated_msg}<br>"
+        elif item.stability == StabilityLevel.STABLE and self.options.enable_stable:
+            description = f"{self.options.stable_md_snippet()}<br>"
+        elif (
+            item.stability == StabilityLevel.EXPERIMENTAL
+            and self.options.enable_experimental
+        ):
+            description = f"{self.options.experimental_md_snippet()}<br>"
+
+        return description

semantic-conventions/src/tests/data/compat/attribute_stable_to_experimental/vnext.yaml

@@ -22,3 +22,4 @@ groups:
         brief: "Request headers."
         note: "Request headers note."
         examples: '`first.fifth_attr.bar=["foo"]`'
+        stability: experimental

semantic-conventions/src/tests/data/compat/attribute_stable_to_experimental/vprev.yaml

@@ -10,6 +10,7 @@ groups:
         brief: "first attribute"
         note: "first attribute note"
         examples: "first example"
+        stability: experimental
       - id: second_attr
         type: int
         brief: "second attribute"

semantic-conventions/src/tests/data/compat/attribute_type_changed/vprev.yaml

@@ -10,6 +10,7 @@ groups:
         brief: "first attribute"
         note: "first attribute note"
         examples: "first example"
+        stability: experimental
       - id: second_attr
         type: int
         brief: "second attribute"

semantic-conventions/src/tests/data/compat/removed_attribute/vprev.yaml

@@ -10,6 +10,7 @@ groups:
         brief: "first attribute"
         note: "first attribute note"
         examples: "first example"
+        stability: experimental
       - id: second_attr
         type: int
         brief: "second attribute"
@@ -20,3 +21,4 @@ groups:
         type: template[string[]]
         brief: "request headers"
         examples: '`first.fifth_attr.foo=["bar"]`'
+        stability: experimental

semantic-conventions/src/tests/data/compat/success/vprev.yaml

@@ -10,6 +10,7 @@ groups:
         brief: "first attribute"
         note: "first attribute note"
         examples: "first example"
+        stability: experimental
       - id: second_attr
         type: int
         brief: "second attribute"

semantic-conventions/src/tests/data/markdown/attribute_group/attribute_group.yaml

@@ -6,10 +6,11 @@ groups:
     attributes:
       - id: bar
         type: string
-        requirement_level: 
+        requirement_level:
           recommended: if available
         brief: Attribute 1
         examples: ['baz']
+        stability: experimental
 
   - id: derived_attributes
     type: attribute_group
@@ -19,10 +20,11 @@ groups:
     attributes:
       - id: qux
         type: int
-        requirement_level: 
+        requirement_level:
           conditionally_required: if available
         brief: Attribute 2
         examples: [42]
+        stability: experimental
 
   - id: span_attribute_group
     prefix: ""

semantic-conventions/src/tests/data/markdown/attribute_templates/attribute_templates.yaml

@@ -14,12 +14,14 @@ groups:
           HTTP request headers, `<key>` being the normalized HTTP Header name
           (lowercase, with - characters replaced by _), the value being the header values.
         examples: '`http.request.header.content_type=["application/json"]`'
+        stability: experimental
       - id: request.method
         type: string
         requirement_level: required
         sampling_relevant: false
         brief: 'HTTP request method.'
         examples: ["GET", "POST", "HEAD"]
+        stability: experimental
       - ref: referenced_http.request.referenced.header
   - id: referenced_http_id
     type: span
@@ -31,6 +33,7 @@ groups:
         brief: >
           This is a referenced attribute.
         examples: '`http.request.header.content_type=["application/json"]`'
+        stability: experimental
   - id: general
     type: span
     prefix: general
@@ -41,3 +44,4 @@ groups:
         brief: >
           This is a general attribute.
         examples: '`some_general_attribute.some_key="abc"`'
+        stability: experimental

semantic-conventions/src/tests/data/markdown/deprecated/general.yaml

@@ -6,6 +6,7 @@ groups:
         These attributes may be used for any network related operation.
     attributes:
       - id: transport
+        stability: experimental
         type:
           allow_custom_values: false
           members:
@@ -36,28 +37,34 @@ groups:
           Transport protocol used. See note below.
         examples: 'IP.TCP'
       - id: peer.ip
+        stability: experimental
         type: string
         brief: >
           Remote address of the peer (dotted decimal for IPv4 or
           [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6)
         examples: '127.0.0.1'
       - id: peer.port
+        stability: experimental
         type: int
         brief: 'Remote port number.'
         examples: [80, 8080, 443]
       - id: peer.name
+        stability: experimental
         type: string
         brief: 'Remote hostname or similar, see note below.'
         examples: 'example.com'
       - id: host.ip
+        stability: experimental
         type: string
         brief: 'Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host.'
         examples: '192.168.0.1'
       - id: host.port
+        stability: experimental
         type: int
         brief: 'Like `net.peer.port` but for the host port.'
         examples: 35555
       - id: host.name
+        stability: experimental
         type: string
         brief: 'Local hostname or similar, see note below.'
         examples: 'localhost'
@@ -68,16 +75,19 @@ groups:
         These attributes may be used for any operation with an authenticated and/or authorized enduser.
     attributes:
       - id: id
+        stability: experimental
         type: string
         brief: >
           Username or client_id extracted from the access token or Authorization header
           in the inbound request from outside the system.
         examples: 'username'
       - id: role
+        stability: experimental
         type: string
         brief: 'Actual/assumed role the client is making the request under extracted from token or application security context.'
         examples: 'admin'
       - id: scope
+        stability: experimental
         type: string
         brief: >
           Scopes or granted authorities the client currently possesses extracted from token

semantic-conventions/src/tests/data/markdown/deprecated/http.yaml

@@ -8,43 +8,51 @@ groups:
         and various HTTP versions like 1.1, 2 and SPDY.
     attributes:
       - id: method
+        stability: experimental
         type: string
         requirement_level: required
         sampling_relevant: false
         brief: 'HTTP request method.'
         examples: ["GET", "POST", "HEAD"]
       - id: url
+        stability: experimental
         type: string
         brief: >
             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.
         examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv']
       - id: target
+        stability: experimental
         type: string
         brief: 'The full request target as passed in a HTTP request line or equivalent.'
         examples: ['/path/12314/?q=ddds#123']
       - id: host
+        stability: experimental
         type: string
         brief: >
             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.
         examples: ['www.example.org']
       - id: scheme
+        stability: experimental
         type: string
         brief: 'The URI scheme identifying the used protocol.'
         examples: ["http", "https"]
       - id: status_code
+        stability: experimental
         type: int
         requirement_level:
           conditionally_required: "if and only if one was received/sent"
         brief: '[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6).'
         examples: [200]
       - id: status_text
+        stability: experimental
         type: string
         brief: '[HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2).'
         deprecated: Use attribute `status_description` instead.
         examples: ['OK']
       - id: flavor
+        stability: experimental
         type:
           # Default value: `true`. If false, it helps the code gen tool to
           # encode checks that only accept the listed values.
@@ -72,6 +80,7 @@ groups:
           is `QUIC`, in which case `IP.UDP` is assumed.
         examples: ['1.0']
       - id: user_agent
+        stability: experimental
         type: string
         brief: 'Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client.'
         examples: ['CERN-LineMode/2.15 libwww/2.17b3']
@@ -95,6 +104,7 @@ groups:
     brief: 'Semantic Convention for HTTP Server'
     attributes:
       - id: server_name
+        stability: experimental
         type: string
         requirement_level:
           conditionally_required: >