From edb8937377a61a546a8201586caa7d8b475907f8 Mon Sep 17 00:00:00 2001
From: WenTao Ou <admin@owent.net>
Date: Sun, 2 Feb 2025 04:20:39 +0800
Subject: [PATCH] [DOC] Add document and example for sharing gRPC Client
 (#3260)

---
 docs/cpp-sdk-factory-design.md | 44 ++++++++++++++++++++++++++++++++++
 examples/otlp/grpc_log_main.cc | 16 ++++++++-----
 2 files changed, 54 insertions(+), 6 deletions(-)

diff --git a/docs/cpp-sdk-factory-design.md b/docs/cpp-sdk-factory-design.md
index a761d6653d..90d2506dd9 100644
--- a/docs/cpp-sdk-factory-design.md
+++ b/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
diff --git a/examples/otlp/grpc_log_main.cc b/examples/otlp/grpc_log_main.cc
index 81a6aa611e..8727c01bf6 100644
--- a/examples/otlp/grpc_log_main.cc
+++ b/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"
@@ -41,10 +42,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));
 
@@ -66,10 +67,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));
 
@@ -106,8 +107,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();