Add attribute_group type to share attributes across signals (#124)

Fixes #123

Co-authored-by: Armin Ruech <[email protected]>

semantic-conventions/CHANGELOG.md

@@ -4,7 +4,8 @@ Please update the changelog as part of any significant pull request.
 
 ## Unreleased
 
-- ...
+- Add a semantic convention type for generic attribute group ("attribute_group")
+  ([#124](https://github.com/open-telemetry/build-tools/pull/124)).
 
 ## v0.14.0
 

semantic-conventions/semconv.schema.json

@@ -52,7 +52,8 @@
 						"resource",
 						"metric",
 						"event",
-						"scope"
+						"scope",
+						"attribute_group"
 					],
 					"description": "The (signal) type of the semantic convention"
 				},

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

@@ -196,6 +196,10 @@ class ScopeSemanticConvention(BaseSemanticConvention):
     GROUP_TYPE_NAME = "scope"
 
 
+class AttributeGroupConvention(BaseSemanticConvention):
+    GROUP_TYPE_NAME = "attribute_group"
+
+
 class SpanSemanticConvention(BaseSemanticConvention):
     GROUP_TYPE_NAME = "span"
 
@@ -531,5 +535,6 @@ def attributes(self):
         MetricSemanticConvention,
         UnitSemanticConvention,
         ScopeSemanticConvention,
+        AttributeGroupConvention,
     )
 }

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

@@ -0,0 +1,33 @@
+groups:
+  - id: attributes
+    prefix: "foo"
+    type: attribute_group
+    brief: Attribute group
+    attributes:
+      - id: bar
+        type: string
+        requirement_level: 
+          recommended: if available
+        brief: Attribute 1
+        examples: ['baz']
+
+  - id: derived_attributes
+    type: attribute_group
+    extends: attributes
+    prefix: "foo"
+    brief: Derived attribute group
+    attributes:
+      - id: qux
+        type: int
+        requirement_level: 
+          conditionally_required: if available
+        brief: Attribute 2
+        examples: [42]
+
+  - id: span_attribute_group
+    prefix: ""
+    type: span
+    brief: A span
+    attributes:
+      - ref: foo.bar
+      - ref: foo.qux

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

@@ -0,0 +1,8 @@
+# Attribute Group Example
+
+<!-- semconv span_attribute_group -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `foo.bar` | string | Attribute 1 | `baz` | Recommended: if available |
+| `foo.qux` | int | Attribute 2 | `42` | Conditionally Required: if available |
+<!-- endsemconv -->

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

@@ -0,0 +1,4 @@
+# Attribute Group Example
+
+<!-- semconv span_attribute_group -->
+<!-- endsemconv -->

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

@@ -129,6 +129,9 @@ def testSamplingRelevant(self):
     def test_scope(self):
         self.check("markdown/scope/")
 
+    def test_attribute_group(self):
+        self.check("markdown/attribute_group/")
+
     def check(
         self,
         input_dir: str,

semantic-conventions/syntax.md

@@ -45,10 +45,11 @@ semconv ::= id [convtype] brief [note] [prefix] [extends] [stability] [deprecate
 id    ::= string
 
 convtype ::= "span" # Default if not specified
-         |   "resource" # see spanspecificfields
-         |   "event"    # see eventspecificfields
+         |   "resource" # see spanfields
+         |   "event"    # see eventfields
          |   "metric"   # (currently non-functional)
-         |   "scope"
+         |   "scope"    # no specific fields defined
+         |   "attribute_group" # no specific fields defined
 
 brief ::= string
 note  ::= string
@@ -168,6 +169,12 @@ The following is only valid if `type` is `event`:
   If not specified, the `prefix` is used. If `prefix` is empty (or unspecified),
   `name` is required.
 
+#### Attribute group semantic convention
+
+Attribute group (`attribute_group` type) defines a set of attributes that can be 
+declared once and referenced by semantic conventions for different signals, for example spans and logs.
+Attribute groups don't have any specific fields and follow the general `semconv` semantics.
+
 ### Attributes
 
 An attribute is defined by: