Add a minimal tracer example (open-telemetry#86)

api/include/opentelemetry/core/timestamp.h

@@ -42,6 +42,11 @@ class SystemTimestamp
     return std::chrono::nanoseconds{nanos_since_epoch_};
   }
 
+  bool operator==(const SystemTimestamp &other) const noexcept
+  {
+    return nanos_since_epoch_ == other.nanos_since_epoch_;
+  }
+
 private:
   int64_t nanos_since_epoch_;
 };
@@ -79,6 +84,11 @@ class SteadyTimestamp
     return std::chrono::nanoseconds{nanos_since_epoch_};
   }
 
+  bool operator==(const SteadyTimestamp &other) const noexcept
+  {
+    return nanos_since_epoch_ == other.nanos_since_epoch_;
+  }
+
 private:
   int64_t nanos_since_epoch_;
 };

api/include/opentelemetry/plugin/tracer.h

@@ -39,7 +39,7 @@ class Span final : public trace::Span
 
   void UpdateName(nostd::string_view name) noexcept override { span_->UpdateName(name); }
 
-  void End() noexcept override { span_->End(); }
+  void End(const trace::EndSpanOptions &options = {}) noexcept override { span_->End(); }
 
   bool IsRecording() const noexcept override { return span_->IsRecording(); }
 

api/include/opentelemetry/trace/noop.h

@@ -38,7 +38,7 @@ class NoopSpan final : public Span
 
   void UpdateName(nostd::string_view /*name*/) noexcept override {}
 
-  void End() noexcept override {}
+  void End(const EndSpanOptions &options = {}) noexcept override {}
 
   bool IsRecording() const noexcept override { return false; }
 

api/include/opentelemetry/trace/span.h

@@ -44,6 +44,11 @@ struct StartSpanOptions
   SpanKind kind = SpanKind::kInternal;
 };
 
+struct EndSpanOptions
+{
+  core::SteadyTimestamp end_steady_time;
+};
+
 class Tracer;
 
 /**
@@ -132,10 +137,7 @@ class Span
 
   // Mark the end of the Span. Only the timing of the first End call for a given Span will
   // be recorded, and implementations are free to ignore all further calls.
-  virtual void End() noexcept = 0;
-
-  // TODO
-  // virtual void End(EndSpanOptions&& opts) noexcept = 0;
+  virtual void End(const EndSpanOptions &options = {}) noexcept = 0;
 
   // TODO
   // SpanContext context() const noexcept = 0;

examples/CMakeLists.txt

@@ -1 +1,2 @@
 add_subdirectory(plugin)
+add_subdirectory(simple)

examples/plugin/plugin/tracer.cc

@@ -38,7 +38,7 @@ class Span final : public trace::Span
 
   void UpdateName(nostd::string_view /*name*/) noexcept override {}
 
-  void End() noexcept override {}
+  void End(const trace::EndSpanOptions &options) noexcept override {}
 
   bool IsRecording() const noexcept override { return true; }
 

examples/simple/BUILD

@@ -0,0 +1,25 @@
+cc_library(
+    name = "foo_library",
+    srcs = [
+        "foo_library/foo_library.cc",
+    ],
+    hdrs = [
+        "foo_library/foo_library.h",
+    ],
+    deps = [
+        "//api",
+    ],
+)
+
+cc_binary(
+    name = "example_simple",
+    srcs = [
+        "main.cc",
+        "stdout_exporter.h",
+    ],
+    deps = [
+        ":foo_library",
+        "//api",
+        "//sdk/src/trace",
+    ],
+)

examples/simple/CMakeLists.txt

@@ -0,0 +1,6 @@
+add_library(foo_library foo_library/foo_library.cc)
+target_link_libraries(foo_library ${CMAKE_THREAD_LIBS_INIT} opentelemetry_api)
+
+add_executable(example_simple main.cc)
+target_link_libraries(example_simple ${CMAKE_THREAD_LIBS_INIT} foo_library
+                      opentelemetry_trace)

examples/simple/foo_library/foo_library.cc

@@ -0,0 +1,33 @@
+#include "opentelemetry/trace/provider.h"
+
+namespace trace = opentelemetry::trace;
+namespace nostd = opentelemetry::nostd;
+
+namespace
+{
+nostd::shared_ptr<trace::Tracer> get_tracer()
+{
+  auto provider = trace::Provider::GetTracerProvider();
+  return provider->GetTracer("foo_library");
+}
+
+void f1()
+{
+  auto span = get_tracer()->StartSpan("f1");
+}
+
+void f2()
+{
+  auto span = get_tracer()->StartSpan("f2");
+
+  f1();
+  f1();
+}
+}  // namespace
+
+void foo_library()
+{
+  auto span = get_tracer()->StartSpan("library");
+
+  f2();
+}

examples/simple/foo_library/foo_library.h

@@ -0,0 +1,3 @@
+#pragma once
+
+void foo_library();

examples/simple/main.cc

@@ -0,0 +1,29 @@
+#include "opentelemetry/sdk/trace/simple_processor.h"
+#include "opentelemetry/sdk/trace/tracer_provider.h"
+#include "opentelemetry/trace/provider.h"
+
+// Using an exporter that simply dumps span data to stdout.
+#include "stdout_exporter.h"
+
+#include "foo_library/foo_library.h"
+
+namespace
+{
+void initTracer()
+{
+  auto exporter  = std::unique_ptr<sdktrace::SpanExporter>(new StdoutExporter);
+  auto processor = std::shared_ptr<sdktrace::SpanProcessor>(
+      new sdktrace::SimpleSpanProcessor(std::move(exporter)));
+  auto provider = nostd::shared_ptr<trace::TracerProvider>(new sdktrace::TracerProvider(processor));
+  trace::Provider::SetTracerProvider(provider);
+}
+}  // namespace
+
+int main()
+{
+  // Removing this line will leave OT initialized with the default noop
+  // tracer, thus being effectively deactivated.
+  initTracer();
+
+  foo_library();
+}

examples/simple/stdout_exporter.h

@@ -0,0 +1,52 @@
+#pragma once
+
+#include "opentelemetry/sdk/trace/exporter.h"
+#include "opentelemetry/sdk/trace/span_data.h"
+
+#include <iostream>
+
+namespace trace    = opentelemetry::trace;
+namespace nostd    = opentelemetry::nostd;
+namespace sdktrace = opentelemetry::sdk::trace;
+
+class StdoutExporter final : public sdktrace::SpanExporter
+{
+  std::unique_ptr<sdktrace::Recordable> MakeRecordable() noexcept
+  {
+    return std::unique_ptr<sdktrace::Recordable>(new sdktrace::SpanData);
+  }
+
+  sdktrace::ExportResult Export(
+      const nostd::span<std::unique_ptr<sdktrace::Recordable>> &spans) noexcept
+  {
+    for (auto &recordable : spans)
+    {
+      auto span = std::unique_ptr<sdktrace::SpanData>(
+          static_cast<sdktrace::SpanData *>(recordable.release()));
+
+      if (span != nullptr)
+      {
+        char trace_id[32]       = {0};
+        char span_id[16]        = {0};
+        char parent_span_id[16] = {0};
+
+        span->GetTraceId().ToLowerBase16(trace_id);
+        span->GetSpanId().ToLowerBase16(span_id);
+        span->GetParentSpanId().ToLowerBase16(parent_span_id);
+
+        std::cout << "{"
+                  << "\n  name          : " << span->GetName()
+                  << "\n  trace_id      : " << std::string(trace_id, 32)
+                  << "\n  span_id       : " << std::string(span_id, 16)
+                  << "\n  parent_span_id: " << std::string(parent_span_id, 16)
+                  << "\n  start         : " << span->GetStartTime().time_since_epoch().count()
+                  << "\n  duration      : " << span->GetDuration().count() << "\n}"
+                  << "\n";
+      }
+    }
+
+    return sdktrace::ExportResult::kSuccess;
+  }
+
+  void Shutdown(std::chrono::microseconds timeout = std::chrono::microseconds(0)) noexcept {}
+};

sdk/include/opentelemetry/sdk/trace/exporter.h

@@ -48,7 +48,8 @@ class SpanExporter
    * @param spans a span of unique pointers to span recordables
    */
   virtual ExportResult Export(
-      nostd::span<std::unique_ptr<opentelemetry::sdk::trace::Recordable>> &spans) noexcept = 0;
+      const nostd::span<std::unique_ptr<opentelemetry::sdk::trace::Recordable>>
+          &spans) noexcept = 0;
 
   /**
    * Shut down the exporter.

sdk/include/opentelemetry/sdk/trace/tracer_provider.h

@@ -43,7 +43,7 @@ class TracerProvider final : public opentelemetry::trace::TracerProvider
 
 private:
   opentelemetry::sdk::AtomicSharedPtr<SpanProcessor> processor_;
-  opentelemetry::nostd::shared_ptr<opentelemetry::trace::Tracer> tracer_;
+  std::shared_ptr<opentelemetry::trace::Tracer> tracer_;
 };
 }  // namespace trace
 }  // namespace sdk

sdk/src/trace/span.cc

@@ -7,11 +7,45 @@ namespace sdk
 {
 namespace trace
 {
+
+using opentelemetry::core::SteadyTimestamp;
+using opentelemetry::core::SystemTimestamp;
+
+namespace
+{
+SystemTimestamp NowOrGiven(const SystemTimestamp &system)
+{
+  if (system == SystemTimestamp())
+  {
+    return SystemTimestamp(std::chrono::system_clock::now());
+  }
+  else
+  {
+    return system;
+  }
+}
+
+SteadyTimestamp NowOrGiven(const SteadyTimestamp &steady)
+{
+  if (steady == SteadyTimestamp())
+  {
+    return SteadyTimestamp(std::chrono::steady_clock::now());
+  }
+  else
+  {
+    return steady;
+  }
+}
+}  // namespace
+
 Span::Span(std::shared_ptr<Tracer> &&tracer,
            std::shared_ptr<SpanProcessor> processor,
            nostd::string_view name,
            const trace_api::StartSpanOptions &options) noexcept
-    : tracer_{std::move(tracer)}, processor_{processor}, recordable_{processor_->MakeRecordable()}
+    : tracer_{std::move(tracer)},
+      processor_{processor},
+      recordable_{processor_->MakeRecordable()},
+      start_steady_time{options.start_steady_time}
 {
   (void)options;
   if (recordable_ == nullptr)
@@ -20,6 +54,9 @@ Span::Span(std::shared_ptr<Tracer> &&tracer,
   }
   processor_->OnStart(*recordable_);
   recordable_->SetName(name);
+
+  recordable_->SetStartTime(NowOrGiven(options.start_system_time));
+  start_steady_time = NowOrGiven(options.start_steady_time);
 }
 
 Span::~Span()
@@ -67,13 +104,17 @@ void Span::UpdateName(nostd::string_view name) noexcept
   recordable_->SetName(name);
 }
 
-void Span::End() noexcept
+void Span::End(const trace_api::EndSpanOptions &options) noexcept
 {
   std::lock_guard<std::mutex> lock_guard{mu_};
   if (recordable_ == nullptr)
   {
     return;
   }
+
+  recordable_->SetDuration(
+      std::chrono::steady_clock::time_point(NowOrGiven(options.end_steady_time)) -
+      std::chrono::steady_clock::time_point(start_steady_time));
   processor_->OnEnd(std::move(recordable_));
   recordable_.reset();
 }

sdk/src/trace/span.h

@@ -35,7 +35,7 @@ class Span final : public trace_api::Span
 
   void UpdateName(nostd::string_view name) noexcept override;
 
-  void End() noexcept override;
+  void End(const trace_api::EndSpanOptions &options = {}) noexcept override;
 
   bool IsRecording() const noexcept override;
 
@@ -46,6 +46,7 @@ class Span final : public trace_api::Span
   std::shared_ptr<SpanProcessor> processor_;
   mutable std::mutex mu_;
   std::unique_ptr<Recordable> recordable_;
+  opentelemetry::core::SteadyTimestamp start_steady_time;
 };
 }  // namespace trace
 }  // namespace sdk

sdk/src/trace/tracer_provider.cc

@@ -13,7 +13,7 @@ opentelemetry::nostd::shared_ptr<opentelemetry::trace::Tracer> TracerProvider::G
     nostd::string_view library_name,
     nostd::string_view library_version) noexcept
 {
-  return tracer_;
+  return opentelemetry::nostd::shared_ptr<opentelemetry::trace::Tracer>(tracer_);
 }
 
 void TracerProvider::SetProcessor(std::shared_ptr<SpanProcessor> processor) noexcept

sdk/test/trace/simple_processor_test.cc

@@ -1,4 +1,4 @@
-#include "src/trace/simple_processor.h"
+#include "opentelemetry/sdk/trace/simple_processor.h"
 #include "opentelemetry/nostd/span.h"
 #include "opentelemetry/sdk/trace/span_data.h"
 
@@ -23,7 +23,7 @@ class MockSpanExporter final : public SpanExporter
   }
 
   ExportResult Export(
-      opentelemetry::nostd::span<std::unique_ptr<Recordable>> &spans) noexcept override
+      const opentelemetry::nostd::span<std::unique_ptr<Recordable>> &spans) noexcept override
   {
     for (auto &span : spans)
     {

sdk/test/trace/tracer_provider_test.cc

@@ -1,6 +1,6 @@
 #include "opentelemetry/sdk/trace/tracer_provider.h"
+#include "opentelemetry/sdk/trace/simple_processor.h"
 #include "opentelemetry/sdk/trace/tracer.h"
-#include "src/trace/simple_processor.h"
 
 #include <gtest/gtest.h>