Merge branch 'pre_release_1.0.0' of github.com:lalitb/opentelemetry-c…

…pp into pre_release_1.0.0

CHANGELOG.md

@@ -28,7 +28,7 @@ Increment the:
 
 ### SDK
 
-* Cleanup GetEnvironmentVariable and remove unused variable under NO_GETENV ([#976](https://github.com/open-telemetry/opentelemetry-cpp/pull/976))
+* Clean up `GetEnvironmentVariable` and remove unused variable under `NO_GETENV` ([#976](https://github.com/open-telemetry/opentelemetry-cpp/pull/976))
 * :collision: Resources: Add note on experimental semantic convention implementation, prefix semantics headers with experimental tag ([#970](https://github.com/open-telemetry/opentelemetry-cpp/pull/970))
 
 ### OTLP Exporter
@@ -43,7 +43,7 @@ Increment the:
 
 ### DOCS
 
-* :book: Add Getting started documentation for SDK: ([#942](https://github.com/open-telemetry/opentelemetry-cpp/pull/942))
+* :book: Add getting-started documentation for SDK: ([#942](https://github.com/open-telemetry/opentelemetry-cpp/pull/942))
 * :book: Remove unnecessary spaces and spelling of gRPC in README ([#965](https://github.com/open-telemetry/opentelemetry-cpp/pull/965))
 
 ### BUILD

CMakeLists.txt

@@ -4,6 +4,12 @@ cmake_minimum_required(VERSION 3.1)
 # versions of gtest
 cmake_policy(SET CMP0057 NEW)
 
+# See https://cmake.org/cmake/help/v3.12/policy/CMP0074.html required by certain
+# version of zlib which is dependeded by cURL.
+if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.12")
+  cmake_policy(SET CMP0074 NEW)
+endif()
+
 project(opentelemetry-cpp)
 
 # Mark variables as used so cmake doesn't complain about them
@@ -81,14 +87,25 @@ else()
   )
 endif()
 
-if(NOT DEFINED CMAKE_CXX_STANDARD)
-  set(CMAKE_CXX_STANDARD 11)
-endif()
-
 option(WITH_STL "Whether to use Standard Library for C++latest features" OFF)
 
 option(WITH_ABSEIL "Whether to use Abseil for C++latest features" OFF)
 
+if(NOT DEFINED CMAKE_CXX_STANDARD)
+  if(WITH_STL)
+    # Require at least C++17. C++20 is needed to avoid gsl::span
+    if(CMAKE_VERSION VERSION_GREATER 3.11.999)
+      # Ask for 20, may get anything below
+      set(CMAKE_CXX_STANDARD 20)
+    else()
+      # Ask for 17, may get anything below
+      set(CMAKE_CXX_STANDARD 17)
+    endif()
+  else()
+    set(CMAKE_CXX_STANDARD 11)
+  endif()
+endif()
+
 if(WITH_ABSEIL)
   find_package(absl CONFIG REQUIRED)
 
@@ -106,14 +123,6 @@ if(WITH_STL)
   # the global project build definitions.
   add_definitions(-DHAVE_CPP_STDLIB)
   add_definitions(-DHAVE_GSL)
-  # Require at least C++17. C++20 is needed to avoid gsl::span
-  if(CMAKE_VERSION VERSION_GREATER 3.11.999)
-    # Ask for 20, may get anything below
-    set(CMAKE_CXX_STANDARD 20)
-  else()
-    # Ask for 17, may get anything below
-    set(CMAKE_CXX_STANDARD 17)
-  endif()
 
   # Guidelines Support Library path. Used if we are not on not get C++20.
   #

Versioning.md

@@ -65,6 +65,17 @@ Refer to the [ABI Policy](./docs/abi-policy.md) for more details. To summarise:
   allowed to break existing stable interfaces. Feature flags will be removed
   once we have a stable implementation for the signal.
 
+* As an exception, small experimental features in otherwise stable signals/components
+  mayn't necessarily be released under feature flag. These would be flagged as experimental
+  by adding a `NOTE` in it's header file - either at the beginning of file, or as the comment for
+  the experimental API methods. Also, if the complete header is experimental, it would be prefixed
+  as `experimental_`. As an example, the semantic conventions for
+  trace signal is experimental at the time of the writing and is within `experimental_semantic_conventions.h`
+
+* Code under the "*::detail" namespace implements internal details,
+  and NOT part of public interface. Also, any API not documented in the [public
+  documentation](https://opentelemetry-cpp.readthedocs.io/en/latest/) is NOT part of public interface.
+
 * GitHub releases will be made for all released versions.
 
 ## Example Versioning Lifecycle

api/include/opentelemetry/common/key_value_iterable_view.h

@@ -14,6 +14,8 @@
 OPENTELEMETRY_BEGIN_NAMESPACE
 namespace common
 {
+// NOTE - code within `detail` namespace implements internal details, and not part
+// of the public interface.
 namespace detail
 {
 inline void take_key_value(nostd::string_view, common::AttributeValue) {}

api/include/opentelemetry/detail/preprocessor.h

@@ -1,6 +1,9 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
+// NOTE - code within detail namespace implements internal details, and not part
+// of the public interface.
+
 #pragma once
 
 #define OPENTELEMETRY_STRINGIFY(S) OPENTELEMETRY_STRINGIFY_(S)

api/include/opentelemetry/trace/context.h

@@ -0,0 +1,33 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+#include "opentelemetry/context/context.h"
+#include "opentelemetry/trace/default_span.h"
+#include "opentelemetry/version.h"
+
+OPENTELEMETRY_BEGIN_NAMESPACE
+namespace trace
+{
+
+// Get Span from explicit context
+inline nostd::shared_ptr<Span> GetSpan(const opentelemetry::context::Context &context)
+{
+  context::ContextValue span = context.GetValue(kSpanKey);
+  if (nostd::holds_alternative<nostd::shared_ptr<Span>>(span))
+  {
+    return nostd::get<nostd::shared_ptr<Span>>(span);
+  }
+  return nostd::shared_ptr<Span>(new DefaultSpan(SpanContext::GetInvalid()));
+}
+
+// Set Span into explicit context
+inline context::Context SetSpan(opentelemetry::context::Context &context,
+                                nostd::shared_ptr<Span> span)
+{
+  return context.SetValue(kSpanKey, span);
+}
+
+}  // namespace trace
+OPENTELEMETRY_END_NAMESPACE

api/include/opentelemetry/trace/semantic_conventions.h → api/include/opentelemetry/trace/experimental_semantic_conventions.h

@@ -1,6 +1,12 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
+// NOTE:
+// This implementation is based on the experimental specs for trace semantic convention as defined
+// here:
+// https://github.com/open-telemetry/opentelemetry-specification/tree/v1.0.0/specification/trace/semantic_conventions
+// and MAY will change in future.
+
 #pragma once
 
 #include "opentelemetry/common/string_util.h"

api/include/opentelemetry/trace/propagation/b3_propagator.h

@@ -3,10 +3,10 @@
 
 #pragma once
 
-#include "detail/context.h"
 #include "detail/hex.h"
 #include "detail/string.h"
 #include "opentelemetry/context/propagation/text_map_propagator.h"
+#include "opentelemetry/trace/context.h"
 #include "opentelemetry/trace/default_span.h"
 
 #include <array>
@@ -50,7 +50,7 @@ class B3PropagatorExtractor : public opentelemetry::context::propagation::TextMa
   {
     SpanContext span_context = ExtractImpl(carrier);
     nostd::shared_ptr<Span> sp{new DefaultSpan(span_context)};
-    return SetSpan(context, sp);
+    return trace::SetSpan(context, sp);
   }
 
   static TraceId TraceIdFromHex(nostd::string_view trace_id)
@@ -131,7 +131,7 @@ class B3Propagator : public B3PropagatorExtractor
   void Inject(opentelemetry::context::propagation::TextMapCarrier &carrier,
               const context::Context &context) noexcept override
   {
-    SpanContext span_context = GetSpan(context)->GetContext();
+    SpanContext span_context = trace::GetSpan(context)->GetContext();
     if (!span_context.IsValid())
     {
       return;

api/include/opentelemetry/trace/propagation/detail/hex.h

@@ -13,6 +13,8 @@ namespace trace
 {
 namespace propagation
 {
+// NOTE - code within `detail` namespace implements internal details, and not part
+// of the public interface.
 namespace detail
 {
 

api/include/opentelemetry/trace/propagation/detail/string.h

@@ -10,6 +10,8 @@ namespace trace
 {
 namespace propagation
 {
+// NOTE - code within `detail` namespace implements internal details, and not part
+// of the public interface.
 namespace detail
 {
 

api/include/opentelemetry/trace/propagation/http_trace_context.h

@@ -2,11 +2,11 @@
 // SPDX-License-Identifier: Apache-2.0
 
 #include <array>
-#include "detail/context.h"
 #include "detail/hex.h"
 #include "detail/string.h"
 #include "opentelemetry/context/propagation/text_map_propagator.h"
 #include "opentelemetry/nostd/string_view.h"
+#include "opentelemetry/trace/context.h"
 #include "opentelemetry/trace/default_span.h"
 
 OPENTELEMETRY_BEGIN_NAMESPACE
@@ -34,7 +34,7 @@ class HttpTraceContext : public opentelemetry::context::propagation::TextMapProp
   void Inject(opentelemetry::context::propagation::TextMapCarrier &carrier,
               const context::Context &context) noexcept override
   {
-    SpanContext span_context = GetSpan(context)->GetContext();
+    SpanContext span_context = trace::GetSpan(context)->GetContext();
     if (!span_context.IsValid())
     {
       return;
@@ -47,7 +47,7 @@ class HttpTraceContext : public opentelemetry::context::propagation::TextMapProp
   {
     SpanContext span_context = ExtractImpl(carrier);
     nostd::shared_ptr<Span> sp{new DefaultSpan(span_context)};
-    return SetSpan(context, sp);
+    return trace::SetSpan(context, sp);
   }
 
   static TraceId TraceIdFromHex(nostd::string_view trace_id)

api/include/opentelemetry/trace/propagation/jaeger.h

@@ -3,10 +3,10 @@
 
 #pragma once
 
-#include "detail/context.h"
 #include "detail/hex.h"
 #include "detail/string.h"
 #include "opentelemetry/context/propagation/text_map_propagator.h"
+#include "opentelemetry/trace/context.h"
 #include "opentelemetry/trace/default_span.h"
 
 OPENTELEMETRY_BEGIN_NAMESPACE
@@ -23,7 +23,7 @@ class JaegerPropagator : public context::propagation::TextMapPropagator
   void Inject(context::propagation::TextMapCarrier &carrier,
               const context::Context &context) noexcept override
   {
-    SpanContext span_context = GetSpan(context)->GetContext();
+    SpanContext span_context = trace::GetSpan(context)->GetContext();
     if (!span_context.IsValid())
     {
       return;
@@ -53,7 +53,7 @@ class JaegerPropagator : public context::propagation::TextMapPropagator
   {
     SpanContext span_context = ExtractImpl(carrier);
     nostd::shared_ptr<Span> sp{new DefaultSpan(span_context)};
-    return SetSpan(context, sp);
+    return trace::SetSpan(context, sp);
   }
 
   bool Fields(nostd::function_ref<bool(nostd::string_view)> callback) const noexcept override

api/include/opentelemetry/trace/span.h

@@ -7,80 +7,21 @@
 
 #include "opentelemetry/common/attribute_value.h"
 #include "opentelemetry/common/key_value_iterable_view.h"
-#include "opentelemetry/common/timestamp.h"
 #include "opentelemetry/nostd/shared_ptr.h"
 #include "opentelemetry/nostd/span.h"
 #include "opentelemetry/nostd/string_view.h"
 #include "opentelemetry/nostd/type_traits.h"
 #include "opentelemetry/nostd/unique_ptr.h"
 #include "opentelemetry/trace/canonical_code.h"
 #include "opentelemetry/trace/span_context.h"
+#include "opentelemetry/trace/span_metadata.h"
+
 #include "opentelemetry/version.h"
 
 OPENTELEMETRY_BEGIN_NAMESPACE
 namespace trace
 {
 
-// The key identifies the active span in the current context.
-constexpr char kSpanKey[] = "active_span";
-
-enum class SpanKind
-{
-  kInternal,
-  kServer,
-  kClient,
-  kProducer,
-  kConsumer,
-};
-
-// StatusCode - Represents the canonical set of status codes of a finished Span.
-
-enum class StatusCode
-{
-  kUnset,  // default status
-  kOk,     // Operation has completed successfully.
-  kError   // The operation contains an error
-};
-
-/**
- * StartSpanOptions provides options to set properties of a Span at the time of
- * its creation
- */
-struct StartSpanOptions
-{
-  // Optionally sets the start time of a Span.
-  //
-  // If the start time of a Span is set, timestamps from both the system clock
-  // and steady clock must be provided.
-  //
-  // Timestamps from the steady clock can be used to most accurately measure a
-  // Span's duration, while timestamps from the system clock can be used to most
-  // accurately place a Span's
-  // time point relative to other Spans collected across a distributed system.
-  common::SystemTimestamp start_system_time;
-  common::SteadyTimestamp start_steady_time;
-
-  // Explicitly set the parent of a Span.
-  //
-  // This defaults to an invalid span context. In this case, the Span is
-  // automatically parented to the currently active span.
-  SpanContext parent = SpanContext::GetInvalid();
-
-  // TODO:
-  // SpanContext remote_parent;
-  // Links
-  SpanKind kind = SpanKind::kInternal;
-};
-/**
- * StartEndOptions provides options to set properties of a Span when it is
- * ended.
- */
-struct EndSpanOptions
-{
-  // Optionally sets the end time of a Span.
-  common::SteadyTimestamp end_steady_time;
-};
-
 class Tracer;
 
 /**
@@ -176,7 +117,7 @@ class Span
    * @param options can be used to manually define span properties like the end
    * timestamp
    */
-  virtual void End(const EndSpanOptions &options = {}) noexcept = 0;
+  virtual void End(const trace::EndSpanOptions &options = {}) noexcept = 0;
 
   virtual trace::SpanContext GetContext() const noexcept = 0;