#include <userver/tracing/span.hpp>
Measures the execution time of the current code block, links it with the parent tracing::Spans and stores that info in the log.
Logging of spans can be controlled at runtime via USERVER_NO_LOG_SPANS.
See Logging and Tracing for usage examples and more descriptions.
Public Member Functions | |
Span (std::string name, const utils::impl::SourceLocation &source_location=utils::impl::SourceLocation::Current()) | |
Span (std::string name, const Span *parent, ReferenceType reference_type=ReferenceType::kChild, const utils::impl::SourceLocation &source_location=utils::impl::SourceLocation::Current()) | |
Span (Span &&other) noexcept | |
Span (const Span &other)=delete | |
Span & | operator= (Span &&)=delete |
Span & | operator= (const Span &)=delete |
Span | CreateChild (std::string name, const utils::impl::SourceLocation &source_location=utils::impl::SourceLocation::Current()) const |
Span | CreateFollower (std::string name, const utils::impl::SourceLocation &source_location=utils::impl::SourceLocation::Current()) const |
ScopeTime | CreateScopeTime () |
Creates a tracing::ScopeTime attached to the span. | |
ScopeTime | CreateScopeTime (std::string name) |
Creates a tracing::ScopeTime attached to the Span and starts measuring execution time. Tag {scope_name}_time with elapsed time is added to result span. | |
ScopeTime::Duration | GetTotalDuration (const std::string &scope_name) const |
ScopeTime::DurationMillis | GetTotalElapsedTime (const std::string &scope_name) const |
void | AddTag (std::string key, logging::LogExtra::Value value) |
void | AddTagFrozen (std::string key, logging::LogExtra::Value value) |
void | AddNonInheritableTag (std::string key, logging::LogExtra::Value value) |
void | AddNonInheritableTags (const logging::LogExtra &) |
void | AddEvent (SpanEvent &&event) |
Add an event to Span. | |
void | AddEvent (std::string_view event_name) |
void | SetLogLevel (logging::Level log_level) |
Sets log level with which the current span itself is written into the tracing system. | |
logging::Level | GetLogLevel () const |
See tracing::Span::SetLogLevel. | |
void | SetLocalLogLevel (std::optional< logging::Level > log_level) |
Sets an additional cutoff for the logs written in the scope of this Span , and in nested scopes recursively. | |
std::optional< logging::Level > | GetLocalLogLevel () const |
See tracing::Span::SetLocalLogLevel. | |
void | SetLink (std::string_view link) |
void | SetParentLink (std::string_view parent_link) |
std::string_view | GetLink () const |
std::string_view | GetParentLink () const |
std::string_view | GetTraceId () const |
std::string_view | GetSpanId () const |
Identifies a specific span. It does not propagate. | |
std::string_view | GetParentId () const |
Span ID of the nearest loggable parent span, or empty string if none exists. | |
std::optional< std::string_view > | GetSpanIdForChildLogs () const |
std::string_view | GetName () const |
Get name the Span was created with. | |
bool | ShouldLogDefault () const noexcept |
void | DetachFromCoroStack () |
void | AttachToCoroStack () |
std::chrono::system_clock::time_point | GetStartSystemTime () const |
Static Public Member Functions | |
static Span & | CurrentSpan () |
Returns the Span of the current task. | |
static Span * | CurrentSpanUnchecked () |
Returns nullptr if called in non-coroutine context or from a task with no alive Span; otherwise returns the Span of the current task. | |
static Span | MakeSpan (std::string name, std::string_view trace_id, std::string_view parent_span_id, const utils::impl::SourceLocation &source_location=utils::impl::SourceLocation::Current()) |
static Span | MakeSpan (std::string name, std::string_view trace_id, std::string_view parent_span_id, std::string_view link, const utils::impl::SourceLocation &source_location=utils::impl::SourceLocation::Current()) |
static Span | MakeRootSpan (std::string name, const utils::impl::SourceLocation &source_location=utils::impl::SourceLocation::Current()) |
|
explicit |
Use implicit task-local storage for parent identification, takes TraceID and Link from the parent Span
.
For extremely rare cases where a new Trace ID is required, use tracing::Span::MakeSpan.
|
explicit |
void tracing::Span::AddNonInheritableTag | ( | std::string | key, |
logging::LogExtra::Value | value ) |
void tracing::Span::AddTag | ( | std::string | key, |
logging::LogExtra::Value | value ) |
Add a tag that is used on each logging in this Span and all future children.
void tracing::Span::AddTagFrozen | ( | std::string | key, |
logging::LogExtra::Value | value ) |
Add a tag that is used on each logging in this Span and all future children. It will not be possible to change its value.
void tracing::Span::AttachToCoroStack | ( | ) |
Attach the Span to current engine::Task so it is returned by CurrentSpan().
Span tracing::Span::CreateChild | ( | std::string | name, |
const utils::impl::SourceLocation & | source_location = utils::impl::SourceLocation::Current() ) const |
Create a child which can be used independently of the parent.
The child shares no state with its parent. If you need to run code in parallel, create a child span and use the child in a separate task.
ScopeTime tracing::Span::CreateScopeTime | ( | std::string | name | ) |
Creates a tracing::ScopeTime attached to the Span and starts measuring execution time. Tag {scope_name}_time
with elapsed time is added to result span.
name
parameter is expected to satisfy snake case. Otherwise, it is converted to snake case.
|
static |
Returns the Span of the current task.
Should not be called in non-coroutine context. Should not be called from a task with no alive Span.
Rule of thumb: it is safe to call it from a task created by utils::Async/utils::CriticalAsync/utils::PeriodicTask. If current task was created with an explicit engine::impl::*Async(), you have to create a Span beforehand.
void tracing::Span::DetachFromCoroStack | ( | ) |
Detach the Span from current engine::Task so it is not returned by CurrentSpan() any more.
std::string_view tracing::Span::GetLink | ( | ) | const |
Get link - a request ID within the service.
Propagates within a single service, but not from client to server. A new link is generated for the "root" request handling task.
std::string_view tracing::Span::GetParentLink | ( | ) | const |
Set parent link - request ID of the upstream service. Can only be called once.
Propagates within a single service.
std::optional< std::string_view > tracing::Span::GetSpanIdForChildLogs | ( | ) | const |
Span ID of the nearest loggable span within the span chain, including the current span. If the current span and all parent spans will not be logged, returns std::nullopt
.
ScopeTime::Duration tracing::Span::GetTotalDuration | ( | const std::string & | scope_name | ) | const |
Returns total time elapsed for a certain scope of this span. If there is no record for the scope, returns 0.
ScopeTime::DurationMillis tracing::Span::GetTotalElapsedTime | ( | const std::string & | scope_name | ) | const |
Returns total time elapsed for a certain scope of this span. If there is no record for the scope, returns 0.
Prefer using Span::GetTotalDuration()
std::string_view tracing::Span::GetTraceId | ( | ) | const |
An ID of the request that does not change from service to service.
Propagates both to sub-spans within a single service, and from client to server
|
static |
|
static |
|
static |
void tracing::Span::SetLink | ( | std::string_view | link | ) |
Set link - a request ID within a service. Can be called only once.
Propagates within a single service, but not from client to server. A new link is generated for the "root" request handling task.
void tracing::Span::SetLocalLogLevel | ( | std::optional< logging::Level > | log_level | ) |
Sets an additional cutoff for the logs written in the scope of this Span
, and in nested scopes recursively.
For example, if the global log level is info
, and the current Span
has (own or inherited) local log level warning
, then all LOG_INFO
s within the current scope will be thrown away.
The cutoff also applies to the span itself. If the span's log level is less than the local log level, then the span is not written to the tracing system.
Local log level of child spans can override local log level of parent spans in both directions. For example:
Span
is warning
,info
,info
logs within that Span
will be written,info
.Currently, local log level cannot override the global log level of the logger. For example, if the global log level is info
, and the current Span
has (own or inherited) local log level debug
, then all LOG_DEBUG
s within the current scope will still be thrown away.
void tracing::Span::SetLogLevel | ( | logging::Level | log_level | ) |
Sets log level with which the current span itself is written into the tracing system.
This (mostly) does not affect logs written within the span, unlike tracing::Span::SetLocalLogLevel.
If Span
's log level is less than the global logger's log level, then the span is not written out. In that case:
trace_id
, link
and span_id
of the nearest written Span
object;Span
even if it is hidden;Span
s as tag scopes regardless of their tracing purposes.Tracing systems use span's log level to highlight warning
and error
spans.
void tracing::Span::SetParentLink | ( | std::string_view | parent_link | ) |
Set parent link - request ID of the upstream service. Can only be called once.
Propagates within a single service.
|
noexcept |
|
friend |
|
friend |