rename SegmentContext -> TracingContext (#58)

Author: Shikugawa

README.md

@@ -35,7 +35,7 @@ cc_binary(
 
 #### Config
 
-cpp2sky provides simple configuration for tracer and segment. We can set `service name`, `instance name` to `SegmentConfig` and `token`. `address` to `TracerConfig`.
+cpp2sky provides simple configuration for tracer.
 The detail information is described in [official protobuf definition](https://github.com/apache/skywalking-data-collect-protocol/blob/master/language-agent/Tracing.proto#L57-L67).
 
 ```cpp
@@ -49,8 +49,12 @@ int main() {
   static const std::string oap_addr = "oap:12800";
   static const std::string token = "token";
 
-  SegmentConfig seg_config(service_name, instance_name);
-  TracerConfig tracer_config(oap_addr, token);
+  TracerConfig tracer_config;
+
+  config.set_instance_name(instance_name);
+  config.set_service_name(service_name);
+  config.set_address(oap_addr);
+  config.set_token(token);
 }
 ```
 
@@ -74,37 +78,29 @@ Then, you can create propagated span object by decoding these items.
 SpanContextPtr parent_span = createSpanContext(parent);
 ```
 
-#### Create workload segment
-
-Create segment for current workload.
-
-```cpp
-SegmentConfig seg_config(service_name, instance_name);
-SegmentContextPtr current_segment = createSegmentContext(seg_config);
-```
-
 #### Create span
 
-First, you must create root span to trace current workload.
+First, you must create tracing context that holds all spans, then crete initial entry span.
 
 ```cpp
-CurrentSegmentSpanPtr current_span = current_segment->createEntrySpan();
+TracingContextPtr tracing_context = tracer->newContext();
+TracingSpanPtr tracing_span = tracing_context->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->createExitSpan(current_span);
+TracingSpanPtr current_span = tracing_context->createExitSpan(current_span);
 ```
 
 Alternative approach is RAII based one. It is used like below,
 
 ```cpp
 {
-  StartEntrySpan entry_span(current_segment, "sample_op1");
+  StartEntrySpan entry_span(tracing_context, "sample_op1");
   {
-    StartExitSpan exit_span(current_segment, entry_span.get(), "sample_op2");
+    StartExitSpan exit_span(tracing_context, entry_span.get(), "sample_op2");
 
     // something...
   }
@@ -113,17 +109,17 @@ Alternative approach is RAII based one. It is used like below,
 
 #### Send segment to OAP
 
-Note that SegmentContextPtr is unique pointer. So when you'd like to send data, you must move it and don't refer after sending,
+Note that TracingContext is unique pointer. So when you'd like to send data, you must move it and don't refer after sending,
 to avoid undefined behavior.
 
 ```cpp
-SegmentContextPtr current_segment = createSegmentContext(config);
-CurrentSegmentSpanPtr current_span = current_segment->createEntrySpan();
+TracingContextPtr tracing_context = tracer->newContext();
+TracingSpanPtr tracing_span = tracing_context->createEntrySpan();
 
-current_span->startSpan("sample_workload");
-current_span->endSpan();
+tracing_span->startSpan("sample_workload");
+tracing_span->endSpan();
 
-tracer->sendSegment(std::move(current_segment));
+tracer->report(std::move(tracing_context));
 ```
 
 ## Security

cpp2sky/BUILD

@@ -18,7 +18,7 @@ cc_library(
   name = "cpp2sky_interface",
   hdrs = [
     "tracer.h",
-    "segment_context.h",
+    "tracing_context.h",
     "propagation.h",
     "well_known_names.h",
     "exception.h",

cpp2sky/tracer.h

@@ -18,7 +18,7 @@
 
 #include "cpp2sky/config.pb.h"
 #include "cpp2sky/propagation.h"
-#include "cpp2sky/segment_context.h"
+#include "cpp2sky/tracing_context.h"
 
 namespace cpp2sky {
 
@@ -29,13 +29,13 @@ class Tracer {
   /**
    * Start new segment. It will be called per request, for example.
    */
-  virtual SegmentContextPtr newSegment() = 0;
-  virtual SegmentContextPtr newSegment(SpanContextPtr span) = 0;
+  virtual TracingContextPtr newContext() = 0;
+  virtual TracingContextPtr newContext(SpanContextPtr span) = 0;
 
   /**
    * Send SegmentContext to the collector.
    */
-  virtual void sendSegment(SegmentContextPtr obj) = 0;
+  virtual void report(TracingContextPtr obj) = 0;
 };
 
 using TracerPtr = std::unique_ptr<Tracer>;

cpp2sky/segment_context.h renamed to cpp2sky/tracing_context.h

@@ -26,9 +26,9 @@
 
 namespace cpp2sky {
 
-class CurrentSegmentSpan {
+class TracingSpan {
  public:
-  virtual ~CurrentSegmentSpan() = default;
+  virtual ~TracingSpan() = default;
 
   /**
    * Generate Apache SkyWalking native span object from current segment span.
@@ -180,11 +180,11 @@ class CurrentSegmentSpan {
   virtual bool finished() const = 0;
 };
 
-using CurrentSegmentSpanPtr = std::shared_ptr<CurrentSegmentSpan>;
+using TracingSpanPtr = std::shared_ptr<TracingSpan>;
 
-class SegmentContext {
+class TracingContext {
  public:
-  virtual ~SegmentContext() = default;
+  virtual ~TracingContext() = default;
 
   /**
    * Get trace ID. This value must be unique globally.
@@ -209,7 +209,7 @@ class SegmentContext {
   /**
    * Get spans generated by this segment context.
    */
-  virtual const std::list<CurrentSegmentSpanPtr>& spans() const = 0;
+  virtual const std::list<TracingSpanPtr>& spans() const = 0;
 
   /**
    * Get span context which generated this segment context as parent.
@@ -225,13 +225,12 @@ class SegmentContext {
    * Generate a segment span related with this segment context.
    * @param parent_span Parent span which is extracted from caller.
    */
-  virtual CurrentSegmentSpanPtr createExitSpan(
-      CurrentSegmentSpanPtr parent_span) = 0;
+  virtual TracingSpanPtr createExitSpan(TracingSpanPtr parent_span) = 0;
 
   /**
    * Generate root segment span, called once per workload.
    */
-  virtual CurrentSegmentSpanPtr createEntrySpan() = 0;
+  virtual TracingSpanPtr createEntrySpan() = 0;
 
   /**
    * Generate sw8 value to send SegmentRef.
@@ -240,7 +239,7 @@ class SegmentContext {
    * https://github.com/apache/skywalking-data-collect-protocol/blob/master/language-agent/Tracing.proto#L97-L101
    */
   virtual std::optional<std::string> createSW8HeaderValue(
-      CurrentSegmentSpanPtr parent, const std::string_view target_address) = 0;
+      TracingSpanPtr parent, const std::string_view target_address) = 0;
   // If you don't specify parent span, stored to current segment, it will be
   // selected newest span as parent span.
   virtual std::optional<std::string> createSW8HeaderValue(
@@ -267,48 +266,47 @@ class SegmentContext {
   virtual bool readyToSend() = 0;
 };
 
-using SegmentContextPtr = std::shared_ptr<SegmentContext>;
+using TracingContextPtr = std::shared_ptr<TracingContext>;
 /**
  * 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,
+  StartEntrySpan(TracingContextPtr tracing_context,
                  std::string_view operation_name)
-      : span_(segment_context->createEntrySpan()) {
+      : span_(tracing_context->createEntrySpan()) {
     span_->startSpan(operation_name.data());
   }
 
   ~StartEntrySpan() {
-    // Span won't be released because the entity is holded by SegmentContext.
+    // Span won't be released because the entity is holded by TracingContext.
     span_->endSpan();
   }
 
-  CurrentSegmentSpanPtr get() { return span_; }
+  TracingSpanPtr get() { return span_; }
 
  private:
-  CurrentSegmentSpanPtr span_;
+  TracingSpanPtr span_;
 };
 
 class StartExitSpan {
  public:
-  StartExitSpan(SegmentContextPtr segment_context,
-                CurrentSegmentSpanPtr parent_span,
+  StartExitSpan(TracingContextPtr tracing_context, TracingSpanPtr parent_span,
                 std::string_view operation_name)
-      : span_(segment_context->createExitSpan(parent_span)) {
+      : span_(tracing_context->createExitSpan(parent_span)) {
     span_->startSpan(operation_name.data());
   }
 
   ~StartExitSpan() {
-    // Span won't be released because the entity is holded by SegmentContext.
+    // Span won't be released because the entity is holded by TracingContext.
     span_->endSpan();
   }
 
-  CurrentSegmentSpanPtr get() { return span_; }
+  TracingSpanPtr get() { return span_; }
 
  private:
-  CurrentSegmentSpanPtr span_;
+  TracingSpanPtr span_;
 };
 
 }  // namespace cpp2sky

example/sample.cc

@@ -16,8 +16,8 @@
 #include <string>
 
 #include "cpp2sky/propagation.h"
-#include "cpp2sky/segment_context.h"
 #include "cpp2sky/tracer.h"
+#include "cpp2sky/tracing_context.h"
 #include "cpp2sky/well_known_names.h"
 #include "httplib.h"
 
@@ -41,24 +41,24 @@ int main() {
   svr.Get("/ping", [&](const httplib::Request& req, httplib::Response& res) {
     std::string context = req.get_header_value(kPropagationHeader.data());
 
-    SegmentContextPtr segment_context;
+    TracingContextPtr tracing_context;
     if (!context.empty()) {
-      // 2. Create segment context with propagated information.
-      segment_context = tracer->newSegment(createSpanContext(context));
+      // 2. Create tracing context with propagated information.
+      tracing_context = tracer->newContext(createSpanContext(context));
     }
 
     {
       // 3. Create entry span.
-      StartEntrySpan current_span(segment_context, "sample_op3");
+      StartEntrySpan current_span(tracing_context, "sample_op3");
 
       /**
        * something....
        */
     }
 
     // 4. Send span data
-    if (segment_context != nullptr) {
-      tracer->sendSegment(std::move(segment_context));
+    if (tracing_context != nullptr) {
+      tracer->report(std::move(tracing_context));
     }
   });
 

example/sample_client.cc

@@ -16,8 +16,8 @@
 #include <string>
 
 #include "cpp2sky/propagation.h"
-#include "cpp2sky/segment_context.h"
 #include "cpp2sky/tracer.h"
+#include "cpp2sky/tracing_context.h"
 #include "cpp2sky/well_known_names.h"
 #include "httplib.h"
 
@@ -37,8 +37,8 @@ int main() {
   // 1. Create tracer object to send span data to OAP.
   auto tracer = createInsecureGrpcTracer(config);
 
-  // 2. Create segment context
-  auto current_segment = tracer->newSegment();
+  // 2. Create tracing context
+  auto tracing_context = tracer->newContext();
 
   /**
    * 3. Create entry span it traces RPC call.
@@ -47,16 +47,16 @@ int main() {
    *
    * example:
    *
-   * auto current_span = current_segment->createEntrySpan();
+   * auto current_span = tracing_context->createEntrySpan();
    * current_span->startSpan("sample_op1");
    *
-   * auto current_span2 = current_segment->createExitSpan();
+   * auto current_span2 = tracing_context->createExitSpan();
    * current_span2->startSpan("sample_op2");
    *
    * httplib::Client cli("remote", 8082);
    * httplib::Headers headers = {
    *   {kPropagationHeader.data(),
-   *   current_segment->createSW8HeaderValue(current_span, "remote:8082")}};
+   *   tracing_context->createSW8HeaderValue(current_span, "remote:8082")}};
    *
    * auto res = cli.Get("/ping", headers);
    *
@@ -65,22 +65,22 @@ int main() {
    *
    */
   {
-    StartEntrySpan entry_span(current_segment, "sample_op1");
+    StartEntrySpan entry_span(tracing_context, "sample_op1");
 
     {
       std::string target_address = "remote:8082";
-      StartExitSpan exit_span(current_segment, entry_span.get(), "sample_op2");
+      StartExitSpan exit_span(tracing_context, entry_span.get(), "sample_op2");
       exit_span.get()->setPeer(target_address);
 
       httplib::Client cli("remote", 8082);
       httplib::Headers headers = {
-          {kPropagationHeader.data(), *current_segment->createSW8HeaderValue(
+          {kPropagationHeader.data(), *tracing_context->createSW8HeaderValue(
                                           exit_span.get(), target_address)}};
 
       auto res = cli.Get("/ping", headers);
     }
   }
 
-  tracer->sendSegment(std::move(current_segment));
+  tracer->report(std::move(tracing_context));
   return 0;
 }

source/BUILD

@@ -4,13 +4,13 @@ cc_library(
   name = "cpp2sky_lib",
   hdrs = [
     "propagation_impl.h",
-    "segment_context_impl.h",
+    "tracing_context_impl.h",
     "grpc_async_client_impl.h",
     "tracer_impl.h",
   ],
   srcs = [
     "propagation_impl.cc",
-    "segment_context_impl.cc",
+    "tracing_context_impl.cc",
     "grpc_async_client_impl.cc",
     "tracer_impl.cc",
   ],
@@ -29,11 +29,11 @@ cc_library(
   name = "cpp2sky_data_lib",
   hdrs  =[
     "propagation_impl.h",
-    "segment_context_impl.h",
+    "tracing_context_impl.h",
   ],
   srcs = [
     "propagation_impl.cc",
-    "segment_context_impl.cc",
+    "tracing_context_impl.cc",
   ],
   deps = [
     "@skywalking_data_collect_protocol//language-agent:tracing_protocol_cc_proto",