Merge 5560d4f into 9e1b39c

README.md

@@ -107,6 +107,21 @@ JAEGER_SAMPLER_PARAM | The sampler parameter (double)
 JAEGER_SAMPLING_ENDPOINT | The url for the remote sampling conf when using sampler type remote. Default is http://127.0.0.1:5778/sampling
 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'.
+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
 
 [Apache 2.0 License](./LICENSE).

src/jaegertracing/Tracer.cpp

@@ -33,6 +33,9 @@ using SystemClock = Tracer::SystemClock;
 using SteadyClock = Tracer::SteadyClock;
 using TimePoints = std::tuple<SystemClock::time_point, SteadyClock::time_point>;
 
+// An extension of opentracing::SpanReferenceType enum. See jaegertracing::SelfRef().
+const static int SpanReferenceType_JaegerSpecific_SelfRef = 99;
+
 TimePoints determineStartTimes(const opentracing::StartSpanOptions& options)
 {
     if (options.start_system_timestamp == SystemClock::time_point() &&
@@ -67,19 +70,32 @@ Tracer::StartSpanWithOptions(string_view operationName,
     try {
         const auto result = analyzeReferences(options.references);
         const auto* parent = result._parent;
+        const auto* self = result._self;
         const auto& references = result._references;
+        if (self && (parent || !references.empty()))
+        {
+            throw std::exception(); // Self reference must be the only reference
+        }
 
         std::vector<Tag> samplerTags;
         auto newTrace = false;
         SpanContext ctx;
         if (!parent || !parent->isValid()) {
             newTrace = true;
             auto highID = static_cast<uint64_t>(0);
-            if (_options & kGen128BitOption) {
-                highID = randomID();
+            auto lowID = static_cast<uint64_t>(0);
+            if (self) {
+                highID = self->traceID().high();
+                lowID = self->traceID().low();
+            }
+            else {
+                if (_options & kGen128BitOption) {
+                    highID = randomID();
+                }
+                lowID = randomID();
             }
-            const TraceID traceID(highID, randomID());
-            const auto spanID = traceID.low();
+            const TraceID traceID(highID, lowID);
+            const auto spanID = self ? self->spanID() : traceID.low();
             const auto parentID = 0;
             auto flags = static_cast<unsigned char>(0);
             if (parent && parent->isDebugIDContainerOnly()) {
@@ -194,6 +210,12 @@ Tracer::analyzeReferences(const std::vector<OpenTracingRef>& references) const
             continue;
         }
 
+        if (static_cast<int>(ref.first) == SpanReferenceType_JaegerSpecific_SelfRef)
+        {
+            result._self = ctx;
+            continue; // not a reference
+        }
+
         result._references.emplace_back(Reference(*ctx, ref.first));
 
         if (!hasParent) {
@@ -245,4 +267,8 @@ Tracer::make(const std::string& serviceName,
                                               options));
 }
 
+opentracing::SpanReference SelfRef(const opentracing::SpanContext* span_context) noexcept {
+    return {static_cast<opentracing::SpanReferenceType>(SpanReferenceType_JaegerSpecific_SelfRef), span_context};
+}
+
 }  // namespace jaegertracing

src/jaegertracing/Tracer.h

@@ -273,11 +273,13 @@ class Tracer : public opentracing::Tracer,
     struct AnalyzedReferences {
         AnalyzedReferences()
             : _parent(nullptr)
+            , _self(nullptr)
             , _references()
         {
         }
 
         const SpanContext* _parent;
+        const SpanContext* _self;
         std::vector<Reference> _references;
     };
 
@@ -301,6 +303,15 @@ class Tracer : public opentracing::Tracer,
     int _options;
 };
 
+
+// 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
 
 #endif  // JAEGERTRACING_TRACER_H