Add event name field, fix leading dot in FQN of attribute w/o prefix.

semantic-conventions/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 Please update the changelog as part of any significant pull request.
 
+## v0.8.0
+
+- Add `name` field for events. It defaults to the `prefix`
+  ([#67](https://github.com/open-telemetry/build-tools/pull/67)).
+
 ## v0.7.0
 
 - Support sampling_relevant attribute fields

semantic-conventions/semconv.schema.json

@@ -13,6 +13,9 @@
 					},
 					{
 						"allOf": [{"$ref": "#/definitions/SpanSemanticConvention"}]
+					},
+					{
+						"allOf": [{"$ref": "#/definitions/EventSemanticConvention"}]
 					}
 				]
 			}
@@ -143,14 +146,31 @@
 				}
 			}
 		},
+		"EventSemanticConvention": {
+			"allOf": [{ "$ref": "#/definitions/SemanticConventionBase" }],
+			"properties": {
+				"type": {
+					"type": "string",
+					"const": "event"
+				},
+				"name": {
+					"type": "string",
+					"description": "The name of the event. Required if no prefix is given."
+				}
+			},
+			"anyOf": [
+				{"required": ["prefix"]},
+				{"required": ["name"]}
+			]
+		},
 		"SemanticConvention": {
 			"allOf": [{ "$ref": "#/definitions/SemanticConventionBase" }],
 			"required": ["type"],
 			"properties": {
 				"type": {
 					"type": "string",
 					"not": {
-						"const": "span"
+						"enum": ["span", "event"]
 					}
 				}
 			}

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

@@ -117,7 +117,10 @@ def parse(
             if attr_id is not None:
                 validate_id(attr_id, position_data["id"])
                 attr_type, brief, examples = SemanticAttribute.parse_id(attribute)
-                fqn = "{}.{}".format(prefix, attr_id)
+                if prefix:
+                    fqn = "{}.{}".format(prefix, attr_id)
+                else:
+                    fqn = attr_id
             else:
                 # Ref
                 attr_type = None

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

@@ -16,7 +16,7 @@
 import typing
 from dataclasses import dataclass, field
 from enum import Enum
-from typing import Union
+from typing import Tuple, Union
 
 from ruamel.yaml import YAML
 
@@ -96,6 +96,18 @@ def SemanticConvention(group):
 class BaseSemanticConvention(ValidatableYamlNode):
     """Contains the model extracted from a yaml file"""
 
+    allowed_keys: Tuple[str, ...] = (
+        "id",
+        "type",
+        "brief",
+        "note",
+        "prefix",
+        "stability",
+        "extends",
+        "attributes",
+        "constraints",
+    )
+
     GROUP_TYPE_NAME: str
 
     @property
@@ -176,34 +188,13 @@ def validate_values(self):
 class ResourceSemanticConvention(BaseSemanticConvention):
     GROUP_TYPE_NAME = "resource"
 
-    allowed_keys = (
-        "id",
-        "type",
-        "brief",
-        "note",
-        "prefix",
-        "stability",
-        "extends",
-        "attributes",
-        "constraints",
-    )
-
 
 class SpanSemanticConvention(BaseSemanticConvention):
     GROUP_TYPE_NAME = "span"
 
-    allowed_keys = (
-        "id",
-        "type",
-        "brief",
-        "note",
-        "prefix",
-        "stability",
-        "extends",
+    allowed_keys = BaseSemanticConvention.allowed_keys + (
         "events",
         "span_kind",
-        "attributes",
-        "constraints",
     )
 
     def __init__(self, group):
@@ -218,23 +209,21 @@ def __init__(self, group):
 class EventSemanticConvention(BaseSemanticConvention):
     GROUP_TYPE_NAME = "event"
 
-    allowed_keys = (
-        "id",
-        "type",
-        "brief",
-        "note",
-        "prefix",
-        "stability",
-        "extends",
-        "attributes",
-        "constraints",
-    )
+    allowed_keys = BaseSemanticConvention.allowed_keys + ("name",)
+
+    def __init__(self, group):
+        super().__init__(group)
+        self.name = group.get("name", self.prefix)
+        if not self.name:
+            raise ValidationError.from_yaml_pos(
+                self._position, "Event must define at least one of name or prefix"
+            )
 
 
 class UnitSemanticConvention(BaseSemanticConvention):
     GROUP_TYPE_NAME = "units"
 
-    allowed_keys = (
+    allowed_keys = (  # We completely override base semantic keys here.
         "id",
         "type",
         "brief",

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

@@ -29,6 +29,7 @@
     StabilityLevel,
 )
 from opentelemetry.semconv.model.semantic_convention import (
+    EventSemanticConvention,
     SemanticConventionSet,
     UnitSemanticConvention,
 )
@@ -390,14 +391,14 @@ def _render_single_file(self, content: str, md: str, output: io.StringIO):
                     "Semantic Convention ID {} not found".format(semconv_id)
                 )
             output.write(content[last_match : match.start(0)])
-            self._render_table(semconv, parameters, output)
+            self._render_group(semconv, parameters, output)
             end_match = self.p_end.search(content, last_match)
             if not end_match:
                 raise ValueError("Missing ending <!-- endsemconv --> tag")
             last_match = end_match.end()
         output.write(content[last_match:])
 
-    def _render_table(self, semconv, parameters, output):
+    def _render_group(self, semconv, parameters, output):
         header: str
         header = semconv.semconv_id
         if parameters:
@@ -412,6 +413,10 @@ def _render_table(self, semconv, parameters, output):
         self.render_ctx.is_remove_constraint = "remove_constraints" in parameters
         self.render_ctx.group_key = parameters.get("tag")
         self.render_ctx.is_full = "full" in parameters
+
+        if isinstance(semconv, EventSemanticConvention):
+            output.write("The event name MUST be `{}`.\n\n".format(semconv.name))
+
         attr_to_print = []
         attr: SemanticAttribute
         for attr in sorted(

semantic-conventions/src/opentelemetry/semconv/version.py

@@ -12,4 +12,4 @@
 #   See the License for the specific language governing permissions and
 #   limitations under the License.
 
-__version__ = "0.7.0"
+__version__ = "0.8.0"

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

@@ -1,6 +1,8 @@
 # Test
 
 <!-- semconv event -->
+The event name MUST be `exception`.
+
 | Attribute  | Type | Description  | Examples  | Required |
 |---|---|---|---|---|
 | `exception.type` | string | The type of the exception. | `java.net.ConnectException`; `OSError` | See below |
@@ -14,4 +16,4 @@
 
 * `exception.type`
 * `exception.message`
-<!-- endsemconv -->
+<!-- endsemconv -->

semantic-conventions/src/tests/data/markdown/event/input.md

@@ -2,4 +2,4 @@
 
 <!-- semconv event -->
 
-<!-- endsemconv -->
+<!-- endsemconv -->

semantic-conventions/src/tests/data/markdown/event_noprefix/event.yaml

@@ -0,0 +1,9 @@
+groups:
+  - id: event
+    name: myname
+    type: event
+    brief: brief
+    attributes:
+      - id: attr
+        type: boolean
+        brief: attrbrief

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

@@ -0,0 +1,9 @@
+# Test
+
+<!-- semconv event -->
+The event name MUST be `myname`.
+
+| Attribute  | Type | Description  | Examples  | Required |
+|---|---|---|---|---|
+| `attr` | boolean | attrbrief |  | No |
+<!-- endsemconv -->

semantic-conventions/src/tests/data/markdown/event_noprefix/input.md

@@ -0,0 +1,5 @@
+# Test
+
+<!-- semconv event -->
+
+<!-- endsemconv -->

semantic-conventions/src/tests/data/markdown/event_renamed/event.yaml

@@ -0,0 +1,10 @@
+groups:
+  - id: event
+    name: myname
+    prefix: myprefix
+    type: event
+    brief: brief
+    attributes:
+      - id: attr
+        type: boolean
+        brief: attrbrief

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

@@ -0,0 +1,9 @@
+# Test
+
+<!-- semconv event -->
+The event name MUST be `myname`.
+
+| Attribute  | Type | Description  | Examples  | Required |
+|---|---|---|---|---|
+| `myprefix.attr` | boolean | attrbrief |  | No |
+<!-- endsemconv -->

semantic-conventions/src/tests/data/markdown/event_renamed/input.md

@@ -0,0 +1,5 @@
+# Test
+
+<!-- semconv event -->
+
+<!-- endsemconv -->

semantic-conventions/src/tests/data/yaml/errors/events/nameless_event.yaml

@@ -0,0 +1,8 @@
+groups:
+  - id: eventid
+    type: event
+    brief: eventbrief
+    attributes:
+      - id: eventattr
+        type: boolean
+        brief: eventattrbrief

semantic-conventions/src/tests/semconv/model/test_error_detection.py

@@ -442,6 +442,14 @@ def test_wrong_event_type(self):
         )
         self.assertEqual(e.line, 2)
 
+    def test_nameless_event(self):
+        with self.assertRaises(ValidationError) as ex:
+            self.open_yaml("yaml/errors/events/nameless_event.yaml")
+        e = ex.exception
+        msg = e.message.lower()
+        self.assertIn("at least one of name or prefix", msg)
+        self.assertEqual(e.line, 2)
+
     def open_yaml(self, path):
         with open(self.load_file(path), encoding="utf-8") as file:
             return parse_semantic_convention_groups(file)

semantic-conventions/src/tests/semconv/model/test_semantic_attribute.py

@@ -46,8 +46,6 @@ def test_parse_deprecated(load_yaml):
     attributes = SemanticAttribute.parse("", "", yaml.get("attributes"))
 
     assert len(attributes) == 1
-    assert list(attributes.keys()) == [".deprecated_attribute"]
+    assert list(attributes.keys()) == ["deprecated_attribute"]
 
-    assert (
-        attributes[".deprecated_attribute"].deprecated == "don't use this one anymore"
-    )
+    assert attributes["deprecated_attribute"].deprecated == "don't use this one anymore"

semantic-conventions/src/tests/semconv/templating/test_markdown.py

@@ -117,6 +117,12 @@ def test_units(self):
     def test_event(self):
         self.check("markdown/event/")
 
+    def test_event_noprefix(self):
+        self.check("markdown/event_noprefix/")
+
+    def test_event_renamed(self):
+        self.check("markdown/event_renamed/")
+
     def testSamplingRelevant(self):
         self.check("markdown/sampling_relevant/")