#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, provided that you Append components::LoggingConfigurator component or use components::CommonComponentList.

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 35 of file span.hpp.

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 (std::string_view scope_name) const

ScopeTime::DurationMillis	GetTotalElapsedTime (std::string_view 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 noexcept
	See tracing::Span::SetLogLevel.

void	SetLocalLogLevel (std::optional< logging::Level > log_level) noexcept
	Sets the log level for the scope of this `Span` and nested scopes recursively.

std::optional< logging::Level >	GetLocalLogLevel () const noexcept
	See tracing::Span::SetLocalLogLevel.

void	SetLink (std::string_view link)

void	SetParentLink (std::string_view parent_link)

std::string_view	GetLink () const noexcept

std::string_view	GetParentLink () const noexcept

std::string_view	GetTraceId () const noexcept

std::string_view	GetSpanId () const noexcept
	Identifies a specific span. It does not propagate.

std::string_view	GetParentId () const noexcept
	Span ID of the nearest loggable parent span, or empty string if none exists.

std::optional< std::string_view >	GetSpanIdForChildLogs () const noexcept

std::string_view	GetName () const noexcept
	Get name the Span was created with.

bool	ShouldLogDefault () const noexcept

bool	IsSampled () const noexcept

void	SetSampled (bool sampled) noexcept

void	DetachFromCoroStack () noexcept

void	AttachToCoroStack ()

std::chrono::system_clock::time_point	GetStartSystemTime () const noexcept

std::chrono::steady_clock::time_point	GetStartSteadyTime () const noexcept

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

Constructor & Destructor Documentation

◆ Span() [1/2]

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

◆ Span() [2/2]

tracing::Span::Span	(	std::string	name,
		const Span *	parent,
		ReferenceType	reference_type = ReferenceType::kChild,
		const utils::impl::SourceLocation &	source_location = utils::impl::SourceLocation::Current() )

explicit

Sets an arbitrary Span as parent. If parent == nullptr, then creates a root Span.

Useful in extremely rare cases. Prefer the constructor above by default.

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.

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

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

noexcept

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

◆ GetLink()

std::string_view tracing::Span::GetLink ( ) const

noexcept

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.

◆ GetParentLink()

std::string_view tracing::Span::GetParentLink ( ) const

noexcept

Set parent link - request ID of the upstream service. Can only be called once.

Propagates within a single service.

◆ GetSpanIdForChildLogs()

std::optional< std::string_view > tracing::Span::GetSpanIdForChildLogs ( ) const

noexcept

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.

◆ GetTotalDuration()

ScopeTime::Duration tracing::Span::GetTotalDuration ( std::string_view 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 ( std::string_view 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()

std::string_view tracing::Span::GetTraceId ( ) const

noexcept

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

◆ IsSampled()

bool tracing::Span::IsSampled ( ) const

noexcept

Returns: true if this span is sampled. Defaults to true for root spans and when the incoming sampled status is unknown. Unsampled spans are not written to the tracing system. Inherited by child spans.

◆ MakeRootSpan()

static Span tracing::Span::MakeRootSpan	(	std::string	name,
		const utils::impl::SourceLocation &	source_location = utils::impl::SourceLocation::Current() )

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
source_location	Implementation detail, do not touch.

◆ MakeSpan() [1/2]

static Span tracing::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

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

Returns: A new Span with the specified IDs.

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, can be empty.
source_location	Implementation detail, do not touch.

◆ MakeSpan() [2/2]

static Span tracing::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

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

Returns: A new Span with the specified IDs.

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, can be empty.
link	The new Link; if empty the Link is autogenerated.
source_location	Implementation detail, do not touch.

◆ SetLink()

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.

◆ SetLocalLogLevel()

void tracing::Span::SetLocalLogLevel ( std::optional< logging::Level > log_level )

noexcept

Sets the log level for the scope of this Span and nested scopes recursively.

Overrides the global log level in both directions: can raise the threshold (suppress logs) or lower it (enable debug logs even if the global level is higher).

For example, if the global log level is info, and the current Span has local log level debug, then all LOG_DEBUGs within the current scope will be written.

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.

◆ SetLogLevel()

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:

nested logs are still written to the logging system;
they inherit trace_id, link and span_id of the nearest written Span object;
tags are still inherited from the nearest Span even if it is hidden;
- this allows to use Spans as tag scopes regardless of their tracing purposes.

Tracing systems use span's log level to highlight warning and error spans.

◆ SetParentLink()

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.

◆ SetSampled()

void tracing::Span::SetSampled ( bool sampled )

noexcept

Mark this span and all future child spans as sampled or unsampled. Unsampled spans are not written to the tracing system.

Called automatically by userver handler implementations when OTel trace sampling is enabled (see otel-trace-sampling-enabled in tracing::DefaultTracingManagerLocator). Can also be called manually in periodics and other primary sources of a request chain to control the fraction of traces written.

◆ 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

◆ engine::TracePlugin

friend class engine::TracePlugin

friend

Definition at line 318 of file span.hpp.

◆ InPlaceSpan

friend class InPlaceSpan

friend

Definition at line 317 of file span.hpp.

◆ SpanBuilder

friend class SpanBuilder

friend

Definition at line 315 of file span.hpp.

◆ TagScope

friend class TagScope

friend

Definition at line 316 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() [1/2]

◆ Span() [2/2]

Member Function Documentation

◆ AddNonInheritableTag()

◆ AddTag()

◆ AddTagFrozen()

◆ AttachToCoroStack()

◆ CreateChild()

◆ CreateScopeTime()

◆ CurrentSpan()

◆ DetachFromCoroStack()

◆ GetLink()

◆ GetParentLink()

◆ GetSpanIdForChildLogs()

◆ GetTotalDuration()

◆ GetTotalElapsedTime()

◆ GetTraceId()

◆ IsSampled()

◆ MakeRootSpan()

◆ MakeSpan() [1/2]

◆ MakeSpan() [2/2]

◆ SetLink()

◆ SetLocalLogLevel()

◆ SetLogLevel()

◆ SetParentLink()

◆ SetSampled()

◆ ShouldLogDefault()

Friends And Related Symbol Documentation

◆ engine::TracePlugin

◆ InPlaceSpan

◆ SpanBuilder

◆ TagScope