From 3b9a9d35395e702cf1d97a457e7d3c1ffd91e74f Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 13 Dec 2022 00:08:25 -0800 Subject: [PATCH] Add attribute_group type to share attributes across signals (#124) Fixes https://github.com/open-telemetry/build-tools/issues/123 Co-authored-by: Armin Ruech --- semantic-conventions/CHANGELOG.md | 3 +- semantic-conventions/semconv.schema.json | 3 +- .../semconv/model/semantic_convention.py | 5 +++ .../attribute_group/attribute_group.yaml | 33 +++++++++++++++++++ .../data/markdown/attribute_group/expected.md | 8 +++++ .../data/markdown/attribute_group/input.md | 4 +++ .../tests/semconv/templating/test_markdown.py | 3 ++ semantic-conventions/syntax.md | 13 ++++++-- 8 files changed, 67 insertions(+), 5 deletions(-) create mode 100644 semantic-conventions/src/tests/data/markdown/attribute_group/attribute_group.yaml create mode 100644 semantic-conventions/src/tests/data/markdown/attribute_group/expected.md create mode 100644 semantic-conventions/src/tests/data/markdown/attribute_group/input.md diff --git a/semantic-conventions/CHANGELOG.md b/semantic-conventions/CHANGELOG.md index b110419b..5efc4bae 100644 --- a/semantic-conventions/CHANGELOG.md +++ b/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 diff --git a/semantic-conventions/semconv.schema.json b/semantic-conventions/semconv.schema.json index 9c9dd991..862c4b73 100644 --- a/semantic-conventions/semconv.schema.json +++ b/semantic-conventions/semconv.schema.json @@ -52,7 +52,8 @@ "resource", "metric", "event", - "scope" + "scope", + "attribute_group" ], "description": "The (signal) type of the semantic convention" }, diff --git a/semantic-conventions/src/opentelemetry/semconv/model/semantic_convention.py b/semantic-conventions/src/opentelemetry/semconv/model/semantic_convention.py index 2f520732..1deda606 100644 --- a/semantic-conventions/src/opentelemetry/semconv/model/semantic_convention.py +++ b/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, ) } diff --git a/semantic-conventions/src/tests/data/markdown/attribute_group/attribute_group.yaml b/semantic-conventions/src/tests/data/markdown/attribute_group/attribute_group.yaml new file mode 100644 index 00000000..9aee0e17 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/semantic-conventions/src/tests/data/markdown/attribute_group/expected.md b/semantic-conventions/src/tests/data/markdown/attribute_group/expected.md new file mode 100644 index 00000000..82b4e34e --- /dev/null +++ b/semantic-conventions/src/tests/data/markdown/attribute_group/expected.md @@ -0,0 +1,8 @@ +# Attribute Group Example + + +| 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 | + diff --git a/semantic-conventions/src/tests/data/markdown/attribute_group/input.md b/semantic-conventions/src/tests/data/markdown/attribute_group/input.md new file mode 100644 index 00000000..d359000f --- /dev/null +++ b/semantic-conventions/src/tests/data/markdown/attribute_group/input.md @@ -0,0 +1,4 @@ +# Attribute Group Example + + + diff --git a/semantic-conventions/src/tests/semconv/templating/test_markdown.py b/semantic-conventions/src/tests/semconv/templating/test_markdown.py index 618f08e8..aeb6a174 100644 --- a/semantic-conventions/src/tests/semconv/templating/test_markdown.py +++ b/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, diff --git a/semantic-conventions/syntax.md b/semantic-conventions/syntax.md index abc746c6..5448b7b3 100644 --- a/semantic-conventions/syntax.md +++ b/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: