implement RAII based span acquisition (#57)

* implement RAII based span acquisition

* format

Author: Shikugawa

README.md

@@ -88,14 +88,27 @@ SegmentContextPtr current_segment = createSegmentContext(seg_config);
 First, you must create root span to trace current workload.
 
 ```cpp
-CurrentSegmentSpanPtr current_span = current_segment->createCurrentSegmentRootSpan();
+CurrentSegmentSpanPtr current_span = current_segment->createEntrySpan();
 ```
 
 After that, you can create another span to trace another workload, such as RPC to other services.
 Note that you must have parent span to create secondary span. It will construct parent-child relation when analysis.
 
 ```cpp
-CurrentSegmentSpanPtr current_span = current_segment->createCurrentSegmentSpan(current_span);
+CurrentSegmentSpanPtr current_span = current_segment->createExitSpan(current_span);
+```
+
+Alternative approach is RAII based one. It is used like below,
+
+```cpp
+{
+  StartEntrySpan entry_span(current_segment, "sample_op1");
+  {
+    StartExitSpan exit_span(current_segment, entry_span.get(), "sample_op2");
+
+    // something...
+  }
+}
 ```
 
 #### Send segment to OAP
@@ -105,7 +118,7 @@ to avoid undefined behavior.
 
 ```cpp
 SegmentContextPtr current_segment = createSegmentContext(config);
-CurrentSegmentSpanPtr current_span = current_segment->createCurrentSegmentRootSpan();
+CurrentSegmentSpanPtr current_span = current_segment->createEntrySpan();
 
 current_span->startSpan("sample_workload");
 current_span->endSpan();

cpp2sky/segment_context.h

@@ -225,13 +225,13 @@ class SegmentContext {
    * Generate a segment span related with this segment context.
    * @param parent_span Parent span which is extracted from caller.
    */
-  virtual CurrentSegmentSpanPtr createCurrentSegmentSpan(
+  virtual CurrentSegmentSpanPtr createExitSpan(
       CurrentSegmentSpanPtr parent_span) = 0;
 
   /**
    * Generate root segment span, called once per workload.
    */
-  virtual CurrentSegmentSpanPtr createCurrentSegmentRootSpan() = 0;
+  virtual CurrentSegmentSpanPtr createEntrySpan() = 0;
 
   /**
    * Generate sw8 value to send SegmentRef.
@@ -268,5 +268,47 @@ class SegmentContext {
 };
 
 using SegmentContextPtr = std::shared_ptr<SegmentContext>;
+/**
+ * RAII based span creation. It acquired then create new span with required
+ * properties. The span wiil be closed and set end time when called destructor.
+ */
+class StartEntrySpan {
+ public:
+  StartEntrySpan(SegmentContextPtr segment_context,
+                 std::string_view operation_name)
+      : span_(segment_context->createEntrySpan()) {
+    span_->startSpan(operation_name.data());
+  }
+
+  ~StartEntrySpan() {
+    // Span won't be released because the entity is holded by SegmentContext.
+    span_->endSpan();
+  }
+
+  CurrentSegmentSpanPtr get() { return span_; }
+
+ private:
+  CurrentSegmentSpanPtr span_;
+};
+
+class StartExitSpan {
+ public:
+  StartExitSpan(SegmentContextPtr segment_context,
+                CurrentSegmentSpanPtr parent_span,
+                std::string_view operation_name)
+      : span_(segment_context->createExitSpan(parent_span)) {
+    span_->startSpan(operation_name.data());
+  }
+
+  ~StartExitSpan() {
+    // Span won't be released because the entity is holded by SegmentContext.
+    span_->endSpan();
+  }
+
+  CurrentSegmentSpanPtr get() { return span_; }
+
+ private:
+  CurrentSegmentSpanPtr span_;
+};
 
 }  // namespace cpp2sky

example/sample.cc

@@ -18,6 +18,7 @@
 #include "cpp2sky/propagation.h"
 #include "cpp2sky/segment_context.h"
 #include "cpp2sky/tracer.h"
+#include "cpp2sky/well_known_names.h"
 #include "httplib.h"
 
 using namespace cpp2sky;
@@ -38,18 +39,27 @@ int main() {
   auto tracer = createInsecureGrpcTracer(config);
 
   svr.Get("/ping", [&](const httplib::Request& req, httplib::Response& res) {
-    // 2. Create segment context
-    auto current_segment = tracer->newSegment();
+    std::string context = req.get_header_value(kPropagationHeader.data());
 
-    // 3. Initialize span data to track root workload on current service.
-    auto current_span = current_segment->createCurrentSegmentRootSpan();
+    SegmentContextPtr segment_context;
+    if (!context.empty()) {
+      // 2. Create segment context with propagated information.
+      segment_context = tracer->newSegment(createSpanContext(context));
+    }
 
-    // 4. Set info
-    current_span->startSpan("/ping");
-    current_span->endSpan();
+    {
+      // 3. Create entry span.
+      StartEntrySpan current_span(segment_context, "sample_op3");
 
-    // 5. Send span data
-    tracer->sendSegment(std::move(current_segment));
+      /**
+       * something....
+       */
+    }
+
+    // 4. Send span data
+    if (segment_context != nullptr) {
+      tracer->sendSegment(std::move(segment_context));
+    }
   });
 
   svr.listen("0.0.0.0", 8081);

example/sample_client.cc

@@ -40,26 +40,47 @@ int main() {
   // 2. Create segment context
   auto current_segment = tracer->newSegment();
 
-  // 3. Initialize span data to track root workload on current service.
-  auto current_span = current_segment->createCurrentSegmentRootSpan();
-
-  // 4. Set info
-  current_span->startSpan("/ping");
-
-  httplib::Client cli("remote", 8082);
-
-  auto context =
-      current_segment->createSW8HeaderValue(current_span, "remote:8082");
-
-  httplib::Headers headers;
-  if (context.has_value()) {
-    headers = {{kPropagationHeader.data(), *context}};
+  /**
+   * 3. Create entry span it traces RPC call.
+   * Span lifetime is managed by RAII. So user don't have to call startSpan and
+   * endSpan explicitly. But it provides basic approach that doesn't use RAII.
+   *
+   * example:
+   *
+   * auto current_span = current_segment->createEntrySpan();
+   * current_span->startSpan("sample_op1");
+   *
+   * auto current_span2 = current_segment->createExitSpan();
+   * current_span2->startSpan("sample_op2");
+   *
+   * httplib::Client cli("remote", 8082);
+   * httplib::Headers headers = {
+   *   {kPropagationHeader.data(),
+   *   current_segment->createSW8HeaderValue(current_span, "remote:8082")}};
+   *
+   * auto res = cli.Get("/ping", headers);
+   *
+   * current_span2->endSpan();
+   * current_span->endSpan();
+   *
+   */
+  {
+    StartEntrySpan entry_span(current_segment, "sample_op1");
+
+    {
+      std::string target_address = "remote:8082";
+      StartExitSpan exit_span(current_segment, entry_span.get(), "sample_op2");
+      exit_span.get()->setPeer(target_address);
+
+      httplib::Client cli("remote", 8082);
+      httplib::Headers headers = {
+          {kPropagationHeader.data(), *current_segment->createSW8HeaderValue(
+                                          exit_span.get(), target_address)}};
+
+      auto res = cli.Get("/ping", headers);
+    }
   }
-  auto res = cli.Get("/ping", headers);
-
-  current_span->endSpan();
 
-  // 5. Send span data
   tracer->sendSegment(std::move(current_segment));
   return 0;
 }

source/segment_context_impl.cc

@@ -172,30 +172,23 @@ SegmentContextImpl::SegmentContextImpl(const std::string& service_name,
       service_(service_name),
       service_instance_(instance_name) {}
 
-CurrentSegmentSpanPtr SegmentContextImpl::createCurrentSegmentSpan(
+CurrentSegmentSpanPtr SegmentContextImpl::createExitSpan(
     CurrentSegmentSpanPtr parent_span) {
-  auto current_span =
-      std::make_shared<CurrentSegmentSpanImpl>(spans_.size(), *this);
-  if (parent_span != nullptr) {
-    current_span->setParentSpanId(parent_span->spanId());
-    current_span->setSpanType(SpanType::Exit);
-  } else {
-    current_span->setParentSpanId(-1);
-    current_span->setSpanType(SpanType::Entry);
-  }
-  // It supports only HTTP request tracing.
-  current_span->setSpanLayer(SpanLayer::Http);
-  if (should_skip_analysis_) {
-    current_span->setSkipAnalysis();
-  }
-
-  spans_.push_back(current_span);
+  auto current_span = createSpan();
+  current_span->setParentSpanId(parent_span->spanId());
+  current_span->setSpanType(SpanType::Exit);
   return current_span;
 }
 
-CurrentSegmentSpanPtr SegmentContextImpl::createCurrentSegmentRootSpan() {
-  assert(spans_.empty());
-  return createCurrentSegmentSpan(nullptr);
+CurrentSegmentSpanPtr SegmentContextImpl::createEntrySpan() {
+  if (!spans_.empty()) {
+    return nullptr;
+  }
+
+  auto current_span = createSpan();
+  current_span->setParentSpanId(-1);
+  current_span->setSpanType(SpanType::Entry);
+  return current_span;
 }
 
 std::optional<std::string> SegmentContextImpl::createSW8HeaderValue(
@@ -215,8 +208,8 @@ std::optional<std::string> SegmentContextImpl::createSW8HeaderValue(
   return encodeSpan(target_span, target_address);
 }
 
-std::string SegmentContextImpl::encodeSpan(CurrentSegmentSpanPtr parent_span,
-                                           const std::string_view target_address) {
+std::string SegmentContextImpl::encodeSpan(
+    CurrentSegmentSpanPtr parent_span, const std::string_view target_address) {
   assert(parent_span);
   std::string header_value;
 
@@ -236,6 +229,20 @@ std::string SegmentContextImpl::encodeSpan(CurrentSegmentSpanPtr parent_span,
   return header_value;
 }
 
+CurrentSegmentSpanPtr SegmentContextImpl::createSpan() {
+  auto current_span =
+      std::make_shared<CurrentSegmentSpanImpl>(spans_.size(), *this);
+
+  // It supports only HTTP request tracing.
+  current_span->setSpanLayer(SpanLayer::Http);
+  if (should_skip_analysis_) {
+    current_span->setSkipAnalysis();
+  }
+
+  spans_.push_back(current_span);
+  return current_span;
+}
+
 SegmentObject SegmentContextImpl::createSegmentObject() {
   SegmentObject obj;
   obj.set_traceid(trace_id_);

source/segment_context_impl.h

@@ -144,10 +144,10 @@ class SegmentContextImpl : public SegmentContext {
   }
 #pragma endregion
 
-  CurrentSegmentSpanPtr createCurrentSegmentSpan(
+  CurrentSegmentSpanPtr createExitSpan(
       CurrentSegmentSpanPtr parent_span) override;
 
-  CurrentSegmentSpanPtr createCurrentSegmentRootSpan() override;
+  CurrentSegmentSpanPtr createEntrySpan() override;
   std::optional<std::string> createSW8HeaderValue(
       const std::string_view target_address) override {
     return createSW8HeaderValue(nullptr, target_address);
@@ -163,6 +163,7 @@ class SegmentContextImpl : public SegmentContext {
  private:
   std::string encodeSpan(CurrentSegmentSpanPtr parent_span,
                          const std::string_view target_address);
+  CurrentSegmentSpanPtr createSpan();
 
   SpanContextPtr parent_span_context_;
   SpanContextExtensionPtr parent_ext_span_context_;

test/e2e/consumer.cc

@@ -31,28 +31,19 @@ void init() {
   config.set_address("collector:19876");
 }
 
-void handlePong(Tracer* tracer, SegmentContext* scp,
-                const httplib::Request& req, httplib::Response& response) {
-  auto span = scp->createCurrentSegmentRootSpan();
-  span->startSpan("/pong");
-  span->endSpan();
-}
-
 int main() {
   init();
 
   httplib::Server svr;
   auto tracer = createInsecureGrpcTracer(config);
 
   svr.Get("/pong", [&](const httplib::Request& req, httplib::Response& res) {
-    if (req.has_header(kPropagationHeader.data())) {
-      auto parent = req.get_header_value(kPropagationHeader.data());
-      auto parent_span = createSpanContext(parent);
-
-      auto current_segment = tracer->newSegment(parent_span);
-      handlePong(tracer.get(), current_segment.get(), req, res);
-      tracer->sendSegment(std::move(current_segment));
-    }
+    auto parent = req.get_header_value(kPropagationHeader.data());
+    auto segment_context = tracer->newSegment(createSpanContext(parent));
+
+    { StartEntrySpan entry_span(segment_context, "/pong"); }
+
+    tracer->sendSegment(std::move(segment_context));
   });
 
   svr.listen("0.0.0.0", 8080);