Add support for annotations on attributes and groups

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to this project will be documented in this file.
 
+## [TBD] - TBD
+
+What's changed
+
+* Add support for annotations on attributes and groups. ([#645](https://github.com/open-telemetry/weaver/pull/645) by @lquerel).
 * 💥 BREAKING CHANGE 💥 - Upgrade to version 0.4.0 of regorus [requires all v0 policies to be modified](https://github.com/microsoft/regorus/pull/373). Policy upgrade instructions [here](https://www.openpolicyagent.org/docs/latest/v0-upgrade/#upgrading-rego) may help. ([#651](https://github.com/open-telemetry/weaver/pull/651) by @jerbly). 
 
 ## [0.13.2] - 2025-02-13

crates/weaver_emit/src/lib.rs

@@ -163,6 +163,7 @@ mod tests {
                     prefix: false,
                     tags: None,
                     value: None,
+                    annotations: None,
                 }],
                 span_kind: Some(SpanKindSpec::Internal),
                 events: vec![],

crates/weaver_emit/src/spans.rs

@@ -183,6 +183,7 @@ mod tests {
             prefix: false,
             tags: None,
             value: None,
+            annotations: None,
         }
     }
 

crates/weaver_forge/src/extensions/otel.rs

@@ -789,6 +789,7 @@ mod tests {
             tags: None,
             value: None,
             prefix: false,
+            annotations: None,
         };
 
         otel::add_filters(&mut env);
@@ -817,6 +818,7 @@ mod tests {
             tags: None,
             value: None,
             prefix: false,
+            annotations: None,
         };
 
         assert_eq!(
@@ -1003,6 +1005,7 @@ mod tests {
                 tags: None,
                 value: None,
                 prefix: false,
+                annotations: None,
             },
             Attribute {
                 name: "rec.b".into(),
@@ -1018,6 +1021,7 @@ mod tests {
                 tags: None,
                 value: None,
                 prefix: false,
+                annotations: None,
             },
             Attribute {
                 name: "crec.a".into(),
@@ -1033,6 +1037,7 @@ mod tests {
                 tags: None,
                 value: None,
                 prefix: false,
+                annotations: None,
             },
             Attribute {
                 name: "crec.b".into(),
@@ -1048,6 +1053,7 @@ mod tests {
                 tags: None,
                 value: None,
                 prefix: false,
+                annotations: None,
             },
             Attribute {
                 name: "rec.c".into(),
@@ -1063,6 +1069,7 @@ mod tests {
                 tags: None,
                 value: None,
                 prefix: false,
+                annotations: None,
             },
             Attribute {
                 name: "rec.d".into(),
@@ -1078,6 +1085,7 @@ mod tests {
                 tags: None,
                 value: None,
                 prefix: false,
+                annotations: None,
             },
             Attribute {
                 name: "opt.a".into(),
@@ -1093,6 +1101,7 @@ mod tests {
                 tags: None,
                 value: None,
                 prefix: false,
+                annotations: None,
             },
             Attribute {
                 name: "opt.b".into(),
@@ -1108,6 +1117,7 @@ mod tests {
                 tags: None,
                 value: None,
                 prefix: false,
+                annotations: None,
             },
             Attribute {
                 name: "req.a".into(),
@@ -1123,6 +1133,7 @@ mod tests {
                 tags: None,
                 value: None,
                 prefix: false,
+                annotations: None,
             },
             Attribute {
                 name: "req.b".into(),
@@ -1138,6 +1149,7 @@ mod tests {
                 tags: None,
                 value: None,
                 prefix: false,
+                annotations: None,
             },
         ];
         let json =
@@ -1196,6 +1208,7 @@ mod tests {
                 tags: None,
                 value: None,
                 prefix: false,
+                annotations: None,
             },
             Attribute {
                 name: "attr2".to_owned(),
@@ -1211,6 +1224,7 @@ mod tests {
                 tags: None,
                 value: None,
                 prefix: false,
+                annotations: None,
             },
             Attribute {
                 name: "attr3".to_owned(),
@@ -1226,6 +1240,7 @@ mod tests {
                 tags: None,
                 value: None,
                 prefix: false,
+                annotations: None,
             },
         ];
 
@@ -1516,6 +1531,7 @@ mod tests {
             tags: None,
             value: None,
             prefix: false,
+            annotations: None,
         };
 
         otel::add_filters(&mut env);
@@ -1544,6 +1560,7 @@ mod tests {
             tags: None,
             value: None,
             prefix: false,
+            annotations: None,
         };
 
         otel::add_filters(&mut env);

crates/weaver_resolved_schema/Cargo.toml

@@ -19,6 +19,7 @@ thiserror.workspace = true
 serde.workspace = true
 ordered-float.workspace = true
 schemars.workspace = true
+serde_yaml.workspace = true
 
 [dev-dependencies]
 serde_json.workspace = true

crates/weaver_resolved_schema/src/attribute.rs

@@ -8,13 +8,15 @@ use crate::tags::Tags;
 use crate::value::Value;
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
 use std::fmt::Display;
 use std::ops::Not;
 #[cfg(test)]
 use weaver_semconv::attribute::PrimitiveOrArrayTypeSpec;
 use weaver_semconv::attribute::{AttributeSpec, AttributeType, Examples, RequirementLevel};
 use weaver_semconv::deprecated::Deprecated;
 use weaver_semconv::stability::Stability;
+use weaver_semconv::YamlValue;
 
 /// An attribute definition.
 #[derive(Serialize, Deserialize, Debug, Clone, Eq, PartialEq, Hash, JsonSchema)]
@@ -76,6 +78,10 @@ pub struct Attribute {
     /// A set of tags for the attribute.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub tags: Option<Tags>,
+    /// Annotations for the group.
+    #[serde(default)]
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub annotations: Option<BTreeMap<String, YamlValue>>,
 
     /// The value of the attribute.
     /// Note: This is only used in a telemetry schema specification.
@@ -121,6 +127,7 @@ impl Attribute {
             prefix: false,
             tags: None,
             value: None,
+            annotations: None,
         }
     }
 
@@ -142,6 +149,7 @@ impl Attribute {
             prefix: false,
             tags: None,
             value: None,
+            annotations: None,
         }
     }
 
@@ -163,6 +171,7 @@ impl Attribute {
             prefix: false,
             tags: None,
             value: None,
+            annotations: None,
         }
     }
 
@@ -188,6 +197,7 @@ impl Attribute {
             prefix: false,
             tags: None,
             value: None,
+            annotations: None,
         }
     }
 

crates/weaver_resolved_schema/src/lib.rs

@@ -136,6 +136,7 @@ impl ResolvedTelemetrySchema {
             constraints: vec![],
             unit: None,
             body: None,
+            annotations: None,
         });
     }
 

crates/weaver_resolved_schema/src/lineage.rs

@@ -10,6 +10,7 @@ use serde::{Deserialize, Serialize};
 use weaver_semconv::attribute::{AttributeSpec, Examples, RequirementLevel};
 use weaver_semconv::deprecated::Deprecated;
 use weaver_semconv::stability::Stability;
+use weaver_semconv::YamlValue;
 
 /// Attribute lineage (at the field level).
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema)]
@@ -374,6 +375,32 @@ impl AttributeLineage {
         }
     }
 
+    /// Determines the value of the annotations field by evaluating the presence of
+    /// a local value. If a local value is provided, it is used, and the annotations
+    /// field's lineage is marked as local. Otherwise, the specified parent
+    /// value is used, and the tag field's lineage is marked as inherited
+    /// from the parent.
+    /// This method updates the lineage information for the annotations field to
+    /// reflect the source of its value.
+    pub fn annotations(
+        &mut self,
+        local_value: &Option<BTreeMap<String, YamlValue>>,
+        parent_value: &Option<BTreeMap<String, YamlValue>>,
+    ) -> Option<BTreeMap<String, YamlValue>> {
+        if local_value.is_some() {
+            _ = self
+                .locally_overridden_fields
+                .insert("annotations".to_owned());
+            _ = self.inherited_fields.remove("annotations");
+            local_value.clone()
+        } else {
+            if parent_value.is_some() {
+                _ = self.inherited_fields.insert("annotations".to_owned());
+            }
+            parent_value.clone()
+        }
+    }
+
     /// Determines the value of the tags field by evaluating the presence of
     /// a local value. If a local value is provided, it is used, and the tags
     /// field's lineage is marked as local. Otherwise, the specified parent

crates/weaver_resolved_schema/src/registry.rs

@@ -8,18 +8,18 @@ use schemars::JsonSchema;
 use std::collections::{BTreeMap, HashMap, HashSet};
 use weaver_semconv::any_value::AnyValueSpec;
 
-use serde::{Deserialize, Serialize};
-use weaver_semconv::deprecated::Deprecated;
-use weaver_semconv::group::{GroupType, InstrumentSpec, SpanKindSpec};
-use weaver_semconv::stability::Stability;
-
 use crate::attribute::{Attribute, AttributeRef};
 use crate::catalog::Catalog;
 use crate::error::{handle_errors, Error};
 use crate::lineage::GroupLineage;
 use crate::registry::GroupStats::{
     AttributeGroup, Event, Metric, MetricGroup, Resource, Scope, Span,
 };
+use serde::{Deserialize, Serialize};
+use weaver_semconv::deprecated::Deprecated;
+use weaver_semconv::group::{GroupType, InstrumentSpec, SpanKindSpec};
+use weaver_semconv::stability::Stability;
+use weaver_semconv::YamlValue;
 
 /// A semantic convention registry.
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema)]
@@ -131,6 +131,10 @@ pub struct Group {
     /// This fields is only used for event groups.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub body: Option<AnyValueSpec>,
+    /// Annotations for the group.
+    #[serde(default)]
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub annotations: Option<HashMap<String, YamlValue>>,
 }
 
 /// Common statistics for a group.

crates/weaver_resolver/data/registry-test-14-annotations/README.md

@@ -0,0 +1,2 @@
+Test that annotations end up in the resolved registry.
+This test must success.

crates/weaver_resolver/data/registry-test-14-annotations/expected-attribute-catalog.json

@@ -0,0 +1,47 @@
+[
+  {
+    "name": "attr1",
+    "type": "string",
+    "brief": "Brief",
+    "examples": "eu-central-1",
+    "requirement_level": "required",
+    "note": "Note",
+    "stability": "stable",
+    "annotations": {
+      "code_generation": {
+        "exclude": true
+      },
+      "privacy_sensitivity": "PII"
+    }
+  },
+  {
+    "name": "attr1",
+    "type": "string",
+    "brief": "Brief",
+    "examples": "eu-central-1",
+    "requirement_level": "required",
+    "note": "Note",
+    "stability": "stable",
+    "annotations": {
+      "code_generation": {
+        "exclude": true
+      },
+      "privacy_sensitivity": "PII + PHI",
+      "complex": {
+        "key1": "string",
+        "key2": 234,
+        "key3": true,
+        "key4": {
+          "key4.1": "string",
+          "key4.2": 234
+        },
+        "key5": [
+          12,
+          45,
+          67
+        ],
+        "key6": null
+      }
+    }
+  }
+]