Add support for Event Semantic Conventions

semantic-conventions/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 Please update the changelog as part of any significant pull request.
 
+## v0.5.0
+
+- Add event semantic convention type & events span field
+  ([#57](https://github.com/open-telemetry/build-tools/pull/57)).
+
 ## v0.4.0
 
 - Add stability fields. (#35)

semantic-conventions/semconv.schema.json

@@ -7,122 +7,154 @@
 		"groups": {
 			"type": "array",
 			"items": {
-				"type": "object",
-				"additionalProperties": false,
-				"required": [
-					"id",
-					"brief"
-				],
 				"anyOf": [
 					{
-						"required": [
-							"attributes"
-						]
+						"allOf": [{"$ref": "#/definitions/SemanticConvention"}]
 					},
 					{
-						"required": [
-							"extends"
-						]
+						"allOf": [{"$ref": "#/definitions/SpanSemanticConvention"}]
 					}
-				],
-				"properties": {
-					"id": {
-						"type": "string",
-						"description": "unique string"
-					},
-					"type": {
-						"type": "string",
-						"enum": [
-							"span",
-							"resource",
-							"metric"
-						]
-					},
-					"brief": {
-						"type": "string",
-						"description": "a brief description of the semantic convention"
-					},
-					"note": {
-						"type": "string",
-						"description": "a more elaborate description of the semantic convention. It defaults to an empty string"
-					},
-					"prefix": {
-						"type": "string",
-						"description": "prefix of the attribute for this semconv. It defaults to an empty string."
-					},
-					"extends": {
-						"type": "string",
-						"description": "reference another semantic convention ID. It inherits all attributes from the specified semconv."
-					},
-					"span_kind": {
-						"type": "string",
-						"enum": [
-							"client",
-							"server",
-							"producer",
-							"consumer",
-							"internal"
-						],
-						"description": "specifies the kind of the span. Leaf semconv nodes (in the hierarchy tree) that do not have this field set will generate a warning."
-					},
-					"attributes": {
-						"type": "array",
-						"items": {
-							"$ref": "#/definitions/Attribute"
-						},
-						"description": "list of attributes that belong to the semconv"
+				]
+			}
+		}
+	},
+	"definitions": {
+		"SemanticConventionBase": {
+			"type": "object",
+			"required": [
+				"id",
+				"brief"
+			],
+			"anyOf": [
+				{
+					"required": [
+						"attributes"
+					]
+				},
+				{
+					"required": [
+						"extends"
+					]
+				}
+			],
+			"properties": {
+				"id": {
+					"type": "string",
+					"description": "unique string"
+				},
+				"type": {
+					"type": "string",
+					"enum": [
+						"span",
+						"resource",
+						"metric",
+						"event"
+					],
+					"description": "The (signal) type of the semantic convention"
+				},
+				"brief": {
+					"type": "string",
+					"description": "a brief description of the semantic convention"
+				},
+				"note": {
+					"type": "string",
+					"description": "a more elaborate description of the semantic convention. It defaults to an empty string"
+				},
+				"prefix": {
+					"type": "string",
+					"description": "prefix of the attribute for this semconv. It defaults to an empty string."
+				},
+				"extends": {
+					"type": "string",
+					"description": "reference another semantic convention ID. It inherits all attributes from the specified semconv."
+				},
+				"attributes": {
+					"type": "array",
+					"items": {
+						"$ref": "#/definitions/Attribute"
 					},
-					"constraints": {
-						"type": "array",
-						"items": {
-							"anyOf": [
-								{
-									"type": "object",
-									"additionalProperties": false,
-									"required": [
-										"any_of"
-									],
-									"properties": {
-										"any_of": {
-											"type": "array",
-											"description": " accepts a list of sequences. Each sequence contains a list of attribute ids that are required. any_of enforces that all attributes of at least one of the sequences are set.",
-											"items": {
-												"anyOf": [
-													{
-														"type": "array",
-														"items": {
-															"type": "string"
-														}
-													},
-													{
+					"description": "list of attributes that belong to the semconv"
+				},
+				"constraints": {
+					"type": "array",
+					"items": {
+						"anyOf": [
+							{
+								"type": "object",
+								"additionalProperties": false,
+								"required": [
+									"any_of"
+								],
+								"properties": {
+									"any_of": {
+										"type": "array",
+										"description": " accepts a list of sequences. Each sequence contains a list of attribute ids that are required. any_of enforces that all attributes of at least one of the sequences are set.",
+										"items": {
+											"anyOf": [
+												{
+													"type": "array",
+													"items": {
 														"type": "string"
 													}
-												]
-											}
+												},
+												{
+													"type": "string"
+												}
+											]
 										}
 									}
-								},
-								{
-									"type": "object",
-									"additionalProperties": false,
-									"required": [
-										"include"
-									],
-									"properties": {
-										"include": {
-											"type": "string",
-											"description": "accepts a semantic conventions id. It includes as part of this semantic convention all constraints and required attributes that are not already defined in the current semantic convention."
-										}
+								}
+							},
+							{
+								"type": "object",
+								"additionalProperties": false,
+								"required": [
+									"include"
+								],
+								"properties": {
+									"include": {
+										"type": "string",
+										"description": "accepts a semantic conventions id. It includes as part of this semantic convention all constraints and required attributes that are not already defined in the current semantic convention."
 									}
 								}
-							]
-						}
+							}
+						]
 					}
 				}
 			}
-		}
-	},
-	"definitions": {
+		},
+		"SpanSemanticConvention": {
+			"allOf": [{ "$ref": "#/definitions/SemanticConventionBase" }],
+			"properties": {
+				"type": {
+					"type": "string",
+					"const": "span"
+				},
+				"span_kind": {
+					"type": "string",
+					"enum": [
+						"client",
+						"server",
+						"producer",
+						"consumer",
+						"internal"
+					],
+					"description": "specifies the kind of the span. Leaf semconv nodes (in the hierarchy tree) that do not have this field set will generate a warning."
+				}
+			}
+		},
+		"SemanticConvention": {
+			"allOf": [{ "$ref": "#/definitions/SemanticConventionBase" }],
+			"required": ["type"],
+			"properties": {
+				"type": {
+					"type": "string",
+					"not": {
+						"const": "span"
+					}
+				}
+			}
+		},
 		"AttributeEnumType": {
 			"type": "object",
 			"additionalProperties": false,

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

@@ -19,7 +19,14 @@
 import sys
 from typing import List
 
-from opentelemetry.semconv.model.semantic_convention import SemanticConventionSet
+from opentelemetry.semconv.model.semantic_convention import (
+    SemanticConventionSet,
+    SpanSemanticConvention,
+    ResourceSemanticConvention,
+    EventSemanticConvention,
+    MetricSemanticConvention,
+    UnitSemanticConvention,
+)
 from opentelemetry.semconv.templating.code import CodeRenderer
 
 from opentelemetry.semconv.templating.markdown import MarkdownRenderer
@@ -199,7 +206,13 @@ def setup_parser():
     )
     parser.add_argument(
         "--only",
-        choices=["span", "resource", "metric", "units"],
+        choices=[
+            SpanSemanticConvention.GROUP_TYPE_NAME,
+            ResourceSemanticConvention.GROUP_TYPE_NAME,
+            EventSemanticConvention.GROUP_TYPE_NAME,
+            MetricSemanticConvention.GROUP_TYPE_NAME,
+            UnitSemanticConvention.GROUP_TYPE_NAME,
+        ],
         help="Process only semantic conventions of the specified type.",
     )
     parser.add_argument(

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

@@ -67,6 +67,7 @@ def parse_semantic_convention_type(type_value):
         for cls in [
             SpanSemanticConvention,
             ResourceSemanticConvention,
+            EventSemanticConvention,
             MetricSemanticConvention,
             UnitSemanticConvention,
         ]
@@ -123,6 +124,7 @@ def __init__(self, group):
             stability, deprecated, position_data
         )
         self.extends = group.get("extends", "").strip()
+        self.events = group.get("events", ())
         self.constraints = parse_constraints(group.get("constraints", ()))
 
     @property
@@ -215,6 +217,7 @@ class SpanSemanticConvention(HasAttributes, BaseSemanticConvention):
         "prefix",
         "stability",
         "extends",
+        "events",
         "span_kind",
         "attributes",
         "constraints",
@@ -230,6 +233,26 @@ def __init__(self, group):
             raise ValidationError.from_yaml_pos(position, msg)
 
 
+class EventSemanticConvention(HasAttributes, BaseSemanticConvention):
+    GROUP_TYPE_NAME = "event"
+
+    allowed_keys = (
+        "id",
+        "type",
+        "brief",
+        "note",
+        "prefix",
+        "stability",
+        "extends",
+        "attributes",
+        "constraints",
+    )
+
+    def __init__(self, group):
+        super().__init__(group)
+        self._set_attributes(self.prefix, self.stability, group)
+
+
 class UnitSemanticConvention(BaseSemanticConvention):
     GROUP_TYPE_NAME = "units"
 
@@ -324,6 +347,8 @@ def finish(self):
         self._populate_extends()
         # From string containing attribute ids to SemanticAttribute objects
         self._populate_anyof_attributes()
+        # From strings containing Semantic Conventions for Events ids to SemanticConvention objects
+        self._populate_events()
 
     def _populate_extends(self):
         """
@@ -423,6 +448,28 @@ def _populate_anyof_attributes(self):
                         if constraint_attrs:
                             any_of.add_attributes(constraint_attrs)
 
+    def _populate_events(self):
+        for semconv in self.models.values():
+            events: typing.List[EventSemanticConvention] = []
+            for event_id in semconv.events:
+                event = self.models.get(event_id)
+                if event is None:
+                    raise ValidationError.from_yaml_pos(
+                        semconv._position,
+                        "Semantic Convention {} has {} as event but the latter cannot be found!".format(
+                            semconv.semconv_id, event_id
+                        ),
+                    )
+                if not isinstance(event, EventSemanticConvention):
+                    raise ValidationError.from_yaml_pos(
+                        semconv._position,
+                        "Semantic Convention {} has {} as event but the latter is not a semantic convention for events!".format(
+                            semconv.semconv_id, event_id
+                        ),
+                    )
+                events.append(event)
+            semconv.events = events
+
     def resolve_ref(self, semconv):
         fixpoint_ref = True
         attr: SemanticAttribute

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.4.1"
+__version__ = "0.5.0"