ARCHIVE/rippled
1
0
Fork 0
mirror of https://github.com/XRPLF/rippled.git synced 2026-07-24 07:30:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'pratik/otel-phase3-tx-tracing' into pratik/otel-phase4-consensus-tracing

Browse Source 
# Conflicts:
#	src/libxrpl/telemetry/SpanGuard.cpp
This commit is contained in:
Pratik Mankawde
2026-07-21 20:43:10 +01:00
parent 75cbf35e0d bb49b02d7d
commit fbb79d73fb
11 changed files with 1226 additions and 516 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
src/libxrpl/telemetry/DeterministicIdGenerator.cpp Normal file
View File

@@ -0,0 +1,92 @@
/**
* Implementation of DeterministicIdGenerator and PendingTraceId.
*
* The pending trace_id lives in file-local thread_locals shared between the
* generator and the RAII guard. GenerateTraceId() consumes the pending id on
* the SDK's no-parent branch; PendingTraceId sets it and asserts consumption.
* All OpenTelemetry SDK types stay confined to telemetry translation units.
*
* @see DeterministicIdGenerator, PendingTraceId (DeterministicIdGenerator.h)
*/
#ifdef XRPL_ENABLE_TELEMETRY
#include <xrpl/telemetry/DeterministicIdGenerator.h>
#include <xrpl/beast/utility/instrumentation.h>
#include <opentelemetry/nostd/span.h>
#include <opentelemetry/sdk/trace/random_id_generator_factory.h>
#include <opentelemetry/trace/span_id.h>
#include <opentelemetry/trace/trace_id.h>
#include <array>
#include <cstdint>
#include <optional>
namespace xrpl::telemetry {
namespace {
/**
* Trace_id pinned by PendingTraceId, consumed by GenerateTraceId(). File-local
* and thread-local, so it is set and read on the same thread with no locking.
*/
thread_local std::optional<std::array<std::uint8_t, 16>> tlsPendingTraceId;
/**
* True once GenerateTraceId() has consumed the pending id. ~PendingTraceId
* asserts on it to catch a forced-root span that never reached the SDK root
* branch.
*/
thread_local bool tlsPendingConsumed = false;
} // namespace
DeterministicIdGenerator::DeterministicIdGenerator()
: opentelemetry::sdk::trace::IdGenerator(/*is_random=*/false)
, random_(opentelemetry::sdk::trace::RandomIdGeneratorFactory::Create())
{
}
opentelemetry::trace::TraceId
DeterministicIdGenerator::GenerateTraceId() noexcept
{
if (tlsPendingTraceId)
{
auto const id = *tlsPendingTraceId;
tlsPendingTraceId.reset();
tlsPendingConsumed = true;
return opentelemetry::trace::TraceId(
opentelemetry::nostd::span<std::uint8_t const, 16>(id.data(), 16));
}
return random_->GenerateTraceId();
}
opentelemetry::trace::SpanId
DeterministicIdGenerator::GenerateSpanId() noexcept
{
return random_->GenerateSpanId(); // ALWAYS random — never uses the pending id
}
PendingTraceId::PendingTraceId(std::array<std::uint8_t, 16> const& id) noexcept
{
tlsPendingTraceId = id;
tlsPendingConsumed = false;
}
PendingTraceId::~PendingTraceId() noexcept
{
// The forced no-parent (root) span-start MUST have consumed the pending id
// via GenerateTraceId(). If not, the SDK took a different branch than the
// caller forced — a bug — so fail loudly in debug/test builds.
XRPL_ASSERT(
tlsPendingConsumed,
"xrpl::telemetry::PendingTraceId : deterministic trace_id was not consumed");
tlsPendingTraceId.reset(); // never leak, even in release
tlsPendingConsumed = false;
}
} // namespace xrpl::telemetry
#endif // XRPL_ENABLE_TELEMETRY

354
src/libxrpl/telemetry/SpanGuard.cpp
View File

@@ -1,23 +1,26 @@
/**
* Pimpl implementation for SpanGuard and SpanContext.
* Pimpl implementation for SpanGuard, ScopedSpanGuard and SpanContext.
*
* All OpenTelemetry SDK types are confined to this translation unit.
* The public SpanGuard.h header contains only standard-library types
* and forward-declares the Impl struct.
* and forward-declares the Impl / ScopedImpl structs.
*
* Two guards with split responsibilities live here:
* - SpanGuard::Impl holds ONLY the OTel Span (shared_ptr). It never
* touches the thread-local context stack, so a SpanGuard is
* thread-free and may be moved to and destroyed on any thread.
* - ScopedSpanGuard::ScopedImpl holds a SpanGuard plus an optional
* Scope. The Scope pushes the span onto the constructing thread's
* context stack; member order (guard first, scope second) ensures
* the Scope pops BEFORE the span ends on destruction. It is
* thread-bound: construct and destroy on the same thread.
*
* Static factory methods access the global Telemetry instance via
* Telemetry::getInstance(), check whether the requested TraceCategory
* is enabled, and return either an active guard with a real Span+Scope
* or a null guard whose methods are all no-ops.
* is enabled, and return either an active guard with a real Span or a
* null guard whose methods are all no-ops.
*
* The Impl struct holds the OTel Span (shared_ptr) and an optional
* Scope. Scope is non-movable, but since Impl lives behind a
* unique_ptr, SpanGuard's move constructor simply transfers the
* pointer — no double-Scope issues. A scoped guard holds the Scope;
* detached() produces an Impl with no Scope (nullopt) so the guard
* carries no thread-local binding and is safe to move across threads.
*
* @see SpanGuard (SpanGuard.h), Telemetry (Telemetry.h),
* @see SpanGuard, ScopedSpanGuard (SpanGuard.h), Telemetry (Telemetry.h),
* FilteringSpanProcessor (Telemetry.cpp)
*/
@@ -25,8 +28,8 @@
#include <xrpl/telemetry/SpanGuard.h>
#include <xrpl/basics/random.h>
#include <xrpl/beast/utility/instrumentation.h>
#include <xrpl/telemetry/DeterministicIdGenerator.h>
#include <xrpl/telemetry/DiscardFlag.h>
#include <xrpl/telemetry/Telemetry.h>
#include <xrpl/telemetry/TraceContextPropagator.h>
@@ -47,6 +50,7 @@
#include <opentelemetry/trace/trace_flags.h>
#include <opentelemetry/trace/trace_id.h>
#include <array>
#include <cstdint>
#include <cstring>
#include <exception>
@@ -90,65 +94,22 @@ SpanContext::isValid() const
struct SpanGuard::Impl
{
/**
* The OTel span being guarded. Set to nullptr after discard() or
* once detached() moves it into a new guard, so ~Impl skips End().
* The OTel span being guarded. Set to nullptr after discard() so
* ~Impl skips End().
*/
opentelemetry::nostd::shared_ptr<otel_trace::Span> span;
/**
* Scope that activates span on the current thread's context stack.
* nullopt for a detached guard, which holds the span with no
* thread-local binding and is therefore safe to move across threads.
*/
std::optional<otel_trace::Scope> scope;
/**
* Thread that constructed this Impl. Meaningful only when `scope`
* holds a value: a Scope is bound to the thread-local context stack
* of the thread that pushed it, so popping it (via ~Scope, when
* ~Impl runs) on a different thread corrupts that thread's stack.
* Checked in ~Impl() and detached() to turn a silent cross-thread
* corruption into an assertion failure in debug/test/fuzzing builds.
*/
std::thread::id owner{std::this_thread::get_id()};
/**
* Construct a scoped guard: the span is pushed onto this thread's
* active-context stack for the lifetime of the guard.
* Construct an unscoped guard: the span is owned but NOT pushed
* onto any thread's context stack. The guard is thread-free.
* @param s The span to guard.
*/
explicit Impl(opentelemetry::nostd::shared_ptr<otel_trace::Span> s) : span(std::move(s))
{
scope.emplace(span);
}
/**
* Tag type selecting the scope-less (detached) constructor.
*/
struct Detached
{
};
/**
* Construct a detached guard: the span is held with NO thread-local
* Scope, so the guard carries no context-stack binding and is safe
* to move to and destroy on another thread.
* @param s The span to guard.
*/
Impl(opentelemetry::nostd::shared_ptr<otel_trace::Span> s, Detached) : span(std::move(s))
{
}
~Impl()
{
// A live Scope (scope engaged) must be popped on the thread that
// pushed it; ending on any other thread corrupts that thread's
// context stack. A detached guard (scope == nullopt) carries no
// binding and may be destroyed anywhere, so the check is skipped.
XRPL_ASSERT(
!scope.has_value() || owner == std::this_thread::get_id(),
"xrpl::telemetry::SpanGuard::Impl::~Impl : scoped guard destroyed on "
"constructing thread");
if (span)
span->End();
}
@@ -166,6 +127,8 @@ struct SpanGuard::Impl
SpanGuard::SpanGuard() = default;
SpanGuard::~SpanGuard() = default;
SpanGuard::SpanGuard(SpanGuard&&) noexcept = default;
SpanGuard&
SpanGuard::operator=(SpanGuard&&) noexcept = default;
SpanGuard::SpanGuard(std::unique_ptr<Impl> impl) : impl_(std::move(impl))
{
@@ -248,7 +211,7 @@ SpanGuard::span(TraceCategory cat, std::string_view prefix, std::string_view nam
}
SpanGuard
SpanGuard::rootSpan(TraceCategory cat, std::string_view prefix, std::string_view name)
SpanGuard::freshRoot(TraceCategory cat, std::string_view prefix, std::string_view name)
{
auto* tel = Telemetry::getInstance();
if ((tel == nullptr) || !tel->isEnabled() || !isCategoryEnabled(*tel, cat))
@@ -342,45 +305,9 @@ SpanGuard::linkedSpan(std::string_view name, SpanContext const& linkCtx)
// LCOV_EXCL_STOP
}
SpanGuard
SpanGuard::detached() &&
{
if (!impl_)
return {};
// Popping the Scope (below, via impl_.reset()) must happen on the thread
// that pushed it; calling detached() elsewhere would pop the wrong stack.
XRPL_ASSERT(
!impl_->scope.has_value() || impl_->owner == std::this_thread::get_id(),
"xrpl::telemetry::SpanGuard::detached : called on constructing thread");
// Take the span out; the old Impl.span is now null so ~Impl won't End().
auto s = std::move(impl_->span);
// Resetting the old Impl destroys its Scope HERE, on the origin thread,
// popping this thread's context stack correctly. The returned guard holds
// the span with no Scope, so it is safe to move to another thread.
impl_.reset();
return SpanGuard(std::make_unique<Impl>(std::move(s), Impl::Detached{}));
}
// ===== Detach-in-place helpers =============================================
void
detachInPlace(std::optional<SpanGuard>& guard)
{
if (!guard || !*guard)
return;
guard.emplace(std::move(*guard).detached());
}
std::shared_ptr<SpanGuard>
detachInPlace(std::shared_ptr<SpanGuard> guard)
{
if (!guard || !*guard)
return guard;
return std::make_shared<SpanGuard>(std::move(*guard).detached());
}
// ===== Hash-derived span (category-gated) ==================================
// Standalone hash-derived span: a TRUE root whose trace_id == hashData[0:16].
SpanGuard
SpanGuard::hashSpan(
TraceCategory const cat,
@@ -395,23 +322,19 @@ SpanGuard::hashSpan(
if ((tel == nullptr) || !tel->isEnabled() || !isCategoryEnabled(*tel, cat))
return {};
otel_trace::TraceId const traceId(
opentelemetry::nostd::span<std::uint8_t const, 16>(hashData, 16));
auto const rval = defaultPrng()();
std::uint8_t spanIdBytes[8];
std::memcpy(spanIdBytes, &rval, sizeof(spanIdBytes));
otel_trace::SpanId const spanId(
opentelemetry::nostd::span<std::uint8_t const, 8>(spanIdBytes, 8));
otel_trace::SpanContext const syntheticCtx(
traceId, spanId, otel_trace::TraceFlags(1), /* remote = */ false);
auto parentCtx = opentelemetry::context::Context{}.SetValue(
otel_trace::kSpanKey,
opentelemetry::nostd::shared_ptr<otel_trace::Span>(
new otel_trace::DefaultSpan(syntheticCtx)));
// Force the deterministic trace_id via the DeterministicIdGenerator, on the
// SDK root branch, so the span is a TRUE root (empty parent_span_id) whose
// trace_id == hashData[0:16]. The kIsRootSpanKey context forces the SDK's
// no-valid-parent branch, where GenerateTraceId() is called and returns the
// pending id. The PendingTraceId guard scopes that id to this one startSpan.
std::array<std::uint8_t, 16> tid{};
std::memcpy(tid.data(), hashData, 16);
auto rootCtx = opentelemetry::context::Context{otel_trace::kIsRootSpanKey, true};
PendingTraceId const pending{tid};
// When a prior context is supplied, attach it as a follows-from LINK (not a
// parent) so consecutive roots (e.g. consensus rounds) stay navigable while
// this span remains a true root under its deterministic trace_id.
if (followsFrom != nullptr && followsFrom->isValid())
{
auto linkSpan = otel_trace::GetSpan(followsFrom->impl_->ctx);
@@ -419,7 +342,7 @@ SpanGuard::hashSpan(
{
auto tracer = tel->getTracer("xrpld");
otel_trace::StartSpanOptions opts;
opts.parent = parentCtx;
opts.parent = rootCtx; // root marker → forces GenerateTraceId()
opts.kind = categoryToSpanKind(cat);
return SpanGuard(
std::make_unique<Impl>(tracer->StartSpan(
@@ -430,9 +353,13 @@ SpanGuard::hashSpan(
}
}
return SpanGuard(std::make_unique<Impl>(tel->startSpan(std::string(name), parentCtx)));
return SpanGuard(
std::make_unique<Impl>(
tel->startSpan(std::string(name), rootCtx, categoryToSpanKind(cat))));
}
// Cross-node hash-derived span: a CHILD of the sender's real remote span
// (remote=true), not a root — so it must NOT use PendingTraceId / rootCtx.
SpanGuard
SpanGuard::hashSpan(
TraceCategory const cat,
@@ -633,6 +560,201 @@ SpanGuard::discard()
}
}
// ===== ScopedSpanGuard::ScopedImpl =========================================
struct ScopedSpanGuard::ScopedImpl
{
/**
* The unscoped guard that owns the span. Declared FIRST so it is
* destroyed AFTER `scope`: the Scope must pop before the span ends.
*/
SpanGuard guard;
/**
* Active OTel Scope binding the span to this thread's context stack.
* Present while the guard is active; reset() (via operator SpanGuard)
* pops it eagerly on the origin thread. Declared AFTER `guard` so
* destruction order pops the scope before the span ends.
*/
std::optional<otel_trace::Scope> scope;
/**
* Thread that constructed this ScopedImpl. The Scope is bound to
* this thread's context stack, so popping it (via ~Scope or reset())
* on a different thread corrupts that thread's stack. Checked in the
* destructor and operator SpanGuard() to turn a silent cross-thread
* corruption into an assertion failure in debug/test/fuzzing builds.
*/
std::thread::id owner{std::this_thread::get_id()};
/**
* Wrap a SpanGuard and activate its span on this thread. If the
* guard is active, push its span onto the thread-local context
* stack; a null guard leaves `scope` empty.
* @param g The span-owning guard to activate.
*/
explicit ScopedImpl(SpanGuard g) : guard(std::move(g))
{
if (guard)
scope.emplace(guard.impl_->span);
}
};
// ===== ScopedSpanGuard core lifecycle ======================================
ScopedSpanGuard::ScopedSpanGuard(SpanGuard&& guard)
: impl_(std::make_unique<ScopedImpl>(std::move(guard)))
{
}
ScopedSpanGuard::~ScopedSpanGuard()
{
// A live Scope must be popped on the thread that pushed it; destroying
// the guard on any other thread corrupts that thread's context stack.
// A null guard holds no Scope, so the check is skipped.
XRPL_ASSERT(
!impl_ || !impl_->scope.has_value() || impl_->owner == std::this_thread::get_id(),
"xrpl::telemetry::ScopedSpanGuard::~ScopedSpanGuard : destroyed on "
"constructing thread");
}
// ===== ScopedSpanGuard factory methods =====================================
ScopedSpanGuard::ScopedSpanGuard(TraceCategory cat, std::string_view prefix, std::string_view name)
: ScopedSpanGuard(SpanGuard::span(cat, prefix, name))
{
}
ScopedSpanGuard
ScopedSpanGuard::freshRoot(TraceCategory cat, std::string_view prefix, std::string_view name)
{
return ScopedSpanGuard(SpanGuard::freshRoot(cat, prefix, name));
}
ScopedSpanGuard
ScopedSpanGuard::childSpan(std::string_view name) const
{
return ScopedSpanGuard(impl_->guard.childSpan(name));
}
ScopedSpanGuard
ScopedSpanGuard::childSpan(std::string_view name, SpanContext const& parentCtx)
{
return ScopedSpanGuard(SpanGuard::childSpan(name, parentCtx));
}
ScopedSpanGuard
ScopedSpanGuard::linkedSpan(std::string_view name) const
{
return ScopedSpanGuard(impl_->guard.linkedSpan(name));
}
ScopedSpanGuard
ScopedSpanGuard::linkedSpan(std::string_view name, SpanContext const& linkCtx)
{
return ScopedSpanGuard(SpanGuard::linkedSpan(name, linkCtx));
}
// ===== ScopedSpanGuard handoff bridge ======================================
ScopedSpanGuard::
operator SpanGuard() &&
{
// The scope must be popped on the thread that pushed it; handing off
// elsewhere would pop the wrong stack.
XRPL_ASSERT(
impl_->owner == std::this_thread::get_id(),
"xrpl::telemetry::ScopedSpanGuard::operator SpanGuard : handoff on "
"constructing thread");
impl_->scope.reset(); // eager pop, on the origin thread
return std::move(impl_->guard);
}
// ===== ScopedSpanGuard context capture =====================================
SpanContext
ScopedSpanGuard::captureContext() const
{
return impl_->guard.captureContext();
}
// ===== ScopedSpanGuard forwarding methods ==================================
void
ScopedSpanGuard::setAttribute(std::string_view key, std::string_view value)
{
impl_->guard.setAttribute(key, value);
}
void
ScopedSpanGuard::setAttribute(std::string_view key, char const* value)
{
impl_->guard.setAttribute(key, value);
}
void
ScopedSpanGuard::setAttribute(std::string_view key, std::int64_t value)
{
impl_->guard.setAttribute(key, value);
}
void
ScopedSpanGuard::setAttribute(std::string_view key, double value)
{
impl_->guard.setAttribute(key, value);
}
void
ScopedSpanGuard::setAttribute(std::string_view key, bool value)
{
impl_->guard.setAttribute(key, value);
}
void
ScopedSpanGuard::setOk()
{
impl_->guard.setOk();
}
void
ScopedSpanGuard::setError(std::string_view description)
{
impl_->guard.setError(description);
}
void
ScopedSpanGuard::addEvent(std::string_view name)
{
impl_->guard.addEvent(name);
}
void
ScopedSpanGuard::recordException(std::exception const& e)
{
impl_->guard.recordException(e);
}
void
ScopedSpanGuard::discard()
{
// A live Scope must be popped on the thread that pushed it; discarding
// on any other thread corrupts that thread's context stack. A null guard
// holds no Scope, so the check is skipped.
XRPL_ASSERT(
!impl_ || !impl_->scope.has_value() || impl_->owner == std::this_thread::get_id(),
"xrpl::telemetry::ScopedSpanGuard::discard : discarded on constructing thread");
// Pop the scope first (on this thread) so no span stays active on the
// stack, then discard the span via the owned guard.
impl_->scope.reset();
impl_->guard.discard();
}
ScopedSpanGuard::
operator bool() const
{
return impl_ && static_cast<bool>(impl_->guard);
}
} // namespace xrpl::telemetry
#endif // XRPL_ENABLE_TELEMETRY

11
src/libxrpl/telemetry/Telemetry.cpp
View File

@@ -20,6 +20,7 @@
#include <xrpl/basics/Log.h>
#include <xrpl/beast/utility/Journal.h>
#include <xrpl/telemetry/DeterministicIdGenerator.h>
#include <xrpl/telemetry/DiscardFlag.h>
#include <xrpl/telemetry/SpanNames.h>
@@ -329,9 +330,15 @@ public:
std::make_shared<trace_sdk::TraceIdRatioBasedSampler>(setup_.samplingRatio);
auto sampler = trace_sdk::ParentBasedSamplerFactory::Create(std::move(rootSampler));
// Create TracerProvider
// Create TracerProvider with a DeterministicIdGenerator. It returns a
// deterministic trace_id when a PendingTraceId is active on the thread,
// else a random one — letting hash-derived roots (introduced on a later
// branch) become true trace roots. Dormant until such a caller exists.
sdkProvider_ = trace_sdk::TracerProviderFactory::Create(
std::move(processor), resourceAttrs, std::move(sampler));
std::move(processor),
resourceAttrs,
std::move(sampler),
std::make_unique<DeterministicIdGenerator>());
// Set as global provider
trace_api::Provider::SetTracerProvider(

495
src/tests/libxrpl/telemetry/SpanGuardScope.cpp
View File

@@ -1,10 +1,19 @@
// Tests for SpanGuard::rootSpan() and SpanGuard::detached().
// Tests for SpanGuard, ScopedSpanGuard and DeterministicIdGenerator.
//
// These verify the cross-thread scope-leak fix at the trace level using an
// in-memory span exporter: rootSpan() must start a fresh trace root (ignoring
// the ambient active span), and detached() must strip the thread-local Scope
// on the origin thread so the guard can be moved to and ended on another
// thread without corrupting the origin thread's context stack.
// These verify the span-guard split and the deterministic-root fix at the
// trace level using an in-memory span exporter:
// - SpanGuard is unscoped and thread-free: it owns only the span, never the
// OTel thread-local context stack, so it may be moved to and ended on any
// thread. SpanGuard::freshRoot() starts a brand-new trace root, ignoring
// the ambient active span.
// - ScopedSpanGuard is scoped and thread-bound: it also pushes an OTel Scope
// so the span is the ambient parent on the constructing thread. Its
// `operator SpanGuard() &&` pops that Scope eagerly on the origin thread and
// yields a thread-free SpanGuard; destroying it on another thread trips an
// owner-thread assertion.
// - DeterministicIdGenerator (installed by the test TracerProvider) mints a
// caller-pinned trace_id for a forced-root span. PendingTraceId pins the id
// for one root span; an ambient child under a live parent never adopts it.
//
// The whole file is telemetry-only: when XRPL_ENABLE_TELEMETRY is not defined
// SpanGuard is a no-op stub and the OpenTelemetry SDK headers are unavailable,
@@ -12,11 +21,13 @@
#ifdef XRPL_ENABLE_TELEMETRY
#include <xrpl/telemetry/DeterministicIdGenerator.h>
#include <xrpl/telemetry/SpanGuard.h>
#include <xrpl/telemetry/Telemetry.h>
#include <gtest/gtest.h>
#include <opentelemetry/context/context.h>
#include <opentelemetry/context/runtime_context.h>
#include <opentelemetry/exporters/memory/in_memory_span_data.h>
#include <opentelemetry/exporters/memory/in_memory_span_exporter_factory.h>
#include <opentelemetry/nostd/shared_ptr.h>
@@ -26,16 +37,20 @@
#include <opentelemetry/sdk/trace/span_data.h>
#include <opentelemetry/sdk/trace/tracer_provider.h>
#include <opentelemetry/sdk/trace/tracer_provider_factory.h>
#include <opentelemetry/trace/context.h>
#include <opentelemetry/trace/span.h>
#include <opentelemetry/trace/span_context.h>
#include <opentelemetry/trace/span_id.h>
#include <opentelemetry/trace/span_metadata.h>
#include <opentelemetry/trace/span_startoptions.h>
#include <opentelemetry/trace/trace_id.h>
#include <opentelemetry/trace/tracer.h>
#include <array>
#include <cstddef>
#include <cstdint>
#include <cstring>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <thread>
@@ -54,7 +69,9 @@ namespace otel_memory = opentelemetry::exporter::memory;
* Reports every trace category as enabled and creates spans through an SDK
* TracerProvider whose SimpleSpanProcessor forwards ended spans to an
* InMemorySpanExporter, so a test can read the exact exported SpanData
* (trace id, span id, parent id, name).
* (trace id, span id, parent id, name). The provider is built with a
* DeterministicIdGenerator so PendingTraceId can pin the trace_id of a
* forced-root span.
*
* Inheritance:
*
@@ -81,16 +98,19 @@ public:
// Factory populates spanData_ with the exporter's shared buffer.
auto exporter = otel_memory::InMemorySpanExporterFactory::Create(spanData_);
auto processor = otel_sdk_trace::SimpleSpanProcessorFactory::Create(std::move(exporter));
// Install the DeterministicIdGenerator (4-arg overload) so a
// PendingTraceId can pin a forced-root span's trace_id in tests.
provider_ = otel_sdk_trace::TracerProviderFactory::Create(
std::move(processor),
opentelemetry::sdk::resource::Resource::Create({}),
otel_sdk_trace::AlwaysOnSamplerFactory::Create());
otel_sdk_trace::AlwaysOnSamplerFactory::Create(),
std::make_unique<DeterministicIdGenerator>());
}
/**
* @return The exporter's span buffer (drained by GetSpans()).
*/
std::shared_ptr<otel_memory::InMemorySpanData>
[[nodiscard]] std::shared_ptr<otel_memory::InMemorySpanData>
spanData() const
{
return spanData_;
@@ -226,6 +246,20 @@ countSpans(
return count;
}
/**
* Build the 16-byte deterministic trace_id used by the generator tests
* (bytes 1..16). Kept out of line so every generator test pins the same id.
* @return The fixed 16-byte trace_id {1, 2, ..., 16}.
*/
std::array<std::uint8_t, 16>
makeTraceIdBytes()
{
std::array<std::uint8_t, 16> h{};
for (int i = 0; i < 16; ++i)
h[i] = static_cast<std::uint8_t>(i + 1);
return h;
}
/**
* Installs a TestTelemetry as the global instance for each test and clears it
* afterwards so the singleton never dangles between cases.
@@ -250,7 +284,7 @@ protected:
/**
* @return The exporter's span buffer for the active TestTelemetry.
*/
std::shared_ptr<otel_memory::InMemorySpanData>
[[nodiscard]] std::shared_ptr<otel_memory::InMemorySpanData>
spanData() const
{
return telemetry_->spanData();
@@ -262,18 +296,18 @@ protected:
std::unique_ptr<TestTelemetry> telemetry_;
};
// rootSpan() must ignore the ambient active span and start a brand-new trace.
TEST_F(SpanGuardScopeTest, rootSpan_ignores_ambient_parent)
// freshRoot() must ignore the ambient active span and start a brand-new trace.
TEST_F(SpanGuardScopeTest, spanGuard_freshRoot_is_true_root_ignoring_ambient)
{
{
// Ambient span becomes the active span on this thread.
auto ambient = SpanGuard::span(TraceCategory::Rpc, "rpc", "command");
ScopedSpanGuard const ambient(TraceCategory::Rpc, "rpc", "command");
ASSERT_TRUE(static_cast<bool>(ambient));
// rootSpan must NOT inherit the ambient span as its parent.
auto root = SpanGuard::rootSpan(TraceCategory::Peer, "peer", "validation.receive");
ASSERT_TRUE(static_cast<bool>(root));
} // root ends first, then ambient -- both on this thread.
// freshRoot must NOT inherit the ambient span as its parent.
auto r = SpanGuard::freshRoot(TraceCategory::Peer, "peer", "validation.receive");
ASSERT_TRUE(static_cast<bool>(r));
} // r ends first, then ambient's scope pops and ambient span ends.
auto spans = spanData()->GetSpans();
auto* ambient = findSpan(spans, "rpc.command");
@@ -285,34 +319,76 @@ TEST_F(SpanGuardScopeTest, rootSpan_ignores_ambient_parent)
EXPECT_FALSE(ambient->GetParentSpanId().IsValid());
EXPECT_TRUE(ambient->GetTraceId().IsValid());
// The rootSpan has NO parent and lives in a DIFFERENT trace than ambient.
// The freshRoot span has NO parent and lives in a DIFFERENT trace.
EXPECT_FALSE(root->GetParentSpanId().IsValid());
EXPECT_TRUE(root->GetTraceId().IsValid());
EXPECT_NE(root->GetTraceId(), ambient->GetTraceId());
}
// detached() pops the Scope on the origin thread, so ending the guard on
// another thread leaves the origin thread's context stack clean.
TEST_F(SpanGuardScopeTest, detached_does_not_corrupt_origin_stack)
// A ScopedSpanGuard is the ambient active span on its thread the moment it is
// constructed: a child created while it is alive parents to its span.
TEST_F(SpanGuardScopeTest, scopedGuard_is_ambient_on_construct)
{
// Scoped guard is active on this (origin) thread.
auto guard = SpanGuard::span(TraceCategory::Ledger, "ledger", "build");
ASSERT_TRUE(static_cast<bool>(guard));
// Strip the thread-local Scope here on the origin thread.
auto detached = std::move(guard).detached();
ASSERT_TRUE(static_cast<bool>(detached));
// End the detached span on a worker thread.
std::thread worker([d = std::move(detached)]() mutable {});
worker.join();
// Back on the origin thread: a new span must be a fresh root, proving the
// origin stack top was restored by detached() (not left holding
// ledger.build).
opentelemetry::trace::SpanId activeId;
{
auto after = SpanGuard::span(TraceCategory::Rpc, "rpc", "command");
ASSERT_TRUE(static_cast<bool>(after));
ScopedSpanGuard const s(TraceCategory::Rpc, "rpc", "process");
ASSERT_TRUE(static_cast<bool>(s));
// While s is alive it is the active span on this thread's context.
auto active =
opentelemetry::trace::GetSpan(opentelemetry::context::RuntimeContext::GetCurrent())
->GetContext();
ASSERT_TRUE(active.IsValid());
activeId = active.span_id();
// A child created here must parent to s's span, proving s is ambient.
auto child = s.childSpan("rpc.dispatch");
ASSERT_TRUE(static_cast<bool>(child));
} // child ends first, then s pops its scope and ends.
auto spans = spanData()->GetSpans();
auto* parent = findSpan(spans, "rpc.process");
auto* child = findSpan(spans, "rpc.dispatch");
ASSERT_NE(parent, nullptr);
ASSERT_NE(child, nullptr);
// The active span observed while s was alive WAS s's span.
EXPECT_TRUE(activeId.IsValid());
EXPECT_EQ(parent->GetSpanId(), activeId);
// The child nested under s: same trace, parent = s's span.
EXPECT_EQ(child->GetParentSpanId(), parent->GetSpanId());
EXPECT_EQ(child->GetTraceId(), parent->GetTraceId());
}
// operator SpanGuard() && pops the Scope eagerly on the origin thread, so the
// span is no longer ambient here and the resulting thread-free guard can be
// ended on a worker thread without corrupting this thread's context stack.
TEST_F(SpanGuardScopeTest, scopedGuard_conversion_pops_scope_on_this_thread)
{
{
ScopedSpanGuard s(TraceCategory::Ledger, "ledger", "build");
ASSERT_TRUE(static_cast<bool>(s));
// Convert to a bare SpanGuard: the scope is popped here, on this thread.
SpanGuard bare = std::move(s);
ASSERT_TRUE(static_cast<bool>(bare));
// The scope is gone: no span is active on this thread now.
auto active =
opentelemetry::trace::GetSpan(opentelemetry::context::RuntimeContext::GetCurrent())
->GetContext();
EXPECT_FALSE(active.IsValid());
// A new ambient span here is a fresh root, NOT nested under build.
{
ScopedSpanGuard const after(TraceCategory::Rpc, "rpc", "command");
ASSERT_TRUE(static_cast<bool>(after));
}
// End the thread-free guard on a worker thread -- no crash.
std::thread worker([g = std::move(bare)]() mutable {});
worker.join();
}
auto spans = spanData()->GetSpans();
@@ -321,243 +397,186 @@ TEST_F(SpanGuardScopeTest, detached_does_not_corrupt_origin_stack)
ASSERT_NE(build, nullptr);
ASSERT_NE(after, nullptr);
// 'after' is a new root: zero parent and a different trace than
// ledger.build.
// The span was exported exactly once, by the worker thread.
EXPECT_EQ(countSpans(spans, "ledger.build"), 1u);
// 'after' did NOT nest under build: fresh root, different trace.
EXPECT_FALSE(after->GetParentSpanId().IsValid());
EXPECT_NE(after->GetTraceId(), build->GetTraceId());
}
// A detached span is ended exactly once, by the worker thread that owns it.
TEST_F(SpanGuardScopeTest, detached_span_ends_once)
{
auto guard = SpanGuard::span(TraceCategory::Ledger, "ledger", "build");
auto detached = std::move(guard).detached();
ASSERT_TRUE(static_cast<bool>(detached));
// Before the worker ends it, the span is still open: nothing exported yet.
auto before = spanData()->GetSpans();
EXPECT_EQ(countSpans(before, "ledger.build"), 0u);
// Ending happens once, on the worker thread, when the guard is destroyed.
{
std::thread worker([d = std::move(detached)]() mutable {});
worker.join();
}
auto after = spanData()->GetSpans();
EXPECT_EQ(countSpans(after, "ledger.build"), 1u);
}
// rootSpan().detached() is the combination used at RPC coroutine entry points
// (e.g. RipplePathFind) that hold a span across a coro yield: the span must be
// a fresh root AND must not leave a Scope on the worker's context stack.
TEST_F(SpanGuardScopeTest, root_then_detached_is_root_and_leaves_stack_clean)
// The SpanGuard produced by the conversion ends the span exactly once: the
// moved-from ScopedSpanGuard must not re-end it on destruction.
TEST_F(SpanGuardScopeTest, scopedGuard_conversion_result_ends_span_once)
{
{
// Ambient span active on this (origin) thread.
auto ambient = SpanGuard::span(TraceCategory::Rpc, "rpc", "command");
ASSERT_TRUE(static_cast<bool>(ambient));
ScopedSpanGuard scoped(TraceCategory::Ledger, "ledger", "build");
ASSERT_TRUE(static_cast<bool>(scoped));
// Fresh root, then detach the Scope on the origin thread.
auto req = SpanGuard::rootSpan(TraceCategory::Rpc, "pathfind", "request").detached();
ASSERT_TRUE(static_cast<bool>(req));
SpanGuard const bare = std::move(scoped);
ASSERT_TRUE(static_cast<bool>(bare));
// End the detached root span on a worker thread (mimics coro resume).
std::thread worker([r = std::move(req)]() mutable {});
worker.join();
// Nothing exported yet: the span is still open.
EXPECT_EQ(countSpans(spanData()->GetSpans(), "ledger.build"), 0u);
// Origin stack must be clean: a new span here is still parented by the
// ambient span (proving the detached root did not linger on the stack).
{
auto child = SpanGuard::span(TraceCategory::Rpc, "rpc", "sub");
ASSERT_TRUE(static_cast<bool>(child));
}
// 'bare' ends the span here on destruction; the moved-from 'scoped'
// guard is destroyed too but must NOT end it a second time.
}
auto spans = spanData()->GetSpans();
auto* ambient = findSpan(spans, "rpc.command");
auto* req = findSpan(spans, "pathfind.request");
auto* child = findSpan(spans, "rpc.sub");
ASSERT_NE(ambient, nullptr);
ASSERT_NE(req, nullptr);
ASSERT_NE(child, nullptr);
// The rooted-then-detached span has NO parent and a DIFFERENT trace.
EXPECT_FALSE(req->GetParentSpanId().IsValid());
EXPECT_NE(req->GetTraceId(), ambient->GetTraceId());
// The detached root did not corrupt the origin stack: 'child' still nests
// under the ambient span (same trace, parent = ambient), NOT under req.
EXPECT_EQ(child->GetParentSpanId(), ambient->GetSpanId());
EXPECT_EQ(child->GetTraceId(), ambient->GetTraceId());
// Exactly one export: not zero (the guard still owns the span) and not two
// (the moved-from scoped guard does not re-end it).
EXPECT_EQ(countSpans(spans, "ledger.build"), 1u);
}
// Death test guarding the cross-thread scope-leak bug.
// A forced-root span started while a PendingTraceId is active adopts that
// pinned 16-byte trace_id and remains a true root (no parent).
TEST_F(SpanGuardScopeTest, deterministicIdGenerator_forced_root_gets_pending_trace_id)
{
auto const h = makeTraceIdBytes();
{
PendingTraceId const pending{h};
auto rootCtx = opentelemetry::context::Context{opentelemetry::trace::kIsRootSpanKey, true};
auto span =
telemetry_->startSpan("tx.receive", rootCtx, opentelemetry::trace::SpanKind::kInternal);
span->End();
} // ~PendingTraceId asserts the id was consumed.
auto spans = spanData()->GetSpans();
ASSERT_EQ(spans.size(), 1u);
// trace_id == the pinned hash.
EXPECT_EQ(std::memcmp(spans[0]->GetTraceId().Id().data(), h.data(), 16), 0);
// TRUE ROOT: no parent.
EXPECT_FALSE(spans[0]->GetParentSpanId().IsValid());
}
// A forced-root span with NO PendingTraceId gets a random (non-zero) trace_id,
// never the deterministic hash -- the safety property when no id is pinned.
TEST_F(SpanGuardScopeTest, deterministicIdGenerator_no_pending_gives_random_root)
{
auto const h = makeTraceIdBytes();
{
auto rootCtx = opentelemetry::context::Context{opentelemetry::trace::kIsRootSpanKey, true};
auto span =
telemetry_->startSpan("tx.receive", rootCtx, opentelemetry::trace::SpanKind::kInternal);
span->End();
}
auto spans = spanData()->GetSpans();
ASSERT_EQ(spans.size(), 1u);
// Random root: valid (non-zero) trace_id...
EXPECT_TRUE(spans[0]->GetTraceId().IsValid());
// ...and NOT the deterministic hash (no pending id leaked in).
EXPECT_NE(std::memcmp(spans[0]->GetTraceId().Id().data(), h.data(), 16), 0);
EXPECT_FALSE(spans[0]->GetParentSpanId().IsValid());
}
// SAFETY: an ambient child under a live parent never adopts a pending id. The
// SDK inherits the parent's trace_id and never calls GenerateTraceId() for the
// child, so the pinned id stays available -- proven here by a trailing
// forced-root span that DOES adopt it (which also consumes the id so
// ~PendingTraceId's consumed-assert holds; see the report for this choice).
TEST_F(SpanGuardScopeTest, deterministicIdGenerator_ambient_child_ignores_pending)
{
auto const h = makeTraceIdBytes();
{
// Ambient parent (a random-id root) active on this thread FIRST, before
// any id is pinned, so the parent itself does not consume it.
ScopedSpanGuard const parent(TraceCategory::Rpc, "rpc", "process");
ASSERT_TRUE(static_cast<bool>(parent));
// Pin the id, then start an ambient child under the live parent.
PendingTraceId const pending{h};
// The child has a valid parent, so the SDK inherits the parent's
// trace_id and never calls GenerateTraceId(): the pending id is ignored.
{
auto child = parent.childSpan("rpc.dispatch");
ASSERT_TRUE(static_cast<bool>(child));
}
// Consume the pinned id with a real forced-root span (its intended use),
// so ~PendingTraceId sees the id as consumed. Its trace_id == h.
{
auto rootCtx =
opentelemetry::context::Context{opentelemetry::trace::kIsRootSpanKey, true};
auto root = telemetry_->startSpan(
"tx.receive", rootCtx, opentelemetry::trace::SpanKind::kInternal);
root->End();
}
} // ~PendingTraceId: consumed == true, assert holds; then parent ends.
auto spans = spanData()->GetSpans();
auto* parent = findSpan(spans, "rpc.process");
auto* child = findSpan(spans, "rpc.dispatch");
auto* root = findSpan(spans, "tx.receive");
ASSERT_NE(parent, nullptr);
ASSERT_NE(child, nullptr);
ASSERT_NE(root, nullptr);
// The ambient child inherited the parent's trace and did NOT adopt h.
EXPECT_EQ(child->GetTraceId(), parent->GetTraceId());
EXPECT_EQ(child->GetParentSpanId(), parent->GetSpanId());
EXPECT_NE(std::memcmp(child->GetTraceId().Id().data(), h.data(), 16), 0);
// The forced-root span DID adopt the pinned id: proof the id was available
// the whole time -- the ambient child simply never requested it.
EXPECT_EQ(std::memcmp(root->GetTraceId().Id().data(), h.data(), 16), 0);
EXPECT_FALSE(root->GetParentSpanId().IsValid());
}
// Death test guarding the cross-thread scope-leak bug, now on ScopedSpanGuard.
//
// This used to be a "negative control": a scoped guard was NOT detached, moved
// to and destroyed on a worker thread (popping the WRONG thread's stack), and
// the test then asserted that a later span on the origin thread had SILENTLY
// inherited the stale span -- proving the corruption happened undetected.
// A ScopedSpanGuard's Scope is bound to the thread that constructed it, so it
// must be destroyed on that same thread. ScopedSpanGuard is non-movable, so it
// cannot be moved into a worker directly; instead we own it through a
// unique_ptr and move only that pointer to a worker thread. Destroying the
// pointer there runs ~ScopedSpanGuard on the WRONG thread, which pops the Scope
// on a foreign context stack -- ~ScopedSpanGuard's owner-thread XRPL_ASSERT
// turns that silent corruption into a loud abort().
//
// SpanGuard::Impl::~Impl now enforces thread affinity with an XRPL_ASSERT: a
// live scope must be destroyed on the thread that created it. In debug/test
// builds (NDEBUG unset) XRPL_ASSERT expands to assert(), so the exact sequence
// above now aborts the process inside the worker thread's destructor instead of
// corrupting the origin stack. The bug therefore moved from "silently wrong" to
// "loudly crashes early" -- the intended tradeoff, since a crash is far easier
// to catch than a corrupted trace hierarchy.
//
// The death happens on the WORKER thread (the moved-in guard is destroyed when
// the worker lambda returns, before worker.join() completes). A failed assert()
// calls abort(), which raises SIGABRT process-wide regardless of which thread
// hit it, so EXPECT_DEATH -- which runs the statement in a forked child and
// checks it dies -- observes the crash. The regex matches the assert message
// substring rather than the whole line, because the file:line/function prefix
// glibc prints around it is platform and compiler dependent.
// The death happens on the WORKER thread (the moved-in unique_ptr is destroyed
// when the worker lambda's captures are torn down, before worker.join()
// completes). A failed assert() calls abort(), which raises SIGABRT
// process-wide regardless of thread, so EXPECT_DEATH -- which runs the
// statement in a forked child and checks it dies -- observes the crash. The
// regex matches the assert message substring; the assert message is written as
// two adjacent string literals in SpanGuard.cpp, so the ".*" bridges the gap
// between "on" and "constructing".
//
// The test is skipped where the assertion cannot fire: under NDEBUG (Release
// builds) XRPL_ASSERT is a no-op, and under ENABLE_VOIDSTAR a failed assert
// continues instead of aborting -- in both cases the worker would not crash and
// EXPECT_DEATH would report a spurious failure.
TEST_F(SpanGuardScopeTest, non_detached_cross_thread_death_asserts_at_wrong_thread_destroy)
TEST_F(SpanGuardScopeTest, scopedGuard_cross_thread_death_asserts_at_wrong_thread_destroy)
{
// XRPL_ASSERT only aborts when assertions are live. Under NDEBUG (Release
// builds) it expands to assert(), which the C standard strips to a no-op,
// so the worker thread destroys the guard without crashing. Under
// ENABLE_VOIDSTAR (Antithesis fuzzing) a failed XRPL_ASSERT continues
// execution instead of aborting. In either case the process does not die
// and EXPECT_DEATH would fail, so skip this test there. The two macros are
// mutually exclusive (instrumentation.h #errors on ENABLE_VOIDSTAR+NDEBUG),
// but both break the death check, so guard against each.
#ifdef NDEBUG
GTEST_SKIP() << "XRPL_ASSERT compiles to a no-op under NDEBUG (Release builds), so the "
"cross-thread scope-leak assertion this test exercises does not fire.";
#elif defined(ENABLE_VOIDSTAR)
#elifdef ENABLE_VOIDSTAR
GTEST_SKIP() << "ENABLE_VOIDSTAR continues past a failed XRPL_ASSERT instead of aborting, so "
"the cross-thread scope-leak assertion this test exercises does not crash.";
#else
EXPECT_DEATH(
{
// Scoped guard is active on this (origin) thread; its Scope is
// bound to this thread.
auto guard = SpanGuard::span(TraceCategory::Ledger, "ledger", "build");
// Scoped guard constructed on THIS thread; its Scope binds here.
auto scoped =
std::make_unique<ScopedSpanGuard>(TraceCategory::Ledger, "ledger", "build");
// Move the still-scoped guard to a worker thread WITHOUT detaching.
// ~SpanGuard::Impl runs on the worker when the lambda returns and
// trips the thread-affinity assertion -> abort().
std::thread worker([d = std::move(guard)]() mutable {});
// Move only the owning pointer to a worker. ~ScopedSpanGuard runs on
// the worker when the lambda's captures are destroyed and trips the
// owner-thread assertion -> abort().
std::thread worker([s = std::move(scoped)]() mutable {});
worker.join();
},
// The assert message is written as two adjacent string literals in
// SpanGuard.cpp; glibc's assert() stringifies the expression source via
// the preprocessor '#' operator, keeping both quoted literals with the
// SpanGuard.cpp; assert() stringifies the expression source via the
// preprocessor '#' operator, keeping both quoted literals with the
// "\" \"" gap between "on" and "constructing". Match across that gap.
".*scoped guard destroyed on.*constructing thread.*");
".*destroyed on.*constructing thread.*");
#endif
}
// detachInPlace(optional&) must detach the live guard the same way the
// hand-rolled emplace(std::move(*opt).detached()) idiom does: after the call
// the guard can be moved to and ended on a worker thread without leaving the
// origin thread's context stack holding it.
TEST_F(SpanGuardScopeTest, detach_in_place_optional_detaches_active_guard)
{
// Scoped optional guard is active on this (origin) thread.
std::optional<SpanGuard> opt = SpanGuard::span(TraceCategory::Ledger, "ledger", "build");
ASSERT_TRUE(opt.has_value());
ASSERT_TRUE(static_cast<bool>(*opt));
// Strip the thread-local Scope here on the origin thread via the helper.
detachInPlace(opt);
ASSERT_TRUE(opt.has_value());
ASSERT_TRUE(static_cast<bool>(*opt));
// End the detached span on a worker thread.
std::thread worker([d = std::move(*opt)]() mutable {});
worker.join();
// Back on the origin thread: a new span must be a fresh root, proving the
// origin stack top was restored by detachInPlace() (not left holding
// ledger.build).
{
auto after = SpanGuard::span(TraceCategory::Rpc, "rpc", "command");
ASSERT_TRUE(static_cast<bool>(after));
}
auto spans = spanData()->GetSpans();
auto* build = findSpan(spans, "ledger.build");
auto* after = findSpan(spans, "rpc.command");
ASSERT_NE(build, nullptr);
ASSERT_NE(after, nullptr);
// 'after' is a new root: zero parent and a different trace than
// ledger.build.
EXPECT_FALSE(after->GetParentSpanId().IsValid());
EXPECT_NE(after->GetTraceId(), build->GetTraceId());
}
// detachInPlace(optional&) on an empty optional is a no-op: it must not crash,
// must leave the optional empty, and must export nothing.
TEST_F(SpanGuardScopeTest, detach_in_place_optional_noop_on_empty)
{
std::optional<SpanGuard> opt;
ASSERT_FALSE(opt.has_value());
detachInPlace(opt);
// Still empty, no span was created or exported.
EXPECT_FALSE(opt.has_value());
EXPECT_TRUE(spanData()->GetSpans().empty());
}
// detachInPlace(shared_ptr) must detach the live guard and return it as a new
// shared_ptr, so the returned guard can be moved to and ended on a worker
// thread without corrupting the origin thread's context stack.
TEST_F(SpanGuardScopeTest, detach_in_place_shared_detaches_active_guard)
{
// Scoped shared guard is active on this (origin) thread.
auto span =
std::make_shared<SpanGuard>(SpanGuard::span(TraceCategory::Ledger, "ledger", "build"));
ASSERT_NE(span, nullptr);
ASSERT_TRUE(static_cast<bool>(*span));
// Strip the thread-local Scope here on the origin thread via the helper.
span = detachInPlace(std::move(span));
ASSERT_NE(span, nullptr);
ASSERT_TRUE(static_cast<bool>(*span));
// End the detached span on a worker thread.
std::thread worker([d = std::move(span)]() mutable {});
worker.join();
// Back on the origin thread: a new span must be a fresh root, proving the
// origin stack top was restored by detachInPlace() (not left holding
// ledger.build).
{
auto after = SpanGuard::span(TraceCategory::Rpc, "rpc", "command");
ASSERT_TRUE(static_cast<bool>(after));
}
auto spans = spanData()->GetSpans();
auto* build = findSpan(spans, "ledger.build");
auto* after = findSpan(spans, "rpc.command");
ASSERT_NE(build, nullptr);
ASSERT_NE(after, nullptr);
// 'after' is a new root: zero parent and a different trace than
// ledger.build.
EXPECT_FALSE(after->GetParentSpanId().IsValid());
EXPECT_NE(after->GetTraceId(), build->GetTraceId());
}
// detachInPlace(shared_ptr) on a null pointer is a no-op: it must not crash and
// must return null unchanged.
TEST_F(SpanGuardScopeTest, detach_in_place_shared_noop_on_null)
{
auto result = detachInPlace(std::shared_ptr<SpanGuard>{});
EXPECT_EQ(result, nullptr);
}
} // namespace
} // namespace xrpl::telemetry

9
src/xrpld/app/misc/NetworkOPs.cpp
View File

@@ -1384,11 +1384,10 @@ NetworkOPsImp::processTransaction(
FailHard failType)
{
using namespace telemetry;
// Detached: this span is stored in TransactionStatus and applied on a
// batch worker thread, so it must not leave its Scope bound to this
// thread's context stack (that leak would adopt later work into this
// transaction's trace).
auto span = std::make_shared<SpanGuard>(txProcessSpan(transaction->getID()).detached());
// SpanGuard is thread-free (holds no Scope), so it is safe to store here
// and end on the batch worker thread that later applies this transaction —
// no detach step is needed.
auto span = std::make_shared<SpanGuard>(txProcessSpan(transaction->getID()));
span->setAttribute(tx_span::attr::txHash, to_string(transaction->getID()).c_str());
span->setAttribute(tx_span::attr::local, bLocal);
if (auto const& stx = transaction->getSTransaction())

15
src/xrpld/app/misc/detail/TxQ.cpp
View File

@@ -545,7 +545,7 @@ TxQ::tryClearAccountQueueUpThruTx(
beast::Journal j)
{
using namespace telemetry;
[[maybe_unused]] auto span = SpanGuard::span(
[[maybe_unused]] ScopedSpanGuard span(
TraceCategory::Transactions, txq_span::prefix::txq, txq_span::op::batchClear);
SeqProxy const tSeqProx{tx.getSeqProxy()};
@@ -752,8 +752,7 @@ TxQ::apply(
beast::Journal j)
{
using namespace telemetry;
auto span =
SpanGuard::span(TraceCategory::Transactions, txq_span::prefix::txq, txq_span::op::enqueue);
ScopedSpanGuard span(TraceCategory::Transactions, txq_span::prefix::txq, txq_span::op::enqueue);
span.setAttribute(txq_span::attr::txHash, to_string(tx->getTransactionID()).c_str());
if (auto const* fmt = TxFormats::getInstance().findByType(tx->getTxnType()))
span.setAttribute(txq_span::attr::txType, fmt->getName().c_str());
@@ -1374,8 +1373,7 @@ void
TxQ::processClosedLedger(Application& app, ReadView const& view, bool timeLeap)
{
using namespace telemetry;
auto span =
SpanGuard::span(TraceCategory::Transactions, txq_span::prefix::txq, txq_span::op::cleanup);
ScopedSpanGuard span(TraceCategory::Transactions, txq_span::prefix::txq, txq_span::op::cleanup);
span.setAttribute(txq_span::attr::ledgerSeq, static_cast<int64_t>(view.header().seq));
std::scoped_lock const lock(mutex_);
@@ -1466,8 +1464,7 @@ TxQ::accept(Application& app, OpenView& view)
// Create the span and read byFee_.size() only after taking the lock, since
// byFee_ is guarded by mutex_.
auto span =
SpanGuard::span(TraceCategory::Transactions, txq_span::prefix::txq, txq_span::op::accept);
ScopedSpanGuard span(TraceCategory::Transactions, txq_span::prefix::txq, txq_span::op::accept);
span.setAttribute(txq_span::attr::queueSize, static_cast<int64_t>(byFee_.size()));
auto const metricsSnapshot = feeMetrics_.getSnapshot();
@@ -1497,7 +1494,7 @@ TxQ::accept(Application& app, OpenView& view)
JLOG(j_.trace()) << "Applying queued transaction " << candidateIter->txID
<< " to open ledger.";
auto txSpan = SpanGuard::span(
ScopedSpanGuard txSpan(
TraceCategory::Transactions, txq_span::prefix::txq, txq_span::op::acceptTx);
txSpan.setAttribute(txq_span::attr::txHash, to_string(candidateIter->txID).c_str());
txSpan.setAttribute(
@@ -1718,7 +1715,7 @@ TxQ::tryDirectApply(
beast::Journal j)
{
using namespace telemetry;
[[maybe_unused]] auto span = SpanGuard::span(
[[maybe_unused]] ScopedSpanGuard const span(
TraceCategory::Transactions, txq_span::prefix::txq, txq_span::op::applyDirect);
auto const account = (*tx)[sfAccount];

7
src/xrpld/overlay/detail/PeerImp.cpp
View File

@@ -1313,10 +1313,9 @@ PeerImp::handleTransaction(
uint256 const txID = stx->getTransactionID();
using namespace telemetry;
// Detached: this span is handed to a job-queue worker and must not
// leave its Scope bound to this peer thread's context stack (that
// leak would adopt later peer messages into this transaction's trace).
auto span = std::make_shared<SpanGuard>(txReceiveSpan(txID, *m).detached());
// SpanGuard is thread-free (holds no Scope), so it is safe to hand to
// a job-queue worker and end on that thread — no detach step is needed.
auto span = std::make_shared<SpanGuard>(txReceiveSpan(txID, *m));
span->setAttribute(tx_span::attr::txHash, to_string(txID).c_str());
span->setAttribute(tx_span::attr::peerId, static_cast<int64_t>(id_));
if (auto const* fmt = TxFormats::getInstance().findByType(stx->getTxnType()))

24
src/xrpld/rpc/detail/ServerHandler.cpp
View File

@@ -229,8 +229,10 @@ ServerHandler::onHandoff(
if (!isWs)
return statusRequestResponse(request, http::status::unauthorized);
auto span =
SpanGuard::span(TraceCategory::Rpc, rpc_span::prefix::rpc, rpc_span::op::wsUpgrade);
// Fresh root so each WS upgrade is its own trace, not nested under a
// leaked ambient span on a reused coro worker.
auto span = ScopedSpanGuard::freshRoot(
TraceCategory::Rpc, rpc_span::prefix::rpc, rpc_span::op::wsUpgrade);
std::shared_ptr<WSSession> ws;
try
{
@@ -348,8 +350,9 @@ ServerHandler::onWSMessage(
auto const size = boost::asio::buffer_size(buffers);
if (size > RPC::Tuning::kMaxRequestSize || !json::Reader{}.parse(jv, buffers) || !jv.isObject())
{
auto span =
SpanGuard::span(TraceCategory::Rpc, rpc_span::prefix::rpc, rpc_span::op::wsMessage);
// Fresh root so each WS message is its own trace.
auto span = ScopedSpanGuard::freshRoot(
TraceCategory::Rpc, rpc_span::prefix::rpc, rpc_span::op::wsMessage);
span.setError(rpc_span::val::invalidJson);
json::Value jvResult(json::ValueType::Object);
@@ -428,7 +431,9 @@ ServerHandler::processSession(
std::shared_ptr<JobQueue::Coro> const& coro,
json::Value const& jv)
{
auto span = SpanGuard::span(TraceCategory::Rpc, rpc_span::prefix::rpc, rpc_span::op::wsMessage);
// Fresh root so each WS message is its own trace.
auto span = ScopedSpanGuard::freshRoot(
TraceCategory::Rpc, rpc_span::prefix::rpc, rpc_span::op::wsMessage);
if (jv.isMember(jss::command) && jv[jss::command].isString())
{
span.setAttribute(rpc_span::attr::command, jv[jss::command].asString().c_str());
@@ -593,8 +598,10 @@ ServerHandler::processSession(
std::shared_ptr<Session> const& session,
std::shared_ptr<JobQueue::Coro> coro)
{
auto span =
SpanGuard::span(TraceCategory::Rpc, rpc_span::prefix::rpc, rpc_span::op::httpRequest);
// Fresh root so each HTTP request is its own trace, not nested under a
// leaked ambient span on a reused coro worker.
auto span = ScopedSpanGuard::freshRoot(
TraceCategory::Rpc, rpc_span::prefix::rpc, rpc_span::op::httpRequest);
auto const requestBody = ::xrpl::buffersToString(session->request().body().data());
span.setAttribute(rpc_span::attr::requestPayloadSize, static_cast<int64_t>(requestBody.size()));
@@ -658,7 +665,8 @@ ServerHandler::processRequest(
std::string_view forwardedFor,
std::string_view user)
{
auto span = SpanGuard::span(TraceCategory::Rpc, rpc_span::prefix::rpc, rpc_span::op::process);
// Scoped child: nests under the httpRequest span active on this thread.
auto span = ScopedSpanGuard(TraceCategory::Rpc, rpc_span::prefix::rpc, rpc_span::op::process);
auto rpcJ = app_.getJournal("RPC");
// Tracks whether any failure occurred. Set on every error path (early

20
src/xrpld/rpc/handlers/orderbook/RipplePathFind.cpp
View File

@@ -27,19 +27,17 @@ json::Value
doRipplePathFind(RPC::JsonContext& context)
{
using namespace telemetry;
// This RPC span is held live across context.coro->yield() below, so it is
// both rooted and detached:
// - rootSpan: on resume the coroutine may run on a different JobQueue
// This RPC span is held live across context.coro->yield() below, so it must
// be both a fresh root and thread-free:
// - freshRoot: on resume the coroutine may run on a different JobQueue
// worker whose thread-local context stack holds unrelated spans; a fresh
// root avoids inheriting a stale ambient parent at creation.
// - detached(): strips the thread-local Scope so the guard does not sit on
// the worker's context stack across the yield (which would adopt other
// spans run on that thread) and is not popped on the wrong thread when
// the coroutine resumes elsewhere. The span still ends when this frame
// unwinds after resume.
auto span = SpanGuard::rootSpan(
TraceCategory::Rpc, pathfind_span::prefix::pathfind, pathfind_span::op::request)
.detached();
// - SpanGuard is thread-free: it holds no thread-local Scope, so it never
// sits on the worker's context stack across the yield and is never popped
// on the wrong thread when the coroutine resumes elsewhere. No scope to
// strip. The span still ends when this frame unwinds after resume.
auto span = SpanGuard::freshRoot(
TraceCategory::Rpc, pathfind_span::prefix::pathfind, pathfind_span::op::request);
// Addresses are hashed before emission for privacy.
if (auto const& src = context.params[jss::source_account]; src.isString())
span.setAttribute(pathfind_span::attr::sourceAccount, redactAccount(src.asString()));