From e48bd82b78d2e415ecfc1d09351b6dfa5caa2086 Mon Sep 17 00:00:00 2001 From: Laurent Querel Date: Wed, 12 Jun 2024 09:26:28 -0700 Subject: [PATCH] chore(doc): Add new entry in developer guide to describe the process of adding new fields in semconv --- docs/developer-guide.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docs/developer-guide.md b/docs/developer-guide.md index 049ae920..86429e8e 100644 --- a/docs/developer-guide.md +++ b/docs/developer-guide.md @@ -35,3 +35,36 @@ output, simply do the following: ```bash weaver registry resolve -r -o resolved-registry.json ``` + +## Adding a new Semantic Convention Field + +Let's assume that you want to add the field `display_name` to the semantic convention groups. It's an optional field +containing a string that represents the display name of the group. + +1. Update the `weaver_semconv` crate to define the new field in [src/group.rs](/crates/weaver_semconv/src/group.rs). The + data types defined in `weaver_semconv` are used to parse the registry YAML files. The following are some guidelines: + - Optional fields should be defined as `Option`. So `display_name` should be defined as `Option`. + - N-ary fields should be defined as `Vec`. + - Other data types are also supported, such as `bool`, `u64`, `f64`, `enum`, `HashMap`, etc. The only constraint is + that the type should implement the `serde::Deserialize` and `serde::Serialize` traits. +2. Update the test data accordingly in [weaver_semconv/data](/crates/weaver_semconv/data). +3. Update all the unit tests to cover the new field. The easiest way to do this is to run the following command: + - `cargo test --package weaver_semconv` + - This command will run all the unit tests in the `weaver_semconv` crate. + - The tests that fail will be the ones that need to be updated, and usually, the error message will guide you on what + needs to be updated (most of the time, it's the addition of the new field in some struct or enum initialization). +4. Update the `weaver_resolved_schema` crate to add the corresponding new field in the "resolved" view of the registry. +This crate defines the data types used to represent the resolved view of the registry. + - Add the new field in [weaver_resolved_schema/src/registry.rs](/crates/weaver_resolved_schema/src/registry.rs). +5. Update the `weaver_resolver` crate to define the mapping between the "non-resolved" and "resolved" views of the +registry. + - Define the mapping in [weaver_resolver/src/registry.rs](/crates/weaver_resolver/src/registry.rs). + - Run the unit tests to test your changes: `cargo test --package weaver_resolver`. +6. Update the `weaver_forge` crate to generate the new field in data structures used by the template engine. + - Add the new field in [weaver_forge/src/registry.rs](/crates/weaver_forge/src/registry.rs). + - Run the unit tests to test your changes: `cargo test --package weaver_forge`. +7. Update your templates to use the new field and use the `weaver registry generate` command to generate and test the +new templates. + +Note: A simplification of the process is under development to make this process a bit easier. Indeed steps 4 and 6 are +somewhat repetitive and could merged into a single step (see this [GH issue](https://github.com/open-telemetry/weaver/issues/208)).