Add interface for a trace recorder (open-telemetry#44)

* Start Recorder api

* Fill out Span api

* Reformat

* Fill out Tracer class

* Add cmake build

* Add commenting

* Fix formatting

* Reformat

* Fix date

* Make mutex mutable

* s/mutex_/mu_/

* Remove AddEvent with steady timestamp

* Fix typo

* Fill in IsRecordable

* Use namespace macros

* Add thread-compatible note

* Add commenting

CMakeLists.txt

@@ -20,4 +20,7 @@ endif()
 
 include_directories(api/include)
 add_subdirectory(api)
+include_directories(sdk/include)
+include_directories(sdk)
+add_subdirectory(sdk)
 add_subdirectory(examples)

api/include/opentelemetry/plugin/tracer.h

@@ -24,10 +24,6 @@ class Span final : public trace::Span
   {
     span_->AddEvent(name, timestamp);
   }
-  void AddEvent(nostd::string_view name, core::SteadyTimestamp timestamp) noexcept override
-  {
-    span_->AddEvent(name, timestamp);
-  }
 
   void SetStatus(trace::CanonicalCode code, nostd::string_view description) noexcept override
   {

api/include/opentelemetry/trace/noop.h

@@ -26,7 +26,6 @@ class NoopSpan final : public Span
   void AddEvent(nostd::string_view name) noexcept override {}
 
   void AddEvent(nostd::string_view name, core::SystemTimestamp timestamp) noexcept override {}
-  void AddEvent(nostd::string_view name, core::SteadyTimestamp timestamp) noexcept override {}
 
   void SetStatus(CanonicalCode code, nostd::string_view description) noexcept override {}
 

api/include/opentelemetry/trace/span.h

@@ -76,7 +76,6 @@ class Span
 
   // Adds an event to the Span, with a custom timestamp.
   virtual void AddEvent(nostd::string_view name, core::SystemTimestamp timestamp) noexcept = 0;
-  virtual void AddEvent(nostd::string_view name, core::SteadyTimestamp timestamp) noexcept = 0;
 
   // TODO
   // Adds an event to the Span, with a custom timestamp, and attributes.

examples/plugin/plugin/tracer.cc

@@ -26,8 +26,6 @@ class Span final : public trace::Span
 
   void AddEvent(nostd::string_view /*name*/, core::SystemTimestamp /*timestamp*/) noexcept override
   {}
-  void AddEvent(nostd::string_view /*name*/, core::SteadyTimestamp /*timestamp*/) noexcept override
-  {}
 
   void SetStatus(trace::CanonicalCode /*code*/,
                  nostd::string_view /*description*/) noexcept override

sdk/CMakeLists.txt

@@ -0,0 +1 @@
+add_subdirectory(src)

sdk/src/CMakeLists.txt

@@ -0,0 +1 @@
+add_subdirectory(trace)

sdk/src/trace/BUILD

@@ -0,0 +1,25 @@
+# Copyright 2020, OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+package(default_visibility = ["//visibility:public"])
+
+cc_library(
+    name = "trace",
+    srcs = glob(["**/*.cc"]),
+    hdrs = glob(["**/*.h"]),
+    include_prefix = "src/trace",
+    deps = [
+        "//api",
+    ],
+)

sdk/src/trace/CMakeLists.txt

@@ -0,0 +1 @@
+add_library(opentelemetry_trace tracer.cc span.cc)

sdk/src/trace/recordable.h

@@ -0,0 +1,48 @@
+#pragma once
+
+#include "opentelemetry/core/timestamp.h"
+#include "opentelemetry/nostd/string_view.h"
+#include "opentelemetry/trace/canonical_code.h"
+#include "opentelemetry/version.h"
+
+OPENTELEMETRY_BEGIN_NAMESPACE
+namespace sdk
+{
+namespace trace
+{
+namespace trace_api = opentelemetry::trace;
+
+/**
+ * Maintains a representation of a span in a format that can be processed by a recorder.
+ *
+ * This class is thread-compatible.
+ */
+class Recordable
+{
+public:
+  virtual ~Recordable() = default;
+
+  /**
+   * Add an event to a span.
+   * @param name the name of the event
+   * @param timestamp the timestamp of the event
+   */
+  virtual void AddEvent(nostd::string_view name, core::SystemTimestamp timestamp) noexcept = 0;
+
+  /**
+   * Set the status of the span.
+   * @param code the status code
+   * @param description a description of the status
+   */
+  virtual void SetStatus(trace_api::CanonicalCode code,
+                         nostd::string_view description) noexcept = 0;
+
+  /**
+   * Set the name of the span.
+   * @param name the name to set
+   */
+  virtual void SetName(nostd::string_view name) noexcept = 0;
+};
+}  // namespace trace
+}  // namespace sdk
+OPENTELEMETRY_END_NAMESPACE

sdk/src/trace/recorder.h

@@ -0,0 +1,31 @@
+#pragma once
+
+#include "opentelemetry/trace/span_id.h"
+#include "opentelemetry/trace/trace_id.h"
+#include "opentelemetry/version.h"
+#include "src/trace/recordable.h"
+
+OPENTELEMETRY_BEGIN_NAMESPACE
+namespace sdk
+{
+namespace trace
+{
+class Recorder
+{
+public:
+  virtual ~Recorder() = default;
+
+  /**
+   * @return a Recordable object to maintain a data representation of a span.
+   */
+  virtual std::unique_ptr<Recordable> MakeRecordable() noexcept = 0;
+
+  /**
+   * Record a span.
+   * @param recordable the data representation of the span.
+   */
+  virtual void Record(std::unique_ptr<Recordable> &&recordable) noexcept = 0;
+};
+}  // namespace trace
+}  // namespace sdk
+OPENTELEMETRY_END_NAMESPACE

sdk/src/trace/span.cc

@@ -0,0 +1,77 @@
+#include "src/trace/span.h"
+
+#include "opentelemetry/version.h"
+
+OPENTELEMETRY_BEGIN_NAMESPACE
+namespace sdk
+{
+namespace trace
+{
+Span::Span(std::shared_ptr<Tracer> &&tracer,
+           nostd::string_view name,
+           const trace_api::StartSpanOptions &options) noexcept
+    : tracer_{std::move(tracer)}, recordable_{tracer_->recorder().MakeRecordable()}
+{
+  (void)options;
+  if (recordable_ == nullptr)
+  {
+    return;
+  }
+  recordable_->SetName(name);
+}
+
+Span::~Span()
+{
+  End();
+}
+
+void Span::AddEvent(nostd::string_view name) noexcept
+{
+  (void)name;
+}
+
+void Span::AddEvent(nostd::string_view name, core::SystemTimestamp timestamp) noexcept
+{
+  (void)name;
+  (void)timestamp;
+}
+
+void Span::SetStatus(trace_api::CanonicalCode code, nostd::string_view description) noexcept
+{
+  std::lock_guard<std::mutex> lock_guard{mu_};
+  if (recordable_ == nullptr)
+  {
+    return;
+  }
+  recordable_->SetStatus(code, description);
+}
+
+void Span::UpdateName(nostd::string_view name) noexcept
+{
+  std::lock_guard<std::mutex> lock_guard{mu_};
+  if (recordable_ == nullptr)
+  {
+    return;
+  }
+  recordable_->SetName(name);
+}
+
+void Span::End() noexcept
+{
+  std::lock_guard<std::mutex> lock_guard{mu_};
+  if (recordable_ == nullptr)
+  {
+    return;
+  }
+  tracer_->recorder().Record(std::move(recordable_));
+  recordable_.reset();
+}
+
+bool Span::IsRecording() const noexcept
+{
+  std::lock_guard<std::mutex> lock_guard{mu_};
+  return recordable_ != nullptr;
+}
+}  // namespace trace
+}  // namespace sdk
+OPENTELEMETRY_END_NAMESPACE

sdk/src/trace/span.h

@@ -0,0 +1,46 @@
+#pragma once
+
+#include "opentelemetry/version.h"
+#include "src/trace/tracer.h"
+
+#include <mutex>
+
+OPENTELEMETRY_BEGIN_NAMESPACE
+namespace sdk
+{
+namespace trace
+{
+namespace trace_api = opentelemetry::trace;
+
+class Span final : public trace_api::Span
+{
+public:
+  explicit Span(std::shared_ptr<Tracer> &&tracer,
+                nostd::string_view name,
+                const trace_api::StartSpanOptions &options) noexcept;
+
+  ~Span() override;
+
+  // trace_api::Span
+  void AddEvent(nostd::string_view name) noexcept override;
+
+  void AddEvent(nostd::string_view name, core::SystemTimestamp timestamp) noexcept override;
+
+  void SetStatus(trace_api::CanonicalCode code, nostd::string_view description) noexcept override;
+
+  void UpdateName(nostd::string_view name) noexcept override;
+
+  void End() noexcept override;
+
+  bool IsRecording() const noexcept override;
+
+  trace_api::Tracer &tracer() const noexcept override { return *tracer_; }
+
+private:
+  std::shared_ptr<Tracer> tracer_;
+  mutable std::mutex mu_;
+  std::unique_ptr<Recordable> recordable_;
+};
+}  // namespace trace
+}  // namespace sdk
+OPENTELEMETRY_END_NAMESPACE

sdk/src/trace/tracer.cc

@@ -0,0 +1,20 @@
+#include "src/trace/tracer.h"
+
+#include "opentelemetry/version.h"
+#include "src/trace/span.h"
+
+OPENTELEMETRY_BEGIN_NAMESPACE
+namespace sdk
+{
+namespace trace
+{
+nostd::unique_ptr<trace_api::Span> Tracer::StartSpan(
+    nostd::string_view name,
+    const trace_api::StartSpanOptions &options) noexcept
+{
+  return nostd::unique_ptr<trace_api::Span>{new (std::nothrow)
+                                                Span{this->shared_from_this(), name, options}};
+}
+}  // namespace trace
+}  // namespace sdk
+OPENTELEMETRY_END_NAMESPACE

sdk/src/trace/tracer.h

@@ -0,0 +1,32 @@
+#pragma once
+
+#include "opentelemetry/trace/tracer.h"
+#include "opentelemetry/version.h"
+#include "src/trace/recorder.h"
+
+#include <memory>
+
+OPENTELEMETRY_BEGIN_NAMESPACE
+namespace sdk
+{
+namespace trace
+{
+class Tracer final : public trace_api::Tracer, public std::enable_shared_from_this<Tracer>
+{
+public:
+  // Note: recorder must be non-null
+  explicit Tracer(std::unique_ptr<Recorder> &&recorder) noexcept : recorder_{std::move(recorder)} {}
+
+  Recorder &recorder() const noexcept { return *recorder_; }
+
+  // trace_api::Tracer
+  nostd::unique_ptr<trace_api::Span> StartSpan(
+      nostd::string_view name,
+      const trace_api::StartSpanOptions &options = {}) noexcept override;
+
+private:
+  std::unique_ptr<Recorder> recorder_;
+};
+}  // namespace trace
+}  // namespace sdk
+OPENTELEMETRY_END_NAMESPACE