From 0b342bb5d613f64dae1d936257a200f527ed3565 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 23 Apr 2024 17:44:26 -0700 Subject: [PATCH 1/7] Document patterns and suggestions for semconv code generation --- .../semantic_conventions_code_generation.md | 94 +++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 supplementary-guidelines/semantic_conventions_code_generation.md diff --git a/supplementary-guidelines/semantic_conventions_code_generation.md b/supplementary-guidelines/semantic_conventions_code_generation.md new file mode 100644 index 0000000000..03974d0a34 --- /dev/null +++ b/supplementary-guidelines/semantic_conventions_code_generation.md @@ -0,0 +1,94 @@ +# Semantic convention libraries + +The code for OpenTelemetry semantic conventions defined in this repository can be auto-generated. + +OpenTelemetry Language SIGs can auto-generate semantic conventions code in the form that's idiomatic for +their language and may (or may not) ship semantic-conventions as a stand-alone library. + +This document outlines common patters and provides non-normative guidance on how to implement auto-generation +and structure semantic conventions artifact. + +## Generating semantic conventions + + +The generation is done using [build-tools code generator](https://github.com/open-telemetry/build-tools/blob/main/semantic-conventions/README.md#code-generator). +It's based on YAML definitions of the semantic conventions and uses [Jinja templates](https://palletsprojects.com/p/jinja/). + +For example, this Jinja template can be used to generate Python constant for an attribute name along with the docstring. + +```jinja +{{attribute.fqn | to_const_name}} = "{{attribute.fqn}}" +""" +{{attribute.brief | to_doc_brief}}. +{%- if attribute.note %} +Note: {{attribute.note | to_doc_brief | indent}}. +{%- endif %} +""" +``` + +It generates the following code: + +```python +SERVER_ADDRESS = "server.address" +""" +Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. +Note: When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. +""" +``` + +Language SIGs are expected to create Jinja templates specific to their language. +Code-generation usually involves several steps which could be semi-automated: + +1. Manually update the Semantic Conventions version when necessary +2. Add the new Schema URL to the list of supported versions + - If it's not automated, then it can, at least, be automatically checked. +4. Check out (or download) this version of Semantic Conventions +5. Run code-generation script for each template +6. Fix lint violations in the auto-generated code (if any) +7. Send the PR with new code to the corresponding repository + +Here're the examples of how steps 2-5 are implemented for [Java](https://github.com/open-telemetry/semantic-conventions-java/blob/7da24068eea69dff11a78d59750b115dc4c5854d/build.gradle.kts#L55-L137) and [Python](https://github.com/open-telemetry/opentelemetry-python/blob/23f67971a4c147b8586c3fe6a68c9cfb0f5d7362/scripts/semconv/generate.sh). + +## Stability and versioning + +Semantic Conventions contain a mix of stability levels. +Language SIGs that ship semantic conventions library may decide to ship a stable artifact with stable part of the Semantic Conventions, a preview artifact with all Semantic Conventions, or other combination that's idiomatic for this language and provides [SemVer 2.0](https://semver.org/) stability guarantees. + +> Note: +> Shipping two versions of the same artifact (stable and preview) could be problematic if dependency resolution mechanism is based on the latest version. +> For example, if user application depends on the `semconv v1.0.0-preview` and some library brings transitive dependency on `semconv v1.1.0`, the latter would be resolved leading +> to compile or runtime issues in the application. +> Shipping two artifacts with different names is recommended for the ecosystems that are prone to diamond-dependency conflicts. + +Other possible solutions include: + +- Generate all semantic conventions for a given version in specific folder while keeping old versions. It is used by [opentelemetry-go](https://github.com/open-telemetry/opentelemetry-go/tree/main/semconv/) but could be problematic if the artifact size is a concern. +- Follow language-specific conventions to annotate experimental parts. For example, Semantic Conventions in Python keeps experimental attributes in `opentelemetry.semconv._incubating` import path which is considered (following Python underscore convention) to be internal and subject to change. + +### Recommendations + +- Generate code for deprecated attributes, metrics, and other conventions (even if they never reached stability). It minimizes runtime issues and breaking changes in user applications. Use appropriate annotations to mark deprecated conventions. All deprecated conventions should have `deprecated` property describing new alternatives (when available) which can be used in auto-generated code documentation. +- Generate code for stable convention inside incubating artifact. It prevents user code from breaking when semantic convention stabilizes. Deprecate stable definitions inside incubating artifact and point users to the stable location. +- Instrumentation libraries should depend on the stable semantic convention artifact or copy relevant definitions and keep them in their code base. Incubating artifact is intended for the end-users. + +## Semantic Conventions Artifact Structure + +This section contains suggestion on structuring semantic convention artifact(s) which should be adjusted to the specific language. + +- Artifact name: `opentelemetry-semconv` and `opentelemetry-semconv-incubating` (if shipping incubating artifact) +- Namespace: `opentelemetry.semconv` and `opentelemetry.semconv.incubating` +- All supported Schema URLs should be listed to allow different instrumentations in one process to provide the exact version of conventions they follow. +- Attributes, metrics, and other convention definitions should be grouped by the convention type and the root namespace. See the example below: + +``` +├── SchemaURLs.* +├── attributes +│ ├── ClientAttributes.* +│ ├── HttpAttributes.* +│ └── ... +├── metrics +│ ├── HttpMetrics.* +│ └── ... +└── events + └── ... +``` \ No newline at end of file From f09701f1602fe604e2cd27fe9c58974c8b824324 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 24 Apr 2024 21:11:59 -0700 Subject: [PATCH 2/7] clean up and move tooling part to the end --- .../semantic_conventions_code_generation.md | 134 +++++++++++------- 1 file changed, 79 insertions(+), 55 deletions(-) diff --git a/supplementary-guidelines/semantic_conventions_code_generation.md b/supplementary-guidelines/semantic_conventions_code_generation.md index 03974d0a34..cb69bcd993 100644 --- a/supplementary-guidelines/semantic_conventions_code_generation.md +++ b/supplementary-guidelines/semantic_conventions_code_generation.md @@ -1,16 +1,84 @@ # Semantic convention libraries -The code for OpenTelemetry semantic conventions defined in this repository can be auto-generated. + -OpenTelemetry Language SIGs can auto-generate semantic conventions code in the form that's idiomatic for -their language and may (or may not) ship semantic-conventions as a stand-alone library. +- [Stability and versioning](#stability-and-versioning) + - [Recommendations](#recommendations) +- [Semantic Conventions Artifact Structure](#semantic-conventions-artifact-structure) +- [Generating semantic conventions](#generating-semantic-conventions) -This document outlines common patters and provides non-normative guidance on how to implement auto-generation -and structure semantic conventions artifact. + + +The code for OpenTelemetry Semantic Conventions defined in this repository can be auto-generated. + +OpenTelemetry Language SIGs can generate Semantic Conventions code in the form that's idiomatic for +their language and may (or may not) ship it as a stand-alone library. + +This document outlines common patterns and provides non-normative guidance on how to structure semantic conventions artifact +and generate the code. + +## Stability and versioning + +Semantic Conventions contain a mix of stability levels. +Language SIGs that ship semantic conventions library may decide to ship a stable artifact with stable part of the Semantic Conventions, an experimental artifact with all Semantic Conventions, or other combination that's idiomatic for this language and provides [SemVer 2.0](https://semver.org/) stability guarantees. + +Possible solutions include: + +- Generate all Semantic Conventions for a given version in specific folder while keeping old versions intact. It is used by [opentelemetry-go](https://github.com/open-telemetry/opentelemetry-go/tree/main/semconv/) but could be problematic if the artifact size is a concern. +- Follow language-specific conventions to annotate experimental parts. For example, Semantic Conventions in Python puts experimental attributes in `opentelemetry.semconv._incubating` import path which is considered (following Python underscore convention) to be internal and subject to change. +- Ship two different artifacts: one that contains stable Semantic Conventions only, another one that contains all conventions. + +> Note: +> Shipping two versions of the same artifact (stable and preview) could be problematic due to diamond-dependency problems. +> For example, if user application depends on the `semconv v1.0.0-preview` and some library brings transitive dependency on `semconv v1.1.0`, the latter would be resolved leading +> to compile or runtime issues in the application. + +## Semantic Conventions Artifact Structure + +This section contains suggestion on structuring semantic convention artifact(s) which should be adjusted to the specific language. + +- Artifact name(s): + - `opentelemetry-semconv` for the stable conventions + - `opentelemetry-semconv-incubating` for the incubating one that contains all conventions +- Namespace: `opentelemetry.semconv` and `opentelemetry.semconv.incubating` +- All supported Schema URLs should be listed to allow different instrumentations in one application to provide the exact version of conventions they follow. +- Attributes, metrics, and other convention definitions should be grouped by the convention type and the root namespace. See the example below: + +``` +├── SchemaUrls.code +├── attributes +│ ├── ClientAttributes.code +│ ├── HttpAttributes.code +│ └── ... +├── metrics +│ ├── HttpMetrics.code +│ └── ... +└── events + └── ... +``` + +### Recommendations + +Generate code for deprecated attributes, metrics, and other conventions. Use appropriate annotations to mark deprecated conventions. +Conventions have a `stability` property which documents if the convention was ever stabilized and the `deprecated` property that +provides alternatives (when available) and can be used to generated code documentation. + +- Deprecated conventions that reached stability should not be removed without major version update according to SemVer. +- Conventions that were deprecated while being experimental should still be generated and kept in the incubating artifact. It minimizes runtime issues + and breaking changes in user applications. + + +Keep stable convention definitions inside incubating artifact (or incubating parts). It prevents user code from breaking when semantic convention stabilizes. Deprecate stable definitions inside incubating artifact and point users to the stable location. +For example, in Java `http.request.method` attribute is defined as deprecated `io.opentelemetry.semconv.incubating.HttpIncubatingAttributes.HTTP_REQUEST_METHOD` as well as `io.opentelemetry.semconv.HttpAttributes.HTTP_REQUEST_METHOD`. + +Instrumentation libraries should depend on the stable semantic convention artifact or copy relevant definitions and keep them in their code base. Incubating artifact is intended for the end-users. ## Generating semantic conventions - +> Note: +> The tooling used for code generation may change to [opentelemetry-weaver](https://github.com/open-telemetry/weaver), +> without any breaking changes in the generated code and with minimal changes to generation process and templates. + The generation is done using [build-tools code generator](https://github.com/open-telemetry/build-tools/blob/main/semantic-conventions/README.md#code-generator). It's based on YAML definitions of the semantic conventions and uses [Jinja templates](https://palletsprojects.com/p/jinja/). @@ -42,53 +110,9 @@ Code-generation usually involves several steps which could be semi-automated: 1. Manually update the Semantic Conventions version when necessary 2. Add the new Schema URL to the list of supported versions - If it's not automated, then it can, at least, be automatically checked. -4. Check out (or download) this version of Semantic Conventions -5. Run code-generation script for each template -6. Fix lint violations in the auto-generated code (if any) -7. Send the PR with new code to the corresponding repository +3. Check out (or download) this version of Semantic Conventions +4. Run code-generation script for each template +5. Fix lint violations in the auto-generated code (if any) +6. Send the PR with new code to the corresponding repository -Here're the examples of how steps 2-5 are implemented for [Java](https://github.com/open-telemetry/semantic-conventions-java/blob/7da24068eea69dff11a78d59750b115dc4c5854d/build.gradle.kts#L55-L137) and [Python](https://github.com/open-telemetry/opentelemetry-python/blob/23f67971a4c147b8586c3fe6a68c9cfb0f5d7362/scripts/semconv/generate.sh). - -## Stability and versioning - -Semantic Conventions contain a mix of stability levels. -Language SIGs that ship semantic conventions library may decide to ship a stable artifact with stable part of the Semantic Conventions, a preview artifact with all Semantic Conventions, or other combination that's idiomatic for this language and provides [SemVer 2.0](https://semver.org/) stability guarantees. - -> Note: -> Shipping two versions of the same artifact (stable and preview) could be problematic if dependency resolution mechanism is based on the latest version. -> For example, if user application depends on the `semconv v1.0.0-preview` and some library brings transitive dependency on `semconv v1.1.0`, the latter would be resolved leading -> to compile or runtime issues in the application. -> Shipping two artifacts with different names is recommended for the ecosystems that are prone to diamond-dependency conflicts. - -Other possible solutions include: - -- Generate all semantic conventions for a given version in specific folder while keeping old versions. It is used by [opentelemetry-go](https://github.com/open-telemetry/opentelemetry-go/tree/main/semconv/) but could be problematic if the artifact size is a concern. -- Follow language-specific conventions to annotate experimental parts. For example, Semantic Conventions in Python keeps experimental attributes in `opentelemetry.semconv._incubating` import path which is considered (following Python underscore convention) to be internal and subject to change. - -### Recommendations - -- Generate code for deprecated attributes, metrics, and other conventions (even if they never reached stability). It minimizes runtime issues and breaking changes in user applications. Use appropriate annotations to mark deprecated conventions. All deprecated conventions should have `deprecated` property describing new alternatives (when available) which can be used in auto-generated code documentation. -- Generate code for stable convention inside incubating artifact. It prevents user code from breaking when semantic convention stabilizes. Deprecate stable definitions inside incubating artifact and point users to the stable location. -- Instrumentation libraries should depend on the stable semantic convention artifact or copy relevant definitions and keep them in their code base. Incubating artifact is intended for the end-users. - -## Semantic Conventions Artifact Structure - -This section contains suggestion on structuring semantic convention artifact(s) which should be adjusted to the specific language. - -- Artifact name: `opentelemetry-semconv` and `opentelemetry-semconv-incubating` (if shipping incubating artifact) -- Namespace: `opentelemetry.semconv` and `opentelemetry.semconv.incubating` -- All supported Schema URLs should be listed to allow different instrumentations in one process to provide the exact version of conventions they follow. -- Attributes, metrics, and other convention definitions should be grouped by the convention type and the root namespace. See the example below: - -``` -├── SchemaURLs.* -├── attributes -│ ├── ClientAttributes.* -│ ├── HttpAttributes.* -│ └── ... -├── metrics -│ ├── HttpMetrics.* -│ └── ... -└── events - └── ... -``` \ No newline at end of file +Here're the examples of how steps 2-6 are implemented for [Java](https://github.com/open-telemetry/semantic-conventions-java/blob/7da24068eea69dff11a78d59750b115dc4c5854d/build.gradle.kts#L55-L137) and [Python](https://github.com/open-telemetry/opentelemetry-python/blob/23f67971a4c147b8586c3fe6a68c9cfb0f5d7362/scripts/semconv/generate.sh). \ No newline at end of file From b0fedd0734026d4868ace214eb67e25e17210a0b Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 24 Apr 2024 21:33:13 -0700 Subject: [PATCH 3/7] more clean up and lint --- .../semantic_conventions_code_generation.md | 60 +++++++++---------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/supplementary-guidelines/semantic_conventions_code_generation.md b/supplementary-guidelines/semantic_conventions_code_generation.md index cb69bcd993..50d01be69a 100644 --- a/supplementary-guidelines/semantic_conventions_code_generation.md +++ b/supplementary-guidelines/semantic_conventions_code_generation.md @@ -2,10 +2,10 @@ -- [Stability and versioning](#stability-and-versioning) - - [Recommendations](#recommendations) -- [Semantic Conventions Artifact Structure](#semantic-conventions-artifact-structure) -- [Generating semantic conventions](#generating-semantic-conventions) +* [Stability and Versioning](#stability-and-versioning) + * [Deprecated Conventions](#deprecated-conventions) +* [Semantic Conventions Artifact Structure](#semantic-conventions-artifact-structure) +* [Generating semantic conventions](#generating-semantic-conventions) @@ -17,7 +17,7 @@ their language and may (or may not) ship it as a stand-alone library. This document outlines common patterns and provides non-normative guidance on how to structure semantic conventions artifact and generate the code. -## Stability and versioning +## Stability and Versioning Semantic Conventions contain a mix of stability levels. Language SIGs that ship semantic conventions library may decide to ship a stable artifact with stable part of the Semantic Conventions, an experimental artifact with all Semantic Conventions, or other combination that's idiomatic for this language and provides [SemVer 2.0](https://semver.org/) stability guarantees. @@ -26,22 +26,38 @@ Possible solutions include: - Generate all Semantic Conventions for a given version in specific folder while keeping old versions intact. It is used by [opentelemetry-go](https://github.com/open-telemetry/opentelemetry-go/tree/main/semconv/) but could be problematic if the artifact size is a concern. - Follow language-specific conventions to annotate experimental parts. For example, Semantic Conventions in Python puts experimental attributes in `opentelemetry.semconv._incubating` import path which is considered (following Python underscore convention) to be internal and subject to change. -- Ship two different artifacts: one that contains stable Semantic Conventions only, another one that contains all conventions. +- Ship two different artifacts: one that contains stable Semantic Conventions and another one that contains all conventions. > Note: > Shipping two versions of the same artifact (stable and preview) could be problematic due to diamond-dependency problems. -> For example, if user application depends on the `semconv v1.0.0-preview` and some library brings transitive dependency on `semconv v1.1.0`, the latter would be resolved leading -> to compile or runtime issues in the application. +> For example, if user application depends on the `semconv v1.0.0-preview` and some library brings transitive dependency on `semconv v1.1.0` that does not contain +> experimental convention, the latter would be resolved leading to compilation or runtime issues in the application. + +Instrumentation libraries should depend on the stable (parts of) semantic convention artifact or copy relevant definitions into their own code base. +Incubating parts are intended for the end-users. + +### Deprecated Conventions + +Generate code for deprecated attributes, metrics, and other conventions. Use appropriate annotations to mark them as deprecated. +Conventions have a `stability` property which provide the stability level at the deprecation time (`experimental` or `stable`) and +the `deprecated` property that describes deprecation reason and can be used to generate documentation. + +- Deprecated conventions that reached stability should not be removed without major version update according to SemVer. +- Conventions that were deprecated while being experimental should still be generated and kept in the incubating artifact. It minimizes runtime issues + and breaking changes in user applications. + +Keep stable convention definitions inside incubating artifact (or incubating parts of the artifact). It prevents user code from breaking when semantic convention stabilizes. Deprecate stable definitions inside incubating artifact and point users to the stable location in generated documentation. +For example, in Java `http.request.method` attribute is defined as deprecated `io.opentelemetry.semconv.incubating.HttpIncubatingAttributes.HTTP_REQUEST_METHOD` field and also as stable `io.opentelemetry.semconv.HttpAttributes.HTTP_REQUEST_METHOD`. ## Semantic Conventions Artifact Structure -This section contains suggestion on structuring semantic convention artifact(s) which should be adjusted to the specific language. +This section contains suggestions on structuring semantic convention artifact(s) which should be adjusted to the specific language. -- Artifact name(s): - - `opentelemetry-semconv` for the stable conventions - - `opentelemetry-semconv-incubating` for the incubating one that contains all conventions +- Artifact name: + - `opentelemetry-semconv` - stable conventions + - `opentelemetry-semconv-incubating` - (if applicable) the incubating artifact which contains all conventions - Namespace: `opentelemetry.semconv` and `opentelemetry.semconv.incubating` -- All supported Schema URLs should be listed to allow different instrumentations in one application to provide the exact version of conventions they follow. +- All supported Schema URLs should be listed to allow different instrumentations in the same application to provide the exact version of conventions they follow. - Attributes, metrics, and other convention definitions should be grouped by the convention type and the root namespace. See the example below: ``` @@ -57,22 +73,6 @@ This section contains suggestion on structuring semantic convention artifact(s) └── ... ``` -### Recommendations - -Generate code for deprecated attributes, metrics, and other conventions. Use appropriate annotations to mark deprecated conventions. -Conventions have a `stability` property which documents if the convention was ever stabilized and the `deprecated` property that -provides alternatives (when available) and can be used to generated code documentation. - -- Deprecated conventions that reached stability should not be removed without major version update according to SemVer. -- Conventions that were deprecated while being experimental should still be generated and kept in the incubating artifact. It minimizes runtime issues - and breaking changes in user applications. - - -Keep stable convention definitions inside incubating artifact (or incubating parts). It prevents user code from breaking when semantic convention stabilizes. Deprecate stable definitions inside incubating artifact and point users to the stable location. -For example, in Java `http.request.method` attribute is defined as deprecated `io.opentelemetry.semconv.incubating.HttpIncubatingAttributes.HTTP_REQUEST_METHOD` as well as `io.opentelemetry.semconv.HttpAttributes.HTTP_REQUEST_METHOD`. - -Instrumentation libraries should depend on the stable semantic convention artifact or copy relevant definitions and keep them in their code base. Incubating artifact is intended for the end-users. - ## Generating semantic conventions > Note: @@ -115,4 +115,4 @@ Code-generation usually involves several steps which could be semi-automated: 5. Fix lint violations in the auto-generated code (if any) 6. Send the PR with new code to the corresponding repository -Here're the examples of how steps 2-6 are implemented for [Java](https://github.com/open-telemetry/semantic-conventions-java/blob/7da24068eea69dff11a78d59750b115dc4c5854d/build.gradle.kts#L55-L137) and [Python](https://github.com/open-telemetry/opentelemetry-python/blob/23f67971a4c147b8586c3fe6a68c9cfb0f5d7362/scripts/semconv/generate.sh). \ No newline at end of file +Here're the examples of how steps 2-5 are implemented for [Java](https://github.com/open-telemetry/semantic-conventions-java/blob/7da24068eea69dff11a78d59750b115dc4c5854d/build.gradle.kts#L55-L137) and [Python](https://github.com/open-telemetry/opentelemetry-python/blob/23f67971a4c147b8586c3fe6a68c9cfb0f5d7362/scripts/semconv/generate.sh). From ece169567c0f56de90d4c99830ee7514655101e7 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 24 Apr 2024 21:48:09 -0700 Subject: [PATCH 4/7] lint --- .../semantic_conventions_code_generation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/supplementary-guidelines/semantic_conventions_code_generation.md b/supplementary-guidelines/semantic_conventions_code_generation.md index 50d01be69a..7dbfc0e89c 100644 --- a/supplementary-guidelines/semantic_conventions_code_generation.md +++ b/supplementary-guidelines/semantic_conventions_code_generation.md @@ -2,10 +2,10 @@ -* [Stability and Versioning](#stability-and-versioning) - * [Deprecated Conventions](#deprecated-conventions) -* [Semantic Conventions Artifact Structure](#semantic-conventions-artifact-structure) -* [Generating semantic conventions](#generating-semantic-conventions) +- [Stability and Versioning](#stability-and-versioning) + - [Deprecated Conventions](#deprecated-conventions) +- [Semantic Conventions Artifact Structure](#semantic-conventions-artifact-structure) +- [Generating semantic conventions](#generating-semantic-conventions) From 1ef4d0aa6c65a436600c9c7400a52f37f178e122 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 2 May 2024 13:55:00 -0700 Subject: [PATCH 5/7] changelog --- .chloggen/953.yaml | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 .chloggen/953.yaml diff --git a/.chloggen/953.yaml b/.chloggen/953.yaml new file mode 100644 index 0000000000..b09aa3df1e --- /dev/null +++ b/.chloggen/953.yaml @@ -0,0 +1,7 @@ +change_type: enhancement + +component: other + +note: Document patterns and suggestions for semconv code generation. + +issues: [551, 953] From b5d539d304f2d2377e4263c1d748f1e721780def Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 7 May 2024 13:51:01 -0700 Subject: [PATCH 6/7] use preview instead of incubating --- .../semantic_conventions_code_generation.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/supplementary-guidelines/semantic_conventions_code_generation.md b/supplementary-guidelines/semantic_conventions_code_generation.md index 7dbfc0e89c..a38838e185 100644 --- a/supplementary-guidelines/semantic_conventions_code_generation.md +++ b/supplementary-guidelines/semantic_conventions_code_generation.md @@ -20,33 +20,33 @@ and generate the code. ## Stability and Versioning Semantic Conventions contain a mix of stability levels. -Language SIGs that ship semantic conventions library may decide to ship a stable artifact with stable part of the Semantic Conventions, an experimental artifact with all Semantic Conventions, or other combination that's idiomatic for this language and provides [SemVer 2.0](https://semver.org/) stability guarantees. +Language SIGs that ship semantic conventions library may decide to ship a stable artifact with stable part of the Semantic Conventions, a preview artifact with all Semantic Conventions, or other combination that's idiomatic for this language and provides [SemVer 2.0](https://semver.org/) stability guarantees. Possible solutions include: - Generate all Semantic Conventions for a given version in specific folder while keeping old versions intact. It is used by [opentelemetry-go](https://github.com/open-telemetry/opentelemetry-go/tree/main/semconv/) but could be problematic if the artifact size is a concern. - Follow language-specific conventions to annotate experimental parts. For example, Semantic Conventions in Python puts experimental attributes in `opentelemetry.semconv._incubating` import path which is considered (following Python underscore convention) to be internal and subject to change. -- Ship two different artifacts: one that contains stable Semantic Conventions and another one that contains all conventions. +- Ship two different artifacts: one that contains stable Semantic Conventions and another one that contains all conventions. For example, [semantic-conventions in Java](https://github.com/open-telemetry/semantic-conventions-java) are shipped in two artifacts: `opentelemetry-semconv` and `opentelemetry-semconv-incubating` artifacts. > Note: > Shipping two versions of the same artifact (stable and preview) could be problematic due to diamond-dependency problems. > For example, if user application depends on the `semconv v1.0.0-preview` and some library brings transitive dependency on `semconv v1.1.0` that does not contain > experimental convention, the latter would be resolved leading to compilation or runtime issues in the application. -Instrumentation libraries should depend on the stable (parts of) semantic convention artifact or copy relevant definitions into their own code base. -Incubating parts are intended for the end-users. +Instrumentation libraries should depend on the stable (part of) semantic convention artifact or copy relevant definitions into their own code base. +Experimental semantic conventions are intended for the end-user applications. ### Deprecated Conventions -Generate code for deprecated attributes, metrics, and other conventions. Use appropriate annotations to mark them as deprecated. +It's recommended to generate code for deprecated attributes, metrics, and other conventions. Use appropriate annotations to mark them as deprecated. Conventions have a `stability` property which provide the stability level at the deprecation time (`experimental` or `stable`) and -the `deprecated` property that describes deprecation reason and can be used to generate documentation. +the `deprecated` property that describes deprecation reason which can be used to generate documentation. - Deprecated conventions that reached stability should not be removed without major version update according to SemVer. -- Conventions that were deprecated while being experimental should still be generated and kept in the incubating artifact. It minimizes runtime issues +- Conventions that were deprecated while being experimental should still be generated and kept in the preview (part of) semantic conventions artifact. It minimizes runtime issues and breaking changes in user applications. -Keep stable convention definitions inside incubating artifact (or incubating parts of the artifact). It prevents user code from breaking when semantic convention stabilizes. Deprecate stable definitions inside incubating artifact and point users to the stable location in generated documentation. +Keep stable convention definitions inside the preview (part of) semantic conversions artifact. It prevents user code from breaking when semantic convention stabilizes. Deprecate stable definitions inside the preview artifact and point users to the stable location in generated documentation. For example, in Java `http.request.method` attribute is defined as deprecated `io.opentelemetry.semconv.incubating.HttpIncubatingAttributes.HTTP_REQUEST_METHOD` field and also as stable `io.opentelemetry.semconv.HttpAttributes.HTTP_REQUEST_METHOD`. ## Semantic Conventions Artifact Structure @@ -55,7 +55,7 @@ This section contains suggestions on structuring semantic convention artifact(s) - Artifact name: - `opentelemetry-semconv` - stable conventions - - `opentelemetry-semconv-incubating` - (if applicable) the incubating artifact which contains all conventions + - `opentelemetry-semconv-incubating` - (if applicable) the preview artifact containing all conventions - Namespace: `opentelemetry.semconv` and `opentelemetry.semconv.incubating` - All supported Schema URLs should be listed to allow different instrumentations in the same application to provide the exact version of conventions they follow. - Attributes, metrics, and other convention definitions should be grouped by the convention type and the root namespace. See the example below: @@ -115,4 +115,4 @@ Code-generation usually involves several steps which could be semi-automated: 5. Fix lint violations in the auto-generated code (if any) 6. Send the PR with new code to the corresponding repository -Here're the examples of how steps 2-5 are implemented for [Java](https://github.com/open-telemetry/semantic-conventions-java/blob/7da24068eea69dff11a78d59750b115dc4c5854d/build.gradle.kts#L55-L137) and [Python](https://github.com/open-telemetry/opentelemetry-python/blob/23f67971a4c147b8586c3fe6a68c9cfb0f5d7362/scripts/semconv/generate.sh). +Here're the examples of how steps 2-5 are implemented for [Java](https://github.com/open-telemetry/semantic-conventions-java/blob/7da24068eea69dff11a78d59750b115dc4c5854d/build.gradle.kts#L55-L137) and [Python](https://github.com/open-telemetry/opentelemetry-python/blob/397e357dfad3e6ff42c09c74d5945dfdcad24bdd/scripts/semconv/generate.sh). From aa873eb173d5abd2f34f01c13654e6a5e0213f6b Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 7 May 2024 13:55:05 -0700 Subject: [PATCH 7/7] a few more fixes --- .../semantic_conventions_code_generation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/supplementary-guidelines/semantic_conventions_code_generation.md b/supplementary-guidelines/semantic_conventions_code_generation.md index a38838e185..76436fed77 100644 --- a/supplementary-guidelines/semantic_conventions_code_generation.md +++ b/supplementary-guidelines/semantic_conventions_code_generation.md @@ -26,15 +26,15 @@ Possible solutions include: - Generate all Semantic Conventions for a given version in specific folder while keeping old versions intact. It is used by [opentelemetry-go](https://github.com/open-telemetry/opentelemetry-go/tree/main/semconv/) but could be problematic if the artifact size is a concern. - Follow language-specific conventions to annotate experimental parts. For example, Semantic Conventions in Python puts experimental attributes in `opentelemetry.semconv._incubating` import path which is considered (following Python underscore convention) to be internal and subject to change. -- Ship two different artifacts: one that contains stable Semantic Conventions and another one that contains all conventions. For example, [semantic-conventions in Java](https://github.com/open-telemetry/semantic-conventions-java) are shipped in two artifacts: `opentelemetry-semconv` and `opentelemetry-semconv-incubating` artifacts. +- Ship two different artifacts: one that contains stable Semantic Conventions and another one with all available conventions. For example, [semantic-conventions in Java](https://github.com/open-telemetry/semantic-conventions-java) are shipped in two artifacts: `opentelemetry-semconv` and `opentelemetry-semconv-incubating`. > Note: > Shipping two versions of the same artifact (stable and preview) could be problematic due to diamond-dependency problems. > For example, if user application depends on the `semconv v1.0.0-preview` and some library brings transitive dependency on `semconv v1.1.0` that does not contain -> experimental convention, the latter would be resolved leading to compilation or runtime issues in the application. +> experimental conventions, the latter would be resolved leading to compilation or runtime issues in the application. Instrumentation libraries should depend on the stable (part of) semantic convention artifact or copy relevant definitions into their own code base. -Experimental semantic conventions are intended for the end-user applications. +Experimental semantic conventions are intended for end-user applications. ### Deprecated Conventions @@ -47,7 +47,7 @@ the `deprecated` property that describes deprecation reason which can be used to and breaking changes in user applications. Keep stable convention definitions inside the preview (part of) semantic conversions artifact. It prevents user code from breaking when semantic convention stabilizes. Deprecate stable definitions inside the preview artifact and point users to the stable location in generated documentation. -For example, in Java `http.request.method` attribute is defined as deprecated `io.opentelemetry.semconv.incubating.HttpIncubatingAttributes.HTTP_REQUEST_METHOD` field and also as stable `io.opentelemetry.semconv.HttpAttributes.HTTP_REQUEST_METHOD`. +For example, in Java `http.request.method` attribute is defined as the deprecated `io.opentelemetry.semconv.incubating.HttpIncubatingAttributes.HTTP_REQUEST_METHOD` field and also as stable `io.opentelemetry.semconv.HttpAttributes.HTTP_REQUEST_METHOD`. ## Semantic Conventions Artifact Structure