Registry manifest and Schema diff #400

lquerel · 2024-10-03T01:11:52Z

IMPORTANT NOTE: At the moment, the only important part to review is the document docs/schema-changes-use-cases.md, which is also available in a more readable format here.

https://github.com/open-telemetry/weaver/blob/1388d1e3b7200cefda95769a2e3f3d298a1957db/docs/schema-changes-use-cases.md

Note: The scope of this PR has been reduced to focus only focus on the schema diff feature. Github issues have been created to track the features that have been postponed #482, #483.

This PR implements the command registry diff, see the following example:

cargo run -- registry diff -r https://github.com/open-telemetry/semantic-conventions/archive/refs/tags/v1.27.0.zip[model] --baseline-registry https://github.com/open-telemetry/semantic-conventions/archive/refs/tags/v1.26.0.zip[model] --diff-format markdown

In this example, the diff is displayed in markdown format. The following formats are supported: json, yaml, markdown, ansi, ansi_stats

A detailed description of the schema diff data model and the diffing process is visible here.

Notes:

The crate weaver_otel_schema is not essential for this PR; it was initially included as part of the preparations for the registry schema-update command. We have decided to implement this command in a future PR. However, for simplicity, I prefer to keep the preparation code in place instead of removing it. Same thing for all_changes in weaver_version.

List of modifications to apply to the semantic conventions repository after the release of the Weaver containing the current PR:

Add a registry-manifest.yaml file with the version of the next release.
Update all deprecated fields.

Closes: #186

crates/weaver_semconv/src/manifest.rs

# Conflicts: # crates/weaver_semconv/src/group.rs

crates/weaver_semconv/src/deprecated.rs

crates/weaver_resolved_schema/src/lib.rs

src/registry/mod.rs

src/registry/update_schema.rs

# Conflicts: # .clippy.toml # Cargo.toml # crates/weaver_semconv_gen/src/lib.rs # src/registry/search.rs # src/registry/stats.rs # src/registry/update_markdown.rs

crates/weaver_resolved_schema/src/lib.rs

Co-authored-by: Jeremy Blythe <[email protected]>

…l-weaver into generate-otel-schema

…cies to be part of the public API.

lmolkova · 2025-01-06T18:59:11Z

docs/schema-changes.md

+  semconv_version: v1.26.0
+changes:
+  attributes:
+    - type: deprecated


nit and personal taste, so definitely not blocking

having

- name: http.server_name type: deprecated

looks more readable to me, maybe because it's closer to how we write attribute definitions.

Ok I will make this change in the documentation.

docs/usage.md

lmolkova · 2025-01-06T19:14:13Z

docs/schema-changes.md

+  and the deprecation note is stored in the note attribute.
+- `removed`: An item in the baseline registry was removed in the head
+  registry. The name of the removed item is stored in the name attribute.
+


we'll eventually need a way to describe other (breaking) changes such as attribute type, metric unit or instrument change.

Maybe we can add other category that would be used for change types that we don't formally support yet? This would allow someone to look at the diff and understand that there was some change and maybe some manual intervention is necessary.
Otherwise, the lack of any mention could be perceived as 'there was no change, all looks good and compatible'.

I will add a note and describe how this could be represented as a potential future extension.

jsuereth

Still haven't finished some of the more mechanical parts, but did review the diff algorithm, deserialization core code.

I think we have an issue around attribute identity we may need to solve. PTAL at comments.

jsuereth · 2025-01-07T12:27:29Z

crates/weaver_common/src/result.rs

+    }
+
+    /// Returns the number of non-fatal errors, or 1 if the result is a fatal error, 0 otherwise.
+    pub fn error_count(&self) -> usize {


nit: Should we use num_errors?

jsuereth · 2025-01-07T12:27:51Z

crates/weaver_forge/expected_output/test/resource/library.md

@@ -22,7 +22,7 @@ Brief: Span attributes used by non-OTLP exporters to represent OpenTelemetry Sco
 - Examples: [
    "io.opentelemetry.contrib.mongodb",
 ]
- Deprecated: use the `otel.scope.name` attribute.
+- Deprecated: 


Should this test be updated?

jsuereth · 2025-01-07T12:29:14Z

crates/weaver_forge/templates/test/resource.md

@@ -39,7 +39,7 @@ Brief: {{ resource.brief }}
 - Sampling relevant: {{ attribute.sampling_relevant }}
  {%- endif %}
  {%- if attribute.deprecated %}
- Deprecated: {{ attribute.deprecated }}
+- Deprecated: {{ attribute.deprecated.note }}


We probably need to put this in the changelog or have some kind of migration guide for this then.

jsuereth · 2025-01-07T12:32:58Z

crates/weaver_resolved_schema/src/attribute.rs

+    /// Creates a new string attribute.
+    /// Note: This constructor is used for testing purposes.
+    #[cfg(test)]
+    pub(crate) fn string<S: AsRef<str>>(name: S, brief: S, note: S) -> Self {


Nit: name, brief and note would have to be the same concrete type for this helper function.

You should either have three different type parameters for them or use something like impl Into<String>.

Good catch. I like the proposal.

jsuereth · 2025-01-07T12:34:20Z

crates/weaver_resolved_schema/src/attribute.rs

+
+    /// Sets the deprecated field of the attribute.
+    /// Note: This method is used for testing purposes.
+    #[cfg(test)]


I like these helper methods. May replicate the pattern elsewhere.

jsuereth · 2025-01-07T12:40:46Z

crates/weaver_resolved_schema/src/lib.rs

+
+    /// Get the attributes of the resolved telemetry schema.
+    #[must_use]
+    pub fn attribute_map(&self) -> HashMap<&str, &Attribute> {


I think there's some faulty assumptions here.

This assumes that all Attributes MUST show up in an attribute group. That is true for Semantic Conventions (due to custom policy), but not enforced by weaver.

This assumes that all attribute groups are registries. This is not true for Semantic Conventions. We have some attribute groups that just "share" attributes for other non-attribute groups. These may be selected before the registry attributes.

Sadly, I think we likely need a more rigid identifier here than name. I haven't had a chance to look through the rest of the code for implications, but I don't think we can rely on this method to only give us unique attributes or attributes from the registry.

jsuereth · 2025-01-07T12:41:28Z

crates/weaver_resolved_schema/src/lib.rs

+    ///
+    /// Note: At the moment (2024-12-30), I don't know a better way to identify
+    /// the "registry" attributes other than by checking if the group ID starts
+    /// with "registry.".


This is because "registry" is a semantic convention concept, not a weaver one. Should we elevate this to weaver itself?

jsuereth · 2025-01-07T12:42:10Z

crates/weaver_resolved_schema/src/lib.rs

+
+    /// Get the groups of a specific type from the resolved telemetry schema.
+    #[must_use]
+    pub fn groups(&self, group_type: GroupType) -> HashMap<String, &Group> {


nit: Any reason why this one uses String instead of &str like the other helpers?

jsuereth · 2025-01-07T12:51:54Z

crates/weaver_semconv/src/registry.rs

        semconv_specs: Vec<(String, SemConvSpec)>,
-    ) -> SemConvRegistry {
+    ) -> Result<SemConvRegistry, Error> {
+        static VERSION_REGEX: LazyLock<Regex> =


Nit: We should use: https://docs.rs/semver/latest/semver/ and URL parser that can give us the last element of the path to send to the parser.

github-advanced-security

clippy found more than 20 potential problems in the proposed changes. Check the Files changed tab for more details.

jerbly · 2025-01-22T00:33:11Z

docs/schema-changes-use-cases.md

+```yaml
+# Version n+1
+groups:
+  - id: registry.network.deprecated
+    type: attribute_group
+    attributes:
+      - id: net.peer.name
+        type: string
+        brief: Deprecated, use `server.address` on client spans and `client.address` on server spans.
+        deprecated:
+          type: conditionally_renamed
+          forward: >
+            switch span_kind {
+              case 'client' => attributes['server.address'] = attributes['net.peer.name'],
+              case 'server' => attributes['client.address'] = attributes['net.peer.name']
+            }
+          backward: >
+            switch span_kind {
+              case 'client' => attributes['net.peer.name'] = attributes['server.address'],
+              case 'server' => attributes['net.peer.name'] = attributes['client.address']
+            }
+        stability: experimental
+        examples: ['example.com']
+```


In this example, the attribute has been deprecated in the attribute_group but the condition is related to its usage in a span. Should the forward / backward instructions be on the span definition where net.peer.name is referenced? There may be different instructions for different spans that use net.peer.name.

Good point. It's a good topic for discussion for our next Semantic Conventions Tooling SIG.

jerbly · 2025-01-22T01:11:10Z

docs/schema-changes-use-cases.md

+```yaml
+# Version n+1
+groups:
+  - id: registry.db.deprecated
+    type: attribute_group
+    stability: experimental
+    attributes:
+      - id: db.instance.id
+        type: string
+        brief: 'Deprecated, no general replacement at this time. For Elasticsearch, use `db.elasticsearch.node.name` instead.'
+        deprecated:
+          type: conditionally_deprecated
+          forward: >
+            if attributes['db.system'] == 'elasticsearch' then attributes['db.elasticsearch.node.name'] = attributes['db.instance.id']
+            else drop attributes['db.instance.id']
+          backward: >
+            if attributes['db.system'] == 'elasticsearch' then attributes['db.instance.id'] = attributes['db.elasticsearch.node.name']
+        stability: experimental
+```


Like my previous comment. When the instructions involve other attributes then the change is dependent on the presence of those attributes in that signal definition. Perhaps defining the instructions on the attribute_group means it's universal for all uses via references? Maybe this can be overridden with further instructions on the span, for example, to deviate from this default?

Yes, in the attribute_group, the setting is intended to be universal. However, I agree that we should demonstrate how this setting can be overridden when dealing with a specific signal.

docs/schema-changes-use-cases.md

feat(semconv): create registry manifest

edab834

lquerel self-assigned this Oct 3, 2024

lquerel added the enhancement New feature or request label Oct 3, 2024

github-advanced-security bot found potential problems Oct 3, 2024

View reviewed changes

lquerel added 3 commits October 4, 2024 10:22

feat(schema): Parse OTEL schema 1.1

fe7d7b5

feat(cli): Add registry diff command (WIP)

76db2aa

Merge branch 'main' into generate-otel-schema

ad77910

lquerel mentioned this pull request Oct 7, 2024

Automate schema-next generation open-telemetry/semantic-conventions#1426

Open

lquerel added 3 commits October 16, 2024 18:33

feat(schema): Support new deprecated field format

6de07ee

Merge remote-tracking branch 'upstream/main' into generate-otel-schema

5efe6b1

# Conflicts: # crates/weaver_semconv/src/group.rs

feat(diff): Add registry diff command.

6cdfbfa

github-advanced-security bot found potential problems Oct 23, 2024

View reviewed changes

feat(diff): Add diff for metrics

880649f

github-advanced-security bot found potential problems Oct 24, 2024

View reviewed changes

crates/weaver_resolved_schema/src/lib.rs Fixed Show fixed Hide fixed

crates/weaver_resolved_schema/src/lib.rs Fixed Show fixed Hide fixed

lquerel added 2 commits October 24, 2024 16:19

feat(diff): Add diff for events, spans, and resources

a87807b

feat(diff): Add template rendering capability

8f8bdaf

github-advanced-security bot found potential problems Oct 25, 2024

View reviewed changes

src/registry/mod.rs Fixed Show fixed Hide fixed

src/registry/mod.rs Fixed Show fixed Hide fixed

feat(diff): Add diff-format for ansi, ansi-stats, json, and yaml

a818f4e

lquerel mentioned this pull request Oct 28, 2024

Diff between two versions of a semconv registry - Proposal #432

Open

lquerel added 6 commits October 29, 2024 11:57

feat(diff): Add diff-format for markdown

05256ea

chore(diff): Fix unit tests

c584f30

feat(cli): Prepare registry update-schema command

374def2

Merge branch 'main' into generate-otel-schema

1b7c9c2

feat(cli): Prepare registry update-schema command

2abd024

feat(cli): Prepare registry update-schema command

83f45eb

github-advanced-security bot found potential problems Oct 31, 2024

View reviewed changes

jsuereth mentioned this pull request Nov 25, 2024

[Project Tracking] Prototype and Proposal for Milestone 1 - Fully resolved registry / telemetry schema #13

Open

5 tasks

lquerel changed the title ~~[WIP] Registry manifest and OTEL schema update~~ [WIP] Registry manifest and Schema diff Nov 27, 2024

lquerel added 2 commits December 1, 2024 16:45

chore(typo): fix typo in comment

6312e42

Merge remote-tracking branch 'upstream/main' into generate-otel-schema

6532bf3

# Conflicts: # .clippy.toml # Cargo.toml # crates/weaver_semconv_gen/src/lib.rs # src/registry/search.rs # src/registry/stats.rs # src/registry/update_markdown.rs

feat(diff): Use the group.id as unique identifier for the groups.

bfdcfa9

lquerel marked this pull request as ready for review December 30, 2024 23:45

lquerel requested a review from a team as a code owner December 30, 2024 23:45

lquerel changed the title ~~[WIP] Registry manifest and Schema diff~~ Registry manifest and Schema diff Dec 30, 2024

lquerel requested review from jsuereth and lmolkova December 30, 2024 23:48

jerbly reviewed Jan 1, 2025

View reviewed changes

crates/weaver_resolved_schema/src/lib.rs Show resolved Hide resolved

jerbly reviewed Jan 1, 2025

View reviewed changes

crates/weaver_resolved_schema/src/lib.rs Show resolved Hide resolved

lquerel and others added 7 commits January 2, 2025 07:54

feat(diff): Update unit tests to check deprecated attributes

e258547

Update crates/weaver_resolved_schema/src/lib.rs

eef3eff

Co-authored-by: Jeremy Blythe <[email protected]>

Update crates/weaver_resolved_schema/src/lib.rs

619c885

Co-authored-by: Jeremy Blythe <[email protected]>

Merge branch 'generate-otel-schema' of https://github.com/lquerel/ote…

b4c49e7

…l-weaver into generate-otel-schema

chore: Merge with main upstream

99b725d

chore(build): Update allowed_external_types to allow classic dependen…

0f430a8

…cies to be part of the public API.

chore(build): Update allowed_external_types to allow classic dependen…

78bfb77

…cies to be part of the public API.

lmolkova reviewed Jan 6, 2025

View reviewed changes

docs/usage.md Show resolved Hide resolved

lmolkova reviewed Jan 6, 2025

View reviewed changes

jsuereth reviewed Jan 7, 2025

View reviewed changes

Merge branch 'main' into generate-otel-schema

98b7ad5

github-advanced-security bot found potential problems Jan 17, 2025

View reviewed changes

lquerel added 4 commits January 17, 2025 09:01

chore(merge): Fix merge issue with main with main branch.

06f3d19

feat(schema-diff): Describe various situations of schema changes.

8fbdf8f

feat(schema-diff): Describe various situations of schema changes.

ab7936d

feat(schema-diff): Update schema changes intro

33fefc7

jerbly reviewed Jan 22, 2025

View reviewed changes

docs/schema-changes-use-cases.md Outdated Show resolved Hide resolved

lquerel added 2 commits January 21, 2025 18:22

feat(schema-diff): Update schema changes intro

a141296

chore(doc): Update document talking about schema changes

1388d1e

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Registry manifest and Schema diff #400

Registry manifest and Schema diff #400

lquerel commented Oct 3, 2024 •

edited

Loading

lmolkova Jan 6, 2025

lquerel Jan 6, 2025

lmolkova Jan 6, 2025

lquerel Jan 6, 2025

lquerel Jan 22, 2025

jsuereth left a comment

jsuereth Jan 7, 2025

jsuereth Jan 7, 2025

jsuereth Jan 7, 2025

jsuereth Jan 7, 2025

lquerel Jan 8, 2025

jsuereth Jan 7, 2025

jsuereth Jan 7, 2025

jsuereth Jan 7, 2025

jsuereth Jan 7, 2025

jsuereth Jan 7, 2025

github-advanced-security bot left a comment

jerbly Jan 22, 2025

lquerel Jan 22, 2025

jerbly Jan 22, 2025

lquerel Jan 22, 2025

Registry manifest and Schema diff #400

Are you sure you want to change the base?

Registry manifest and Schema diff #400

Conversation

lquerel commented Oct 3, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jsuereth left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-advanced-security bot left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lquerel commented Oct 3, 2024 •

edited

Loading