pub trait Span {
// Required methods
fn add_event_with_timestamp<T>(
&mut self,
name: T,
timestamp: SystemTime,
attributes: Vec<KeyValue>,
)
where T: Into<Cow<'static, str>>;
fn span_context(&self) -> &SpanContext;
fn is_recording(&self) -> bool;
fn set_attribute(&mut self, attribute: KeyValue);
fn set_status(&mut self, status: Status);
fn update_name<T>(&mut self, new_name: T)
where T: Into<Cow<'static, str>>;
fn add_link(&mut self, span_context: SpanContext, attributes: Vec<KeyValue>);
fn end_with_timestamp(&mut self, timestamp: SystemTime);
// Provided methods
fn add_event<T>(&mut self, name: T, attributes: Vec<KeyValue>)
where T: Into<Cow<'static, str>> { ... }
fn record_error(&mut self, err: &dyn Error) { ... }
fn set_attributes(&mut self, attributes: impl IntoIterator<Item = KeyValue>) { ... }
fn end(&mut self) { ... }
}
Expand description
The interface for a single operation within a trace.
Spans can be nested to form a trace tree. Each trace contains a root span, which typically describes the entire operation and, optionally, one or more sub-spans for its sub-operations.
The span name
concisely identifies the work represented by the span, for
example, an RPC method name, a function name, or the name of a subtask or
stage within a larger computation. The span name should be the most general
string that identifies a (statistically) interesting class of spans, rather
than individual span instances while still being human-readable. That is,
"get_user"
is a reasonable name, while "get_user/314159"
, where "314159"
is
a user ID, is not a good name due to its high cardinality. Generality
should be prioritized over human-readability.
For example, here are potential span names for an endpoint that gets a hypothetical account information:
Span Name | Guidance |
---|---|
get | Too general |
get_account/42 | Too specific |
get_account | Good, and account_id=42 would make a nice Span attribute |
get_account/{accountId} | Also good (using the “HTTP route”) |
The span’s start and end timestamps reflect the elapsed real time of the operation.
For example, if a span represents a request-response cycle (e.g. HTTP or an RPC), the span should have a start time that corresponds to the start time of the first sub-operation, and an end time of when the final sub-operation is complete. This includes:
- receiving the data from the request
- parsing of the data (e.g. from a binary or json format)
- any middleware or additional processing logic
- business logic
- construction of the response
- sending of the response
Child spans (or in some cases events) may be created to represent sub-operations which require more detailed observability. Child spans should measure the timing of the respective sub-operation, and may add additional attributes.
Required Methods§
sourcefn add_event_with_timestamp<T>(
&mut self,
name: T,
timestamp: SystemTime,
attributes: Vec<KeyValue>,
)
fn add_event_with_timestamp<T>( &mut self, name: T, timestamp: SystemTime, attributes: Vec<KeyValue>, )
Record an event with a timestamp in the context this span.
Note that the OpenTelemetry project documents certain “standard attributes” that have prescribed semantic meanings and are available via the opentelemetry_semantic_conventions crate.
sourcefn span_context(&self) -> &SpanContext
fn span_context(&self) -> &SpanContext
A reference to the SpanContext
for this span.
sourcefn is_recording(&self) -> bool
fn is_recording(&self) -> bool
Returns true
if this span is recording information.
Spans will not be recording information after they have ended.
This flag may be true
despite the entire trace being sampled out. This
allows recording and processing of information about the individual
spans without sending it to the backend. An example of this scenario may
be recording and processing of all incoming requests for the processing
and building of SLA/SLO latency charts while sending only a subset -
sampled spans - to the backend.
sourcefn set_attribute(&mut self, attribute: KeyValue)
fn set_attribute(&mut self, attribute: KeyValue)
Set an attribute of this span.
Setting an attribute with the same key as an existing attribute results in both being stored as attribute, without any de-duplication performed.
Note that the OpenTelemetry project documents certain “standard attributes” that have prescribed semantic meanings and are available via the opentelemetry_semantic_conventions crate.
sourcefn set_status(&mut self, status: Status)
fn set_status(&mut self, status: Status)
Sets the status of this Span
.
If used, this will override the default span status, which is Status::Unset
.
sourcefn update_name<T>(&mut self, new_name: T)
fn update_name<T>(&mut self, new_name: T)
Updates the span’s name.
After this update, any sampling behavior based on the name will depend on the implementation.
sourcefn add_link(&mut self, span_context: SpanContext, attributes: Vec<KeyValue>)
fn add_link(&mut self, span_context: SpanContext, attributes: Vec<KeyValue>)
Adds Link
to another SpanContext
.
This method allows linking the current span to another span, identified by its SpanContext
. Links can be used
to connect spans from different traces or within the same trace. Attributes can be attached to the link to
provide additional context or metadata.
§Arguments
span_context
- TheSpanContext
of the span to link to. This represents the target span’s unique identifiers and trace information.attributes
- A vector ofKeyValue
pairs that describe additional attributes of the link. These attributes can include any contextual information relevant to the link between the spans.
sourcefn end_with_timestamp(&mut self, timestamp: SystemTime)
fn end_with_timestamp(&mut self, timestamp: SystemTime)
Signals that the operation described by this span ended at the given time.
Provided Methods§
sourcefn add_event<T>(&mut self, name: T, attributes: Vec<KeyValue>)
fn add_event<T>(&mut self, name: T, attributes: Vec<KeyValue>)
Record an event in the context this span.
Note that the OpenTelemetry project documents certain “standard attributes” that have prescribed semantic meanings and are available via the opentelemetry_semantic_conventions crate.
sourcefn record_error(&mut self, err: &dyn Error)
fn record_error(&mut self, err: &dyn Error)
Record an error as an event for this span.
An additional call to Span::set_status is required if the status of the span should be set to error, as this method does not change the span status.
If this span is not being recorded then this method does nothing.
sourcefn set_attributes(&mut self, attributes: impl IntoIterator<Item = KeyValue>)
fn set_attributes(&mut self, attributes: impl IntoIterator<Item = KeyValue>)
Set multiple attributes of this span.
Setting an attribute with the same key as an existing attribute results in both being stored as attribute, without any de-duplication performed.
Note that the OpenTelemetry project documents certain “standard attributes” that have prescribed semantic meanings and are available via the opentelemetry_semantic_conventions crate.