#include <userver/tracing/span.hpp>

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.

Logging of spans can be controlled at runtime via USERVER_NO_LOG_SPANS.

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/main.cpp.

Definition at line 33 of file 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.

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
	Returns level for tags logging.

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

void	SetParentLink (std::string parent_link)
	Set parent_link - an ID . Can be called only once.

std::string	GetLink () const

std::string	GetParentLink () const

const std::string &	GetTraceId () const

const std::string &	GetSpanId () const
	Identifies a specific span. It does not propagate.

const std::string &	GetParentId () const

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)

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

static Span	MakeRootSpan (std::string name, logging::Level log_level=logging::Level::kInfo)

Constructor & Destructor Documentation

◆ Span()

tracing::Span::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() )

explicit

Use default tracer and implicit coro local storage for parent identification, takes TraceID from the parent.

For extremely rare cases where a new Trace ID is required use tracing::Span::MakeSpan().

Member Function Documentation

◆ AddNonInheritableTag()

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.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ 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.

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

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.

Note: name parameter is expected to satisfy snake case. Otherwise, it is converted to snake case.

◆ 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.

◆ GetLink()

std::string 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

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

◆ GetTraceId()

const std::string & 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

◆ MakeRootSpan()

static Span tracing::Span::MakeRootSpan	(	std::string	name,
		logging::Level	log_level = logging::Level::kInfo )

static

Factory function for rare cases of creating a root Span that starts the trace_id chain, ignoring CurrentSpan, if any. Useful in background jobs, periodics, distlock tasks, cron tasks, etc. The result of such jobs is not directly requested by anything.

Returns: A new Span that is the root of a new Span hierarchy.

Parameters

name	Name of a new Span
log_level	Log level for the span's own log record

◆ MakeSpan() [1/2]

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

static

Factory function for extremely rare cases of creating a Span with custom IDs; prefer Span constructor instead.

Returns: A new Span attached to current Span (if any) but with a new Trace ID.

Parameters

name	Name of a new Span
trace_id	New Trace ID; if empty then the Trace ID is autogenerated
parent_span_id	Id of the parent Span, could be empty.

◆ 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

Factory function for extremely rare cases of creating a Span with custom IDs; prefer Span constructor instead.

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

Parameters

name	Name of a new Span
trace_id	New Trace ID; if empty then the Trace ID is autogenerated
parent_span_id	Id of the parent Span, could be empty.
link	The new link

◆ SetLink()

void tracing::Span::SetLink ( std::string 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

◆ SetLocalLogLevel()

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_INFOs within the current scope will be thrown away.

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_DEBUGs within the current scope will still be thrown away.

◆ SetLogLevel()

void tracing::Span::SetLogLevel ( logging::Level log_level )

Sets log level with which the current span itself is written into the tracing system.

If Span's log level is less than the global logger's log level, then the span is not written out. In that case, nested logs are still written to the logging system as usual, inheriting trace_id, link, span_id and inheritable tags of the current Span object.

◆ 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 Symbol Documentation

◆ SpanBuilder

friend class SpanBuilder

friend

Definition at line 263 of file span.hpp.

◆ TagScope

friend class TagScope

friend

Definition at line 264 of file span.hpp.

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

userver/tracing/span.hpp

Detailed Description

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

◆ Span()

Member Function Documentation

◆ AddNonInheritableTag()

◆ AddTag()

◆ AddTagFrozen()

◆ AttachToCoroStack()

◆ CreateChild()

◆ CreateScopeTime()

◆ CurrentSpan()

◆ DetachFromCoroStack()

◆ GetLink()

◆ GetTotalDuration()

◆ GetTotalElapsedTime()

◆ GetTraceId()

◆ MakeRootSpan()

◆ MakeSpan() [1/2]

◆ MakeSpan() [2/2]

◆ SetLink()

◆ SetLocalLogLevel()

◆ SetLogLevel()

◆ ShouldLogDefault()

Friends And Related Symbol Documentation

◆ SpanBuilder

◆ TagScope