@@ -65,110 +65,62 @@ impl InstrumentKind {
6565 }
6666}
6767
68- /// Describes properties an instrument is created with, also used for filtering
69- /// in [View](crate::metrics::View)s.
68+ /// Describes properties an instrument is created with, used for filtering in
69+ /// [View](crate::metrics::View)s.
70+ ///
71+ /// A reference to `Instrument` is provided to the `view` to select the
72+ /// instrument(s) for which the [Stream] should be applied.
7073///
7174/// # Example
7275///
73- /// Instruments can be used as criteria for views.
76+ /// ```rust
77+ /// use opentelemetry_sdk::metrics::{Instrument, Stream};
7478///
79+ /// let my_view_change_cardinality = |i: &Instrument| {
80+ /// if i.name() == "my_second_histogram" {
81+ /// // Note: If Stream is invalid, build() will return an error. By
82+ /// // calling `.ok()`, any such error is ignored and treated as if the
83+ /// // view does not match the instrument. If this is not the desired
84+ /// // behavior, consider handling the error explicitly.
85+ /// Stream::builder().with_cardinality_limit(2).build().ok()
86+ /// } else {
87+ /// None
88+ /// }
89+ /// };
7590/// ```
76- /// use opentelemetry_sdk::metrics::{new_view, Aggregation, Instrument, Stream, StreamBuilder};
77- ///
78- /// let criteria = Instrument::new().name("counter_*");
79- /// let mask = Stream::builder()
80- /// .with_aggregation(Aggregation::Sum)
81- /// .build()
82- /// .unwrap();
83- ///
84- /// let view = new_view(criteria, mask);
85- /// # drop(view);
86- /// ```
87- #[ derive( Clone , Default , Debug , PartialEq ) ]
88- #[ non_exhaustive]
91+ #[ derive( Clone , Debug , PartialEq ) ]
8992pub struct Instrument {
9093 /// The human-readable identifier of the instrument.
91- pub name : Cow < ' static , str > ,
94+ pub ( crate ) name : Cow < ' static , str > ,
9295 /// describes the purpose of the instrument.
93- pub description : Cow < ' static , str > ,
96+ pub ( crate ) description : Cow < ' static , str > ,
9497 /// The functional group of the instrument.
95- pub kind : Option < InstrumentKind > ,
98+ pub ( crate ) kind : InstrumentKind ,
9699 /// Unit is the unit of measurement recorded by the instrument.
97- pub unit : Cow < ' static , str > ,
100+ pub ( crate ) unit : Cow < ' static , str > ,
98101 /// The instrumentation that created the instrument.
99- pub scope : InstrumentationScope ,
102+ pub ( crate ) scope : InstrumentationScope ,
100103}
101104
102- #[ cfg( feature = "spec_unstable_metrics_views" ) ]
103105impl Instrument {
104- /// Create a new instrument with default values
105- pub fn new ( ) -> Self {
106- Instrument :: default ( )
107- }
108-
109- /// Set the instrument name.
110- pub fn name ( mut self , name : impl Into < Cow < ' static , str > > ) -> Self {
111- self . name = name. into ( ) ;
112- self
113- }
114-
115- /// Set the instrument description.
116- pub fn description ( mut self , description : impl Into < Cow < ' static , str > > ) -> Self {
117- self . description = description. into ( ) ;
118- self
119- }
120-
121- /// Set the instrument unit.
122- pub fn unit ( mut self , unit : impl Into < Cow < ' static , str > > ) -> Self {
123- self . unit = unit. into ( ) ;
124- self
125- }
126-
127- /// Set the instrument scope.
128- pub fn scope ( mut self , scope : InstrumentationScope ) -> Self {
129- self . scope = scope;
130- self
131- }
132-
133- /// empty returns if all fields of i are their default-value.
134- pub ( crate ) fn is_empty ( & self ) -> bool {
135- self . name . is_empty ( )
136- && self . description . is_empty ( )
137- && self . kind . is_none ( )
138- && self . unit . is_empty ( )
139- && self . scope == InstrumentationScope :: default ( )
140- }
141-
142- pub ( crate ) fn matches ( & self , other : & Instrument ) -> bool {
143- self . matches_name ( other)
144- && self . matches_description ( other)
145- && self . matches_kind ( other)
146- && self . matches_unit ( other)
147- && self . matches_scope ( other)
106+ /// Instrument name.
107+ pub fn name ( & self ) -> & str {
108+ self . name . as_ref ( )
148109 }
149110
150- pub ( crate ) fn matches_name ( & self , other : & Instrument ) -> bool {
151- self . name . is_empty ( ) || self . name . as_ref ( ) == other. name . as_ref ( )
111+ /// Instrument kind.
112+ pub fn kind ( & self ) -> InstrumentKind {
113+ self . kind
152114 }
153115
154- pub ( crate ) fn matches_description ( & self , other : & Instrument ) -> bool {
155- self . description . is_empty ( ) || self . description . as_ref ( ) == other. description . as_ref ( )
116+ /// Instrument unit.
117+ pub fn unit ( & self ) -> & str {
118+ self . unit . as_ref ( )
156119 }
157120
158- pub ( crate ) fn matches_kind ( & self , other : & Instrument ) -> bool {
159- self . kind . is_none ( ) || self . kind == other. kind
160- }
161-
162- pub ( crate ) fn matches_unit ( & self , other : & Instrument ) -> bool {
163- self . unit . is_empty ( ) || self . unit . as_ref ( ) == other. unit . as_ref ( )
164- }
165-
166- pub ( crate ) fn matches_scope ( & self , other : & Instrument ) -> bool {
167- ( self . scope . name ( ) . is_empty ( ) || self . scope . name ( ) == other. scope . name ( ) )
168- && ( self . scope . version ( ) . is_none ( )
169- || self . scope . version ( ) . as_ref ( ) == other. scope . version ( ) . as_ref ( ) )
170- && ( self . scope . schema_url ( ) . is_none ( )
171- || self . scope . schema_url ( ) . as_ref ( ) == other. scope . schema_url ( ) . as_ref ( ) )
121+ /// Instrument scope.
122+ pub fn scope ( & self ) -> & InstrumentationScope {
123+ & self . scope
172124 }
173125}
174126
@@ -188,7 +140,6 @@ impl Instrument {
188140/// .unwrap();
189141/// ```
190142#[ derive( Default , Debug ) ]
191- #[ non_exhaustive]
192143pub struct StreamBuilder {
193144 name : Option < Cow < ' static , str > > ,
194145 description : Option < Cow < ' static , str > > ,
@@ -312,27 +263,9 @@ fn validate_bucket_boundaries(boundaries: &[f64]) -> Result<(), String> {
312263 Ok ( ( ) )
313264}
314265
315- /// Describes the stream of data an instrument produces.
316- ///
317- /// # Example
318- ///
319- /// Streams can be used as masks in views.
320- ///
321- /// ```
322- /// use opentelemetry_sdk::metrics::{new_view, Aggregation, Instrument, Stream};
323- ///
324- /// let criteria = Instrument::new().name("counter_*");
325- /// let mask = Stream::builder()
326- /// .with_aggregation(Aggregation::Sum)
327- /// .build()
328- /// .unwrap();
329- ///
330- /// let view = new_view(criteria, mask);
331- /// # drop(view);
332- /// ```
266+ /// Describes the stream of data an instrument produces. Used in
267+ /// [View](crate::metrics::View)s to customize the metric output.
333268#[ derive( Default , Debug ) ]
334- #[ non_exhaustive]
335- #[ allow( unreachable_pub) ]
336269pub struct Stream {
337270 /// The human-readable identifier of the stream.
338271pub ( crate ) name : Option < Cow < ' static , str > > ,
0 commit comments