tracing::Span Class Reference

Measures the execution time of the current code block, links it with the parent tracing::Spans and stores that info in the log. More...

#include <userver/tracing/span.hpp>

Public Member Functions
	Span (TracerPtr tracer, std::string name, const Span *parent, ReferenceType reference_type, logging::Level log_level=logging::Level::kInfo, utils::impl::SourceLocation source_location=utils::impl::SourceLocation::Current())
	Span (std::string name, ReferenceType reference_type=ReferenceType::kChild, logging::Level log_level=logging::Level::kInfo, utils::impl::SourceLocation source_location=utils::impl::SourceLocation::Current())
	Span (Span &&other) noexcept
Span &	operator= (const Span &)=delete
Span &	operator= (Span &&)=delete
Span	CreateChild (std::string name) const
Span	CreateFollower (std::string name) const
ScopeTime	CreateScopeTime ()
	Creates a tracing::ScopeTime attached to the span. More...
ScopeTime	CreateScopeTime (std::string name)
	Creates a tracing::ScopeTime attached to the Span and starts measuring execution time. More...
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	SetLogLevel (logging::Level log_level)
	Sets level for tags logging.
logging::Level	GetLogLevel () const
	Returns level for tags logging.
void	SetLocalLogLevel (std::optional< logging::Level > log_level)
	Sets the local log level that disables logging of this span if the local log level set and greater than the main log level of the Span.
std::optional< logging::Level >	GetLocalLogLevel () const
	Returns the local log level that disables logging of this span if it is set and greater than the main log level of the Span.
void	SetLink (std::string link)
	Set link. Can be called only once.
void	SetParentLink (std::string parent_link)
	Set parent_link. Can be called only once.
std::string	GetLink () const
std::string	GetParentLink () const
const std::string &	GetTraceId () const
const std::string &	GetSpanId () const
const std::string &	GetParentId () const
void	LogTo (logging::LogHelper &log_helper) const &
bool	ShouldLogDefault () const noexcept
void	DetachFromCoroStack ()
void	AttachToCoroStack ()

Static Public Member Functions
static Span &	CurrentSpan ()
	Returns the Span of the current task. More...
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)
static Span	MakeSpan (std::string name, std::string_view trace_id, std::string_view parent_span_id, std::string link)

Friends
class	SpanBuilder

Detailed Description

Measures the execution time of the current code block, links it with the parent tracing::Spans and stores that info in the log.

See Logging and Tracing for usage examples and more descriptions.

Warning

Shall be created only as a local variable. Do not use it as a class member!

Examples

samples/tcp_full_duplex_service/tcp_full_duplex_service.cpp.

Definition at line 29 of file span.hpp.

Member Function Documentation

AddNonInheritableTag()

void tracing::Span::AddNonInheritableTag	(	std::string	key,
		logging::LogExtra::Value	value
	)

Add a tag that is local to the Span (IOW, it is not propagated to future children) and logged only once in the destructor of the Span.

AddTag()

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.

Examples

samples/tcp_full_duplex_service/tcp_full_duplex_service.cpp.

AddTagFrozen()

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.

AttachToCoroStack()

void tracing::Span::AttachToCoroStack

(

)

Attach the Span to current engine::Task so it is returned by CurrentSpan().

CreateChild()

Span tracing::Span::CreateChild

(

std::string

name

)

const

Create a child which can be used independently from 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.

CreateScopeTime() [1/2]

ScopeTime tracing::Span::CreateScopeTime

(

)

Creates a tracing::ScopeTime attached to the span.

Note that

auto scope = tracing::Span::CurrentSpan().CreateScopeTime();

is equivalent to

tracing::Span scope;

CreateScopeTime() [2/2]

ScopeTime tracing::Span::CreateScopeTime

(

std::string

name

)

Creates a tracing::ScopeTime attached to the Span and starts measuring execution time.

Note that

auto scope = tracing::Span::CurrentSpan().CreateScopeTime(name);

is equivalent to

tracing::Span scope{name};

CurrentSpan()

static Span & tracing::Span::CurrentSpan ( )

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.

DetachFromCoroStack()

void tracing::Span::DetachFromCoroStack

(

)

Detach the Span from current engine::Task so it is not returned by CurrentSpan() any more.

GetTotalDuration()

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.

GetTotalElapsedTime()

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()

MakeSpan() [1/2]

static Span tracing::Span::MakeSpan ( std::string  name, std::string_view  trace_id, std::string_view  parent_span_id  )

static

Returns

A new Span attached to current Span (if any).

MakeSpan() [2/2]

static Span tracing::Span::MakeSpan ( std::string  name, std::string_view  trace_id, std::string_view  parent_span_id, std::string  link  )

static

Returns

A new Span attached to current Span (if any), sets link.

ShouldLogDefault()

bool tracing::Span::ShouldLogDefault ( ) const

noexcept

Returns

true if this span would be logged with the current local and global log levels to the default logger.

Friends And Related Function Documentation

SpanBuilder

friend class SpanBuilder

friend

Definition at line 207 of file span.hpp.

---

The documentation for this class was generated from the following file:

• userver/tracing/span.hpp