@@ -45,28 +45,42 @@ impl SpanRef<'_> {
4545}
4646
4747impl SpanRef < ' _ > {
48- /// An API to record events in the context of a given `Span`.
48+ /// Record an event in the context this span.
49+ ///
50+ /// Note that the OpenTelemetry project documents certain "[standard
51+ /// attributes]" that have prescribed semantic meanings and are available via
52+ /// the [opentelemetry_semantic_conventions] crate.
53+ ///
54+ /// [standard attributes]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.9.0/specification/trace/semantic_conventions/README.md
55+ /// [opentelemetry_semantic_conventions]: https://docs.rs/opentelemetry-semantic-conventions
4956pub fn add_event < T > ( & self , name : T , attributes : Vec < KeyValue > )
5057 where
5158 T : Into < Cow < ' static , str > > ,
5259 {
5360 self . with_inner_mut ( |inner| inner. add_event ( name, attributes) )
5461 }
5562
56- /// Convenience method to record an exception/error as an `Event`
63+ /// Record an exception event
5764pub fn record_exception ( & self , err : & dyn Error ) {
5865 self . with_inner_mut ( |inner| inner. record_exception ( err) )
5966 }
6067
61- /// Convenience method to record a exception/error as an `Event` with custom stacktrace
68+ /// Record an exception event with stacktrace
6269pub fn record_exception_with_stacktrace < T > ( & self , err : & dyn Error , stacktrace : T )
6370 where
6471 T : Into < Cow < ' static , str > > ,
6572 {
6673 self . with_inner_mut ( |inner| inner. record_exception_with_stacktrace ( err, stacktrace) )
6774 }
6875
69- /// An API to record events at a specific time in the context of a given `Span`.
76+ /// Record an event with a timestamp in the context this span.
77+ ///
78+ /// Note that the OpenTelemetry project documents certain "[standard
79+ /// attributes]" that have prescribed semantic meanings and are available via
80+ /// the [opentelemetry_semantic_conventions] crate.
81+ ///
82+ /// [standard attributes]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.9.0/specification/trace/semantic_conventions/README.md
83+ /// [opentelemetry_semantic_conventions]: https://docs.rs/opentelemetry-semantic-conventions
7084pub fn add_event_with_timestamp < T > (
7185 & self ,
7286 name : T ,
@@ -80,13 +94,21 @@ impl SpanRef<'_> {
8094 } )
8195 }
8296
83- /// Returns the `SpanContext` for the given `Span` .
97+ /// A reference to the [ `SpanContext`] for this span .
8498pub fn span_context ( & self ) -> & SpanContext {
8599 & self . 0 . span_context
86100 }
87101
88- /// Returns true if this `Span` is recording information like events with the `add_event`
89- /// operation, attributes using `set_attributes`, status with `set_status`, etc.
102+ /// Returns `true` if this span is recording information.
103+ ///
104+ /// Spans will not be recording information after they have ended.
105+ ///
106+ /// This flag may be `true` despite the entire trace being sampled out. This
107+ /// allows recording and processing of information about the individual
108+ /// spans without sending it to the backend. An example of this scenario may
109+ /// be recording and processing of all incoming requests for the processing
110+ /// and building of SLA/SLO latency charts while sending only a subset -
111+ /// sampled spans - to the backend.
90112pub fn is_recording ( & self ) -> bool {
91113 self . 0
92114 . inner
@@ -95,61 +117,125 @@ impl SpanRef<'_> {
95117 . unwrap_or ( false )
96118 }
97119
98- /// An API to set a single `Attribute` where the attribute properties are passed
99- /// as arguments. To avoid extra allocations some implementations may offer a separate API for
100- /// each of the possible value types.
120+ /// Set an attribute of this span.
121+ ///
122+ /// Setting an attribute with the same key as an existing attribute
123+ /// generally overwrites the existing attribute's value.
124+ ///
125+ /// Note that the OpenTelemetry project documents certain "[standard
126+ /// attributes]" that have prescribed semantic meanings and are available via
127+ /// the [opentelemetry_semantic_conventions] crate.
128+ ///
129+ /// [standard attributes]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.9.0/specification/trace/semantic_conventions/README.md
130+ /// [opentelemetry_semantic_conventions]: https://docs.rs/opentelemetry-semantic-conventions
101131pub fn set_attribute ( & self , attribute : crate :: KeyValue ) {
102132 self . with_inner_mut ( move |inner| inner. set_attribute ( attribute) )
103133 }
104134
105- /// Sets the status of the `Span`. If used, this will override the default `Span`
106- /// status, which is `Unset`. `message` MUST be ignored when the status is `OK` or `Unset`
135+ /// Sets the status of this `Span`.
136+ ///
137+ /// If used, this will override the default span status, which is [`StatusCode::Unset`].
138+ ///
139+ /// [`StatusCode::Unset`]: super::StatusCode::Unset
107140pub fn set_status < T > ( & self , code : super :: StatusCode , message : T )
108141 where
109142 T : Into < Cow < ' static , str > > ,
110143 {
111144 self . with_inner_mut ( move |inner| inner. set_status ( code, message) )
112145 }
113146
114- /// Updates the `Span`'s name. After this update, any sampling behavior based on the
115- /// name will depend on the implementation.
147+ /// Updates the span's name.
148+ ///
149+ /// After this update, any sampling behavior based on the name will depend on
150+ /// the implementation.
116151pub fn update_name < T > ( & self , new_name : T )
117152 where
118153 T : Into < Cow < ' static , str > > ,
119154 {
120155 self . with_inner_mut ( move |inner| inner. update_name ( new_name) )
121156 }
122157
123- /// Finishes the `Span` .
158+ /// Signals that the operation described by this span has now ended .
124159pub fn end ( & self ) {
125160 self . end_with_timestamp ( crate :: time:: now ( ) ) ;
126161 }
127162
128- /// Finishes the `Span` with given timestamp
163+ /// Signals that the operation described by this span ended at the given time.
129164pub fn end_with_timestamp ( & self , timestamp : std:: time:: SystemTime ) {
130165 self . with_inner_mut ( move |inner| inner. end_with_timestamp ( timestamp) )
131166 }
132167}
133168
134- /// Methods for storing and retrieving trace data in a context.
169+ /// Methods for storing and retrieving trace data in a [`Context`].
170+ ///
171+ /// See [`Context`] for examples of setting and retrieving the current context.
135172pub trait TraceContextExt {
136- /// Returns a clone of the current context with the included span.
173+ /// Returns a clone of the current context with the included [`Span`].
174+ ///
175+ /// # Examples
176+ ///
177+ /// ```
178+ /// use opentelemetry_api::{global, trace::{TraceContextExt, Tracer}, Context};
137179///
138- /// This is useful for building tracers.
180+ /// let tracer = global::tracer("example");
181+ ///
182+ /// // build a span
183+ /// let span = tracer.start("parent_span");
184+ ///
185+ /// // create a new context from the currently active context that includes this span
186+ /// let cx = Context::current_with_span(span);
187+ ///
188+ /// // create a child span by explicitly specifying the parent context
189+ /// let child = tracer.start_with_context("child_span", &cx);
190+ /// # drop(child)
191+ /// ```
139192fn current_with_span < T : crate :: trace:: Span + Send + Sync + ' static > ( span : T ) -> Self ;
140193
141194 /// Returns a clone of this context with the included span.
142195///
143- /// This is useful for building tracers.
196+ /// # Examples
197+ ///
198+ /// ```
199+ /// use opentelemetry_api::{global, trace::{TraceContextExt, Tracer}, Context};
200+ ///
201+ /// fn fn_with_passed_in_context(cx: &Context) {
202+ /// let tracer = global::tracer("example");
203+ ///
204+ /// // build a span
205+ /// let span = tracer.start("parent_span");
206+ ///
207+ /// // create a new context from the given context that includes the span
208+ /// let cx_with_parent = cx.with_span(span);
209+ ///
210+ /// // create a child span by explicitly specifying the parent context
211+ /// let child = tracer.start_with_context("child_span", &cx_with_parent);
212+ /// # drop(child)
213+ /// }
214+ ///
144215fn with_span < T : crate :: trace:: Span + Send + Sync + ' static > ( & self , span : T ) -> Self ;
145216
146217 /// Returns a reference to this context's span, or the default no-op span if
147218/// none has been set.
219+ ///
220+ /// # Examples
221+ ///
222+ /// ```
223+ /// use opentelemetry_api::{trace::TraceContextExt, Context};
224+ ///
225+ /// // Add an event to the currently active span
226+ /// Context::current().span().add_event("An event!", vec![]);
227+ /// ```
148228fn span ( & self ) -> SpanRef < ' _ > ;
149229
150- /// Used to see if a span has been marked as active
230+ /// Returns whether or not an active span has been set.
231+ ///
232+ /// # Examples
233+ ///
234+ /// ```
235+ /// use opentelemetry_api::{trace::TraceContextExt, Context};
151236///
152- /// This is useful for building tracers.
237+ /// assert!(!Context::current().has_active_span());
238+ /// ```
153239fn has_active_span ( & self ) -> bool ;
154240
155241 /// Returns a copy of this context with the span context included.
0 commit comments