Merge pull request #170 from open-telemetry/main

[DOC] Add document and example for sharing gRPC Client (open-telemetry#3260)

docs/cpp-sdk-factory-design.md

@@ -94,6 +94,50 @@ This property makes it possible to:
 - deploy a new SDK shared library
 - keep the application unchanged
 
+### Case study, using Factory and shared gRPC client between OTLP gRPC exporters
+
+To reduce the cost of gRPC, the SDK allow users to share gRPC clients between
+OTLP gRPC exporters when these exporters have the same settings. This can be
+used as follows from the application code:
+
+```cpp
+// Include following headers
+#include "opentelemetry/exporters/otlp/otlp_grpc_client_factory.h"
+#include "opentelemetry/exporters/otlp/otlp_grpc_exporter_factory.h"
+#include "opentelemetry/exporters/otlp/otlp_grpc_exporter_options.h"
+#include "opentelemetry/exporters/otlp/otlp_grpc_log_record_exporter_factory.h"
+#include "opentelemetry/exporters/otlp/otlp_grpc_log_record_exporter_options.h"
+
+// Create exporters with shared gRPC Client
+namespace otlp = opentelemetry::exporter::otlp;
+
+void SetupOtlp() {
+  otlp::OtlpGrpcClientOptions client_opts;
+  otlp::OtlpGrpcExporterOptions trace_opts;
+  otlp::OtlpGrpcLogRecordExporterOptions log_opts;
+
+  // Setting client_opts, trace_opts and log_opts
+  // client_opts.endpoint = "localhost:1234";
+  // Or we can use client_opts = trace_opts; to copy options from environment of
+  // trace OTLP exporter.
+
+  std::shared_ptr<otlp::OtlpGrpcClient> shared_client =
+    otlp::OtlpGrpcClientFactory::Create(client_opts);
+
+  // Create exporters
+  auto trace_exporter =
+    otlp::OtlpGrpcExporterFactory::Create(trace_opts, shared_client);
+  auto log_exporter =
+    otlp::OtlpGrpcLogRecordExporterFactory::Create(log_opts, shared_client);
+
+  // Other initialization codes ...
+}
+```
+
+Be careful, create OTLP exporters with an existing `OtlpGrpcClient` will ignore
+the options of gRPC when passing the `OtlpGrpcExporterOptions` or other option
+object.
+
 ## SDK extension
 
 Applications owners who want to extend existing SDK classes are expected

examples/otlp/grpc_log_main.cc

@@ -1,6 +1,7 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
+#include "opentelemetry/exporters/otlp/otlp_grpc_client_factory.h"
 #include "opentelemetry/exporters/otlp/otlp_grpc_exporter_factory.h"
 #include "opentelemetry/exporters/otlp/otlp_grpc_exporter_options.h"
 #include "opentelemetry/exporters/otlp/otlp_grpc_log_record_exporter_factory.h"
@@ -37,10 +38,10 @@ opentelemetry::exporter::otlp::OtlpGrpcLogRecordExporterOptions log_opts;
 std::shared_ptr<opentelemetry::sdk::trace::TracerProvider> tracer_provider;
 std::shared_ptr<opentelemetry::sdk::logs::LoggerProvider> logger_provider;
 
-void InitTracer()
+void InitTracer(const std::shared_ptr<otlp::OtlpGrpcClient> &shared_client)
 {
   // Create OTLP exporter instance
-  auto exporter   = otlp::OtlpGrpcExporterFactory::Create(opts);
+  auto exporter   = otlp::OtlpGrpcExporterFactory::Create(opts, shared_client);
   auto processor  = trace_sdk::SimpleSpanProcessorFactory::Create(std::move(exporter));
   tracer_provider = trace_sdk::TracerProviderFactory::Create(std::move(processor));
 
@@ -62,10 +63,10 @@ void CleanupTracer()
   trace::Provider::SetTracerProvider(none);
 }
 
-void InitLogger()
+void InitLogger(const std::shared_ptr<otlp::OtlpGrpcClient> &shared_client)
 {
   // Create OTLP exporter instance
-  auto exporter   = otlp::OtlpGrpcLogRecordExporterFactory::Create(log_opts);
+  auto exporter   = otlp::OtlpGrpcLogRecordExporterFactory::Create(log_opts, shared_client);
   auto processor  = logs_sdk::SimpleLogRecordProcessorFactory::Create(std::move(exporter));
   logger_provider = logs_sdk::LoggerProviderFactory::Create(std::move(processor));
 
@@ -102,8 +103,11 @@ int main(int argc, char *argv[])
       log_opts.ssl_credentials_cacert_path = argv[2];
     }
   }
-  InitLogger();
-  InitTracer();
+
+  std::shared_ptr<otlp::OtlpGrpcClient> shared_client = otlp::OtlpGrpcClientFactory::Create(opts);
+
+  InitLogger(shared_client);
+  InitTracer(shared_client);
   foo_library();
   CleanupTracer();
   CleanupLogger();