Registry manifest and Schema diff #400

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

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

…ed on the message

…cated::Renamed::renamed_to

…method

# Conflicts: # crates/weaver_codegen_test/build.rs

lquerel · 2024-12-19T02:12:37Z

@lmolkova @jsuereth

Note 1: I have addressed most of the feedback. The main task remaining is the removal of change detection for elements other than attributes. That will be done soon.

Note 2: I will also write a document describing: the format of the schema diff, examples of what can be done with it, the current limitations, and ideas for future development.

I have a question regarding the format of the new deprecated field. In the current version of this PR, a deprecated field can take one of the following three forms:

Old approach (still supported for compatibility reasons):

deprecated: "deprecation message"

or

deprecated:
  action: renamed
  renamed_to: attribute_name

or

deprecated:
  action: deprecated

With this, we can handle simple attribute renaming scenarios, as well as merge scenarios (e.g., A and B are renamed to C; Weaver will detect this automatically). However, we currently have no way to represent a split (e.g., A is renamed to B and C). So with the current implementation, the semconv author will need to set deprecated to action: deprecated and provide a note at the object level to explain the split in textual form.

We could make this explicit in the format of the deprecated field and in the diff output. This would allow for migration documentation that more accurately reflects the desired changes. However, it still wouldn’t enable automatic downgrades in the schema processor for the split scenario (at least without logic taking into account some additional context).

Question: Adding such an advanced definition for the deprecated field isn’t particularly complicated, so I don’t mind including it. What do you think? Are there other types of deprecations you’d like to codify?

…ng data model.

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.

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

lquerel added 6 commits December 18, 2024 17:09

feat(diff): Remove complex logic infering the type of deprecation bas…

8dcd311

…ed on the message

feat(diff): Rename the field Deprecated::Renamed::new_name into Depre…

b58d200

…cated::Renamed::renamed_to

chore(doc): Fix documentation of the ResolvedTelemetrySchema::groups …

a1ab93a

…method

chore(doc): Fix documentation based on @jsuereth feedback

396450f

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

12c79c2

# Conflicts: # crates/weaver_codegen_test/build.rs

chore(merge): Merge with upstream main branch

0a63cd8

lquerel added 5 commits December 30, 2024 08:11

Merge branch 'main' into generate-otel-schema

e067b7f

feat(diff): Documentation of the schema diff command and the underlyi…

80121f5

…ng data model.

feat(diff): Compute a diff only on the registry attributes.

dbe4316

Merge branch 'main' into generate-otel-schema

7e0a813

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

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

lquerel commented Dec 19, 2024 •

edited

Loading

lmolkova Jan 6, 2025

lquerel Jan 6, 2025

lmolkova Jan 6, 2025

lquerel Jan 6, 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

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

lquerel commented Dec 19, 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

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

lquerel commented Oct 3, 2024 •

edited

Loading

lquerel commented Dec 19, 2024 •

edited

Loading