From b2d3e125374968e3d1cee45338a8ba257c7c3320 Mon Sep 17 00:00:00 2001 From: Oleksandr Bukaiev Date: Thu, 20 Feb 2020 19:11:43 -0700 Subject: [PATCH] Updates in README and code comments as per reviewer's request Signed-off-by: Oleksandr Bukaiev --- README.md | 17 ++++++++++++----- src/jaegertracing/Tracer.cpp | 3 +-- src/jaegertracing/Tracer.h | 9 ++++++--- 3 files changed, 19 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 0ff2d79b..d1d6146c 100644 --- a/README.md +++ b/README.md @@ -108,12 +108,19 @@ JAEGER_SAMPLING_ENDPOINT | The url for the remote sampling conf when using sampl JAEGER_TAGS | A comma separated list of `name = value` tracer level tags, which get added to all reported spans. The value can also refer to an environment variable using the format `${envVarName:default}`, where the `:default` is optional, and identifies a value to be used if the environment variable cannot be found ### SelfRef -Jaeger Tracer supports an additional reference type call 'SelfRef'. This allows a caller to provide traceId and spanId for the root span. -Must be the lone reference. -Usage example: - jaegertracing::SpanContext spanContextWithUserIDs { {1, 2}, 3, 0, 0, jaegertracing::SpanContext::StrMap() }; // TraceId and SpanID must be != 0 - auto span = opentracing::Tracer::Global()->StartSpan("tracedFunction1", {jaegertracing::SelfRef(&spanContextWithUserIDs)}); +Jaeger Tracer supports an additional reference type call 'SelfRef'. +It returns an opentracing::SpanReference which can be passed to Tracer::StartSpan +to influence the SpanContext of the newly created span. Specifically, the new span inherits the traceID +and spanID from the passed SELF reference. It can be used to pass externally generated IDs to the tracer, +with the purpose of recording spans from data generated elsewhere (e.g. from logs), or by augmenting the +data of the existing span (Jaeger backend will merge multiple instances of the spans with the same IDs). +Must be the lone reference, can be used only for root spans. +Usage example: +``` + jaegertracing::SpanContext customCtx { {1, 2}, 3, 0, 0, jaegertracing::SpanContext::StrMap() }; // TraceId and SpanID must be != 0 + auto span = tracer->StartSpan("spanName", { jaegertracing::SelfRef(&customCtx) }); +``` ## License diff --git a/src/jaegertracing/Tracer.cpp b/src/jaegertracing/Tracer.cpp index fd3a0608..d8f659fe 100644 --- a/src/jaegertracing/Tracer.cpp +++ b/src/jaegertracing/Tracer.cpp @@ -33,8 +33,7 @@ using SystemClock = Tracer::SystemClock; using SteadyClock = Tracer::SteadyClock; using TimePoints = std::tuple; -// An extension of enum opentracing::SpanReferenceType, for a new Span. Only to copy traceID and (for non-root spans) spanID -// spanID for root spans still traceID.low() +// An extension of opentracing::SpanReferenceType enum. See jaegertracing::SelfRef(). const static int SpanReferenceType_JaegerSpecific_SelfRef = 99; TimePoints determineStartTimes(const opentracing::StartSpanOptions& options) diff --git a/src/jaegertracing/Tracer.h b/src/jaegertracing/Tracer.h index 56b074c0..8d204267 100644 --- a/src/jaegertracing/Tracer.h +++ b/src/jaegertracing/Tracer.h @@ -304,9 +304,12 @@ class Tracer : public opentracing::Tracer, }; -// jaegertracing::SelfRef returns a StartSpanOption pointing to the Span which traceID and spanID should become the new Span's IDs -// -// See opentracing::SpanReference +// jaegertracing::SelfRef() returns an opentracing::SpanReference which can be passed to Tracer::StartSpan +// to influence the SpanContext of the newly created span. Specifically, the new span inherits the traceID +// and spanID from the passed SELF reference. It can be used to pass externally generated IDs to the tracer, +// with the purpose of recording spans from data generated elsewhere (e.g. from logs), or by augmenting the +// data of the existing span (Jaeger backend will merge multiple instances of the spans with the same IDs). +// Must be the lone reference, can be used only for root spans opentracing::SpanReference SelfRef(const opentracing::SpanContext* span_context) noexcept; } // namespace jaegertracing