[Trace SDK] Implement builders (open-telemetry#1393)

Implemented code review comments:
- reworded docs/cpp-sdk-factory-design.md,
- re organized includes,
- added TracerContextFactory.

Also:
- renamed Build() methods to Create(),
  for consistency with HttpClientFactory::Create(),
- added doxygen comments,
- added CHANGELOG entry.

CHANGELOG.md

@@ -15,6 +15,9 @@ Increment the:
 
 ## [Unreleased]
 
+* [TRACE SDK] Add trace sdk builders (#1393) [#1471](https://github.com/open-telemetry/opentelemetry-cpp/pull/1471)
+* [EXAMPLE] Fix memory ownership of InMemorySpanExporter (#1473) [#1471](https://github.com/open-telemetry/opentelemetry-cpp/pull/1471)
+
 ## [1.4.1] 2022-06-19
 
 * [METRICS SDK] Fix variables inizialization [#1430](https://github.com/open-telemetry/opentelemetry-cpp/pull/1430)

docs/cpp-sdk-factory-design.md

@@ -1,16 +1,20 @@
 # SDK Factory Design
 
-The use cases for applications calling the opentelemetry SDK can be
-classified into the following two broad categories:
+When an application owner needs to configure the opentelemetry SDK,
+this can be done in different ways:
 
-- SDK users, the application needs to assemble a trace provider / metrics
-  provider / log provider by assembling available SDK elements,
-- SDK implementors, the application needs to extend the opentelemetry SDK
-  by implementing new features.
+- by assembly of available SDK elements already provided,
+- by extension of the SDK to support more functionality.
 
-## SDK users
+The sections below investigate each use case,
+and the consequences when using shared libraries.
 
-Assume an application needs to build a trace provider, using the gRPC trace
+Last, a section discuss the impact of C++ conditional parameters
+on the SDK interface, and how this affects shared libraries.
+
+## SDK assembly
+
+Assume the application owner needs to build a trace provider, using the gRPC trace
 exporter.
 
 ### Case study, direct call to the SDK implementation classes
@@ -70,14 +74,15 @@ from the application code:
 ```cpp
 opentelemetry::exporter::otlp::OtlpGrpcExporterOptions opts;
 
-auto exporter = opentelemetry::exporter::otlp::OtlpGrpcExporterFactory::Build(opts);
+auto exporter =
+  opentelemetry::exporter::otlp::OtlpGrpcExporterFactory::Create(opts);
 ```
 
 While the application code does not change much,
 the amount of SDK internals exposed to the application is reduced
 significantly.
 
-OtlpGrpcExporterFactory::Build() actually returns a abstract SpanExporter
+OtlpGrpcExporterFactory::Create() actually returns a abstract SpanExporter
 object, instead of a concrete OtlpGrpcExporter object.
 
 As a result, the application binary is not even aware of the implementation
@@ -89,9 +94,9 @@ This property makes it possible to:
 - deploy a new SDK shared library
 - keep the application unchanged
 
-## SDK implementors
+## SDK extension
 
-Applications that want to extend existing SDK classes are expected
+Applications owners who want to extend existing SDK classes are expected
 to have a stronger dependency on the SDK internals.
 
 For example, with

examples/batch/main.cc

@@ -1,19 +1,10 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
-/* API */
-
-#include "opentelemetry/trace/provider.h"
-
-/* SDK */
-
+#include "opentelemetry/exporters/ostream/span_exporter_factory.h"
 #include "opentelemetry/sdk/trace/batch_span_processor_factory.h"
 #include "opentelemetry/sdk/trace/tracer_provider_factory.h"
-
-/* Exporter */
-
-// Using an exporter that simply dumps span data to stdout.
-#include "opentelemetry/exporters/ostream/span_exporter_factory.h"
+#include "opentelemetry/trace/provider.h"
 
 #include <chrono>
 #include <thread>
@@ -30,7 +21,7 @@ namespace
 
 void initTracer()
 {
-  auto exporter = trace_exporter::OStreamSpanExporterFactory::Build();
+  auto exporter = trace_exporter::OStreamSpanExporterFactory::Create();
 
   // CONFIGURE BATCH SPAN PROCESSOR PARAMETERS
 
@@ -46,9 +37,9 @@ void initTracer()
   resource::ResourceAttributes attributes = {{"service", "test_service"}, {"version", (uint32_t)1}};
   auto resource                           = resource::Resource::Create(attributes);
 
-  auto processor = trace_sdk::BatchSpanProcessorFactory::Build(std::move(exporter), options);
+  auto processor = trace_sdk::BatchSpanProcessorFactory::Create(std::move(exporter), options);
 
-  auto provider = trace_sdk::TracerProviderFactory::Build(std::move(processor), resource);
+  auto provider = trace_sdk::TracerProviderFactory::Create(std::move(processor), resource);
 
   // Set the global trace provider.
   trace_api::Provider::SetTracerProvider(provider);

examples/grpc/tracer_common.h

@@ -3,23 +3,15 @@
 
 #pragma once
 
-/* API */
-
 #include "opentelemetry/context/propagation/global_propagator.h"
 #include "opentelemetry/context/propagation/text_map_propagator.h"
+#include "opentelemetry/exporters/ostream/span_exporter_factory.h"
 #include "opentelemetry/nostd/shared_ptr.h"
-#include "opentelemetry/trace/propagation/http_trace_context.h"
-#include "opentelemetry/trace/provider.h"
-
-/* SDK */
-
 #include "opentelemetry/sdk/trace/simple_processor_factory.h"
 #include "opentelemetry/sdk/trace/tracer_context.h"
 #include "opentelemetry/sdk/trace/tracer_provider_factory.h"
-
-/* Exporter */
-
-#include "opentelemetry/exporters/ostream/span_exporter_factory.h"
+#include "opentelemetry/trace/propagation/http_trace_context.h"
+#include "opentelemetry/trace/provider.h"
 
 #include <grpcpp/grpcpp.h>
 #include <cstring>
@@ -79,14 +71,14 @@ class GrpcServerCarrier : public opentelemetry::context::propagation::TextMapCar
 
 void initTracer()
 {
-  auto exporter = opentelemetry::exporter::trace::OStreamSpanExporterFactory::Build();
+  auto exporter = opentelemetry::exporter::trace::OStreamSpanExporterFactory::Create();
   auto processor =
-      opentelemetry::sdk::trace::SimpleSpanProcessorFactory::Build(std::move(exporter));
+      opentelemetry::sdk::trace::SimpleSpanProcessorFactory::Create(std::move(exporter));
   std::vector<std::unique_ptr<opentelemetry::sdk::trace::SpanProcessor>> processors;
   processors.push_back(std::move(processor));
   // Default is an always-on sampler.
   auto context  = std::make_shared<opentelemetry::sdk::trace::TracerContext>(std::move(processors));
-  auto provider = opentelemetry::sdk::trace::TracerProviderFactory::Build(context);
+  auto provider = opentelemetry::sdk::trace::TracerProviderFactory::Create(context);
   // Set the global trace provider
   opentelemetry::trace::Provider::SetTracerProvider(provider);
 

examples/http/tracer_common.h

@@ -59,14 +59,14 @@ class HttpTextMapCarrier : public opentelemetry::context::propagation::TextMapCa
 
 void initTracer()
 {
-  auto exporter = opentelemetry::exporter::trace::OStreamSpanExporterFactory::Build();
+  auto exporter = opentelemetry::exporter::trace::OStreamSpanExporterFactory::Create();
   auto processor =
-      opentelemetry::sdk::trace::SimpleSpanProcessorFactory::Build(std::move(exporter));
+      opentelemetry::sdk::trace::SimpleSpanProcessorFactory::Create(std::move(exporter));
   std::vector<std::unique_ptr<opentelemetry::sdk::trace::SpanProcessor>> processors;
   processors.push_back(std::move(processor));
   // Default is an always-on sampler.
   auto context  = std::make_shared<opentelemetry::sdk::trace::TracerContext>(std::move(processors));
-  auto provider = opentelemetry::sdk::trace::TracerProviderFactory::Build(context);
+  auto provider = opentelemetry::sdk::trace::TracerProviderFactory::Create(context);
   // Set the global trace provider
   opentelemetry::trace::Provider::SetTracerProvider(provider);
 

examples/jaeger/main.cc

@@ -23,9 +23,9 @@ opentelemetry::exporter::jaeger::JaegerExporterOptions opts;
 void InitTracer()
 {
   // Create Jaeger exporter instance
-  auto exporter  = jaeger::JaegerExporterFactory::Build(opts);
-  auto processor = trace_sdk::SimpleSpanProcessorFactory::Build(std::move(exporter));
-  auto provider  = trace_sdk::TracerProviderFactory::Build(std::move(processor));
+  auto exporter  = jaeger::JaegerExporterFactory::Create(opts);
+  auto processor = trace_sdk::SimpleSpanProcessorFactory::Create(std::move(exporter));
+  auto provider  = trace_sdk::TracerProviderFactory::Create(std::move(processor));
   // Set the global trace provider
   trace::Provider::SetTracerProvider(provider);
 }

examples/multi_processor/main.cc

@@ -1,23 +1,13 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
-/* API */
-
-#include "opentelemetry/trace/provider.h"
-
-/* SDK */
-
-#include "opentelemetry/sdk/trace/simple_processor_factory.h"
-#include "opentelemetry/sdk/trace/tracer_context.h"
-#include "opentelemetry/sdk/trace/tracer_provider_factory.h"
-
-/* Exporter */
-
 #include "opentelemetry/exporters/memory/in_memory_span_data.h"
 #include "opentelemetry/exporters/memory/in_memory_span_exporter_factory.h"
 #include "opentelemetry/exporters/ostream/span_exporter_factory.h"
-
-/* Application */
+#include "opentelemetry/sdk/trace/simple_processor_factory.h"
+#include "opentelemetry/sdk/trace/tracer_context.h"
+#include "opentelemetry/sdk/trace/tracer_provider_factory.h"
+#include "opentelemetry/trace/provider.h"
 
 #ifdef BAZEL_BUILD
 #  include "examples/common/foo_library/foo_library.h"
@@ -36,16 +26,16 @@ std::shared_ptr<InMemorySpanData> initTracer()
 {
   std::shared_ptr<InMemorySpanData> data;
 
-  auto exporter1  = opentelemetry::exporter::trace::OStreamSpanExporterFactory::Build();
-  auto processor1 = trace_sdk::SimpleSpanProcessorFactory::Build(std::move(exporter1));
+  auto exporter1  = opentelemetry::exporter::trace::OStreamSpanExporterFactory::Create();
+  auto processor1 = trace_sdk::SimpleSpanProcessorFactory::Create(std::move(exporter1));
 
-  auto exporter2  = opentelemetry::exporter::memory::InMemorySpanExporterFactory::Build(data);
-  auto processor2 = trace_sdk::SimpleSpanProcessorFactory::Build(std::move(exporter2));
+  auto exporter2  = opentelemetry::exporter::memory::InMemorySpanExporterFactory::Create(data);
+  auto processor2 = trace_sdk::SimpleSpanProcessorFactory::Create(std::move(exporter2));
 
   std::vector<std::unique_ptr<opentelemetry::sdk::trace::SpanProcessor>> processors;
   processors.push_back(std::move(processor1));
   processors.push_back(std::move(processor2));
-  auto provider = trace_sdk::TracerProviderFactory::Build(std::move(processors));
+  auto provider = trace_sdk::TracerProviderFactory::Create(std::move(processors));
 
   // Set the global trace provider
   trace_api::Provider::SetTracerProvider(std::move(provider));

examples/multithreaded/main.cc

@@ -1,15 +1,13 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
+#include "opentelemetry/exporters/ostream/span_exporter_factory.h"
 #include "opentelemetry/sdk/resource/resource.h"
 #include "opentelemetry/sdk/trace/simple_processor_factory.h"
 #include "opentelemetry/sdk/trace/tracer_provider_factory.h"
 #include "opentelemetry/trace/provider.h"
 #include "opentelemetry/trace/scope.h"
 
-// Using an exporter that simply dumps span data to stdout.
-#include "opentelemetry/exporters/ostream/span_exporter_factory.h"
-
 #include <algorithm>
 #include <thread>
 
@@ -21,9 +19,9 @@ namespace
 {
 void initTracer()
 {
-  auto exporter  = opentelemetry::exporter::trace::OStreamSpanExporterFactory::Build();
-  auto processor = trace_sdk::SimpleSpanProcessorFactory::Build(std::move(exporter));
-  auto provider  = trace_sdk::TracerProviderFactory::Build(
+  auto exporter  = opentelemetry::exporter::trace::OStreamSpanExporterFactory::Create();
+  auto processor = trace_sdk::SimpleSpanProcessorFactory::Create(std::move(exporter));
+  auto provider  = trace_sdk::TracerProviderFactory::Create(
       std::move(processor), opentelemetry::sdk::resource::Resource::Create({}));
   // Set the global trace provider
   trace_api::Provider::SetTracerProvider(provider);

examples/otlp/grpc_log_main.cc

@@ -36,9 +36,9 @@ opentelemetry::exporter::otlp::OtlpGrpcExporterOptions opts;
 void InitTracer()
 {
   // Create OTLP exporter instance
-  auto exporter  = otlp::OtlpGrpcExporterFactory::Build(opts);
-  auto processor = trace_sdk::SimpleSpanProcessorFactory::Build(std::move(exporter));
-  auto provider  = trace_sdk::TracerProviderFactory::Build(std::move(processor));
+  auto exporter  = otlp::OtlpGrpcExporterFactory::Create(opts);
+  auto processor = trace_sdk::SimpleSpanProcessorFactory::Create(std::move(exporter));
+  auto provider  = trace_sdk::TracerProviderFactory::Create(std::move(processor));
   // Set the global trace provider
   trace::Provider::SetTracerProvider(provider);
 }

examples/otlp/grpc_main.cc

@@ -23,9 +23,9 @@ opentelemetry::exporter::otlp::OtlpGrpcExporterOptions opts;
 void InitTracer()
 {
   // Create OTLP exporter instance
-  auto exporter  = otlp::OtlpGrpcExporterFactory::Build(opts);
-  auto processor = trace_sdk::SimpleSpanProcessorFactory::Build(std::move(exporter));
-  auto provider  = trace_sdk::TracerProviderFactory::Build(std::move(processor));
+  auto exporter  = otlp::OtlpGrpcExporterFactory::Create(opts);
+  auto processor = trace_sdk::SimpleSpanProcessorFactory::Create(std::move(exporter));
+  auto provider  = trace_sdk::TracerProviderFactory::Create(std::move(processor));
   // Set the global trace provider
   trace::Provider::SetTracerProvider(provider);
 }

examples/otlp/http_log_main.cc

@@ -33,9 +33,9 @@ opentelemetry::exporter::otlp::OtlpHttpExporterOptions opts;
 void InitTracer()
 {
   // Create OTLP exporter instance
-  auto exporter  = otlp::OtlpHttpExporterFactory::Build(opts);
-  auto processor = trace_sdk::SimpleSpanProcessorFactory::Build(std::move(exporter));
-  auto provider  = trace_sdk::TracerProviderFactory::Build(std::move(processor));
+  auto exporter  = otlp::OtlpHttpExporterFactory::Create(opts);
+  auto processor = trace_sdk::SimpleSpanProcessorFactory::Create(std::move(exporter));
+  auto provider  = trace_sdk::TracerProviderFactory::Create(std::move(processor));
   // Set the global trace provider
   trace::Provider::SetTracerProvider(provider);
 }

examples/otlp/http_main.cc

@@ -26,9 +26,9 @@ opentelemetry::exporter::otlp::OtlpHttpExporterOptions opts;
 void InitTracer()
 {
   // Create OTLP exporter instance
-  auto exporter  = otlp::OtlpHttpExporterFactory::Build(opts);
-  auto processor = trace_sdk::SimpleSpanProcessorFactory::Build(std::move(exporter));
-  auto provider  = trace_sdk::TracerProviderFactory::Build(std::move(processor));
+  auto exporter  = otlp::OtlpHttpExporterFactory::Create(opts);
+  auto processor = trace_sdk::SimpleSpanProcessorFactory::Create(std::move(exporter));
+  auto provider  = trace_sdk::TracerProviderFactory::Create(std::move(processor));
   // Set the global trace provider
   trace::Provider::SetTracerProvider(provider);
 }

examples/simple/main.cc

@@ -1,21 +1,10 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
-/* API */
-
-#include "opentelemetry/trace/provider.h"
-
-/* SDK */
-
+#include "opentelemetry/exporters/ostream/span_exporter_factory.h"
 #include "opentelemetry/sdk/trace/simple_processor_factory.h"
 #include "opentelemetry/sdk/trace/tracer_provider_factory.h"
-
-/* Exporter */
-
-// Using an exporter that simply dumps span data to stdout.
-#include "opentelemetry/exporters/ostream/span_exporter_factory.h"
-
-/* Application code */
+#include "opentelemetry/trace/provider.h"
 
 #ifdef BAZEL_BUILD
 #  include "examples/common/foo_library/foo_library.h"
@@ -31,9 +20,9 @@ namespace
 {
 void initTracer()
 {
-  auto exporter  = trace_exporter::OStreamSpanExporterFactory::Build();
-  auto processor = trace_sdk::SimpleSpanProcessorFactory::Build(std::move(exporter));
-  auto provider  = trace_sdk::TracerProviderFactory::Build(std::move(processor));
+  auto exporter  = trace_exporter::OStreamSpanExporterFactory::Create();
+  auto processor = trace_sdk::SimpleSpanProcessorFactory::Create(std::move(exporter));
+  auto provider  = trace_sdk::TracerProviderFactory::Create(std::move(processor));
 
   // Set the global trace provider
   trace_api::Provider::SetTracerProvider(provider);

examples/zipkin/main.cc

@@ -26,9 +26,9 @@ void InitTracer()
   // Create zipkin exporter instance
   resource::ResourceAttributes attributes = {{"service.name", "zipkin_demo_service"}};
   auto resource                           = resource::Resource::Create(attributes);
-  auto exporter                           = zipkin::ZipkinExporterFactory::Build(opts);
-  auto processor = trace_sdk::SimpleSpanProcessorFactory::Build(std::move(exporter));
-  auto provider  = trace_sdk::TracerProviderFactory::Build(std::move(processor), resource);
+  auto exporter                           = zipkin::ZipkinExporterFactory::Create(opts);
+  auto processor = trace_sdk::SimpleSpanProcessorFactory::Create(std::move(exporter));
+  auto provider  = trace_sdk::TracerProviderFactory::Create(std::move(processor), resource);
   // Set the global trace provider
   trace::Provider::SetTracerProvider(provider);
 }

exporters/jaeger/include/opentelemetry/exporters/jaeger/jaeger_exporter_factory.h

@@ -12,11 +12,21 @@ namespace exporter
 namespace jaeger
 {
 
+/**
+ * Factory class for JaegerExporter.
+ */
 class JaegerExporterFactory
 {
 public:
-  static std::unique_ptr<opentelemetry::sdk::trace::SpanExporter> Build();
-  static std::unique_ptr<opentelemetry::sdk::trace::SpanExporter> Build(
+  /**
+   * Create a JaegerExporter using all default options.
+   */
+  static std::unique_ptr<opentelemetry::sdk::trace::SpanExporter> Create();
+
+  /**
+   * Create a JaegerExporter using the given options.
+   */
+  static std::unique_ptr<opentelemetry::sdk::trace::SpanExporter> Create(
       const JaegerExporterOptions &options);
 };