Add note on experimental semantic convention implementation (#970)

* add note on experimental semantic conv * nit * Document experimental feature in versioning doc * Document experimental feature in versioning doc * rename experimental headers to experimental-* * review comments * missing changes * fix bazel builg
open-telemetry · Sep 13, 2021 · 320c593 · 320c593
1 parent c8b35ff
commit 320c593
Show file tree

Hide file tree

Showing 13 changed files with 57 additions and 34 deletions.
diff --git a/Versioning.md b/Versioning.md
@@ -65,6 +65,13 @@ 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.

diff --git a/...pentelemetry/trace/semantic_conventions.h → ...trace/experimental_semantic_conventions.h b/...pentelemetry/trace/semantic_conventions.h → ...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"

diff --git a/examples/grpc/BUILD b/examples/grpc/BUILD
@@ -32,7 +32,7 @@ cc_library(
 cc_binary(
     name = "client_grpc",
     srcs = [
-        "client.cpp",
+        "client.cc",
     ],
     defines = ["BAZEL_BUILD"],
     deps = [
@@ -47,7 +47,7 @@ cc_binary(
 cc_binary(
     name = "server_grpc",
     srcs = [
-        "server.cpp",
+        "server.cc",
     ],
     defines = ["BAZEL_BUILD"],
     deps = [

diff --git a/examples/grpc/CMakeLists.txt b/examples/grpc/CMakeLists.txt
@@ -37,7 +37,7 @@ else()
 endif()
 
 foreach(_target client server)
-  add_executable(${_target} "${_target}.cpp")
+  add_executable(${_target} "${_target}.cc")
   target_link_libraries(
     ${_target} example_grpc_proto protobuf::libprotobuf gRPC::grpc++
     opentelemetry_trace opentelemetry_exporter_ostream_span)

diff --git a/examples/grpc/client.cpp → examples/grpc/client.cc b/examples/grpc/client.cpp → examples/grpc/client.cc
@@ -3,16 +3,16 @@
 // modern compilers are unaffected.
 #include <grpcpp/grpcpp.h>
 #ifdef BAZEL_BUILD
-#include "examples/grpc/protos/messages.grpc.pb.h"
+#  include "examples/grpc/protos/messages.grpc.pb.h"
 #else
-#include "messages.grpc.pb.h"
+#  include "messages.grpc.pb.h"
 #endif
 
-#include "opentelemetry/trace/semantic_conventions.h"
-#include "tracer_common.h"
 #include <iostream>
 #include <memory>
 #include <string>
+#include "opentelemetry/trace/experimental_semantic_conventions.h"
+#include "tracer_common.h"
 
 using grpc::Channel;
 using grpc::ClientContext;
@@ -23,7 +23,6 @@ using grpc_example::Greeter;
 using grpc_example::GreetRequest;
 using grpc_example::GreetResponse;
 
-
 namespace
 {
 
@@ -45,13 +44,14 @@ class GreeterClient
     options.kind = opentelemetry::trace::SpanKind::kClient;
 
     std::string span_name = "GreeterClient/Greet";
-    auto span             = get_tracer("grpc")->StartSpan(span_name,
-                                              {{OTEL_CPP_GET_ATTR(AttrRpcSystem), "grpc"},
-                                               {OTEL_CPP_GET_ATTR(AttrRpcService), "grpc-example.GreetService"},
-                                               {OTEL_CPP_GET_ATTR(AttrRpcMethod), "Greet"},
-                                               {OTEL_CPP_GET_ATTR(AttrNetPeerIp), ip},
-                                               {OTEL_CPP_GET_ATTR(AttrNetPeerPort), port}},
-                                              options);
+    auto span             = get_tracer("grpc")->StartSpan(
+        span_name,
+        {{OTEL_CPP_GET_ATTR(AttrRpcSystem), "grpc"},
+         {OTEL_CPP_GET_ATTR(AttrRpcService), "grpc-example.GreetService"},
+         {OTEL_CPP_GET_ATTR(AttrRpcMethod), "Greet"},
+         {OTEL_CPP_GET_ATTR(AttrNetPeerIp), ip},
+         {OTEL_CPP_GET_ATTR(AttrNetPeerPort), port}},
+        options);
 
     auto scope = get_tracer("grpc-client")->WithActiveSpan(span);
 

diff --git a/examples/grpc/server.cpp → examples/grpc/server.cc b/examples/grpc/server.cpp → examples/grpc/server.cc
@@ -1,11 +1,11 @@
 #ifdef BAZEL_BUILD
-#include "examples/grpc/protos/messages.grpc.pb.h"
+#  include "examples/grpc/protos/messages.grpc.pb.h"
 #else
-#include "messages.grpc.pb.h"
+#  include "messages.grpc.pb.h"
 #endif
 
 #include "opentelemetry/trace/context.h"
-#include "opentelemetry/trace/semantic_conventions.h"
+#include "opentelemetry/trace/experimental_semantic_conventions.h"
 #include "opentelemetry/trace/span_context_kv_iterable_view.h"
 #include "tracer_common.h"
 
@@ -16,10 +16,10 @@
 
 #include <chrono>
 #include <fstream>
+#include <map>
 #include <sstream>
 #include <string>
 #include <thread>
-#include <map>
 
 using grpc::Server;
 using grpc::ServerBuilder;
@@ -31,7 +31,7 @@ using grpc_example::Greeter;
 using grpc_example::GreetRequest;
 using grpc_example::GreetResponse;
 
-using Span = opentelemetry::trace::Span;
+using Span        = opentelemetry::trace::Span;
 using SpanContext = opentelemetry::trace::SpanContext;
 using namespace opentelemetry::trace;
 
@@ -44,7 +44,8 @@ class GreeterServer final : public Greeter::Service
                const GreetRequest *request,
                GreetResponse *response) override
   {
-    for(  auto elem: context->client_metadata()) {
+    for (auto elem : context->client_metadata())
+    {
       std::cout << "ELEM: " << elem.first << " " << elem.second << "\n";
     }
 
@@ -61,13 +62,13 @@ class GreeterServer final : public Greeter::Service
     options.parent   = opentelemetry::trace::GetSpan(new_context)->GetContext();
 
     std::string span_name = "GreeterService/Greet";
-    auto span             = get_tracer("grpc")
-                    ->StartSpan(span_name,
-                                {{OTEL_CPP_GET_ATTR(AttrRpcSystem), "grpc"},
-                                 {OTEL_CPP_GET_ATTR(AttrRpcService), "GreeterService"},
-                                 {OTEL_CPP_GET_ATTR(AttrRpcMethod), "Greet"},
-                                 {OTEL_CPP_GET_ATTR(AttrRpcGrpcStatusCode), 0}},
-                                options);
+    auto span =
+        get_tracer("grpc")->StartSpan(span_name,
+                                      {{OTEL_CPP_GET_ATTR(AttrRpcSystem), "grpc"},
+                                       {OTEL_CPP_GET_ATTR(AttrRpcService), "GreeterService"},
+                                       {OTEL_CPP_GET_ATTR(AttrRpcMethod), "Greet"},
+                                       {OTEL_CPP_GET_ATTR(AttrRpcGrpcStatusCode), 0}},
+                                      options);
     auto scope = get_tracer("grpc")->WithActiveSpan(span);
 
     // Fetch and parse whatever HTTP headers we can from the gRPC request.

diff --git a/examples/http/client.cc b/examples/http/client.cc
@@ -3,7 +3,7 @@
 
 #include "opentelemetry/ext/http/client/http_client_factory.h"
 #include "opentelemetry/ext/http/common/url_parser.h"
-#include "opentelemetry/trace/semantic_conventions.h"
+#include "opentelemetry/trace/experimental_semantic_conventions.h"
 #include "tracer_common.h"
 
 namespace

diff --git a/examples/http/server.cc b/examples/http/server.cc
@@ -3,7 +3,7 @@
 
 #include "server.h"
 #include "opentelemetry/trace/context.h"
-#include "opentelemetry/trace/semantic_conventions.h"
+#include "opentelemetry/trace/experimental_semantic_conventions.h"
 #include "tracer_common.h"
 
 #include <iostream>

diff --git a/exporters/jaeger/src/recordable.cc b/exporters/jaeger/src/recordable.cc
@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 #include "opentelemetry/exporters/jaeger/recordable.h"
-#include "opentelemetry/sdk/resource/semantic_conventions.h"
+#include "opentelemetry/sdk/resource/experimental_semantic_conventions.h"
 
 OPENTELEMETRY_BEGIN_NAMESPACE
 namespace exporter

diff --git a/exporters/zipkin/src/recordable.cc b/exporters/zipkin/src/recordable.cc
@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 #include "opentelemetry/exporters/zipkin/recordable.h"
-#include "opentelemetry/sdk/resource/semantic_conventions.h"
+#include "opentelemetry/sdk/resource/experimental_semantic_conventions.h"
 
 #include <map>
 #include <string>

diff --git a/...metry/sdk/resource/semantic_conventions.h → ...ource/experimental_semantic_conventions.h b/...metry/sdk/resource/semantic_conventions.h → ...ource/experimental_semantic_conventions.h
@@ -1,3 +1,12 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+// NOTE:
+// This implementation is based on the experimental specs for resource semantic convention as
+// defined here:
+// https://github.com/open-telemetry/opentelemetry-specification/tree/v1.0.0/specification/resource/semantic_conventions
+// and MAY will change in future.
+
 #pragma once
 
 #include <type_traits>

diff --git a/sdk/src/resource/resource.cc b/sdk/src/resource/resource.cc
@@ -3,8 +3,8 @@
 
 #include "opentelemetry/sdk/resource/resource.h"
 #include "opentelemetry/nostd/span.h"
+#include "opentelemetry/sdk/resource/experimental_semantic_conventions.h"
 #include "opentelemetry/sdk/resource/resource_detector.h"
-#include "opentelemetry/sdk/resource/semantic_conventions.h"
 #include "opentelemetry/version.h"
 
 OPENTELEMETRY_BEGIN_NAMESPACE

diff --git a/sdk/test/resource/resource_test.cc b/sdk/test/resource/resource_test.cc
@@ -5,8 +5,8 @@
 #include "opentelemetry/common/key_value_iterable_view.h"
 #include "opentelemetry/nostd/string_view.h"
 #include "opentelemetry/sdk/common/attribute_utils.h"
+#include "opentelemetry/sdk/resource/experimental_semantic_conventions.h"
 #include "opentelemetry/sdk/resource/resource_detector.h"
-#include "opentelemetry/sdk/resource/semantic_conventions.h"
 
 #include <cstdlib>
 #include <string>