Introduce StackdriverOptions for stats and trace exporters. (census-instrumentation#182)

Author: g-easy

examples/grpc/stackdriver.cc

@@ -30,9 +30,14 @@ void RegisterStackdriverExporters() {
   }
   const char *hostname = getenv("HOSTNAME");
   if (hostname == nullptr) hostname = "hostname";
-  const std::string opencensus_task =
-      absl::StrCat("cpp-", getpid(), "@", hostname);
-  opencensus::exporters::stats::StackdriverExporter::Register(project_id,
-                                                              opencensus_task);
-  opencensus::exporters::trace::StackdriverExporter::Register(project_id);
+
+  opencensus::exporters::stats::StackdriverOptions stats_opts;
+  stats_opts.project_id = project_id;
+  stats_opts.opencensus_task = absl::StrCat("cpp-", getpid(), "@", hostname);
+
+  opencensus::exporters::trace::StackdriverOptions trace_opts;
+  trace_opts.project_id = project_id;
+
+  opencensus::exporters::stats::StackdriverExporter::Register(stats_opts);
+  opencensus::exporters::trace::StackdriverExporter::Register(trace_opts);
 }

opencensus/exporters/stats/stackdriver/BUILD

@@ -30,6 +30,7 @@ cc_library(
         "//opencensus/common/internal/grpc:status",
         "//opencensus/stats",
         "@com_github_grpc_grpc//:grpc++",
+        "@com_google_absl//absl/base",
         "@com_google_absl//absl/strings",
         "@com_google_absl//absl/synchronization",
         "@com_google_absl//absl/time",

opencensus/exporters/stats/stackdriver/README.md

@@ -39,20 +39,33 @@ documentation for configuring roles. The "Monitoring Editor" role is required.
 
 ### Register the exporter
 
-`#include opencensus/exporters/stats/stackdriver/stackdriver_exporter.h` (if
-using Bazel, this requires a dependency on
-`"@io_opencensus_cpp//exporters/stats/stackdriver:stackdriver_exporter"`).
+Include:
+
+```c++
+#include "opencensus/exporters/stats/stackdriver/stackdriver_exporter.h"
+```
+
+Add a BUILD dependency on:
+
+```
+"@io_opencensus_cpp//exporters/stats/stackdriver:stackdriver_exporter",
+```
+
 In your application's initialization code, register the exporter:
+
 ```c++
 const char* hostname = getenv("HOSTNAME");
 if (hostname == nullptr) hostname = "hostname";
-const std::string opencensus_task =
-    absl::StrCat("cpp-", getpid(), "@", hostname);
-opencensus::exporters::stats::StackdriverExporter::Register(
-    "my-stackdriver-project-id", opencensus_task);
+
+opencensus::exporters::stats::StackdriverOptions opts;
+opts.project_id = "my-stackdriver-project-id";
+opts.opencensus_task = absl::StrCat("cpp-", getpid(), "@", hostname);
+
+opencensus::exporters::stats::StackdriverExporter::Register(opts);
 ```
-The `opencensus_task` may be anything, but must be unique among all exporters
-simultaneously exporting to Stackdriver concurrently; the format
+
+The `opencensus_task` may be anything, but must be unique among all processes
+simultaneously exporting to Stackdriver. The format
 `"cpp-${PROCESS_ID}@${HOSTNAME}"` is recommended.
 
 ### Register views and record stats

opencensus/exporters/stats/stackdriver/internal/stackdriver_e2e_test.cc

@@ -35,7 +35,7 @@ namespace exporters {
 namespace stats {
 namespace {
 
-// This is a true end-to-end test for the stackdriver exporter, connecting to
+// This is a true end-to-end test for the Stackdriver Exporter, connecting to
 // production Stackdriver. As such, it is subject to failures in networking or
 // the Stackdriver backend; it also cannot be run multiple times simultaneously
 // under the same Cloud project.
@@ -66,7 +66,10 @@ class StackdriverE2eTest : public ::testing::Test {
                    "unset.\n";
       std::abort();
     }
-    StackdriverExporter::Register(project_id_, "test_task");
+    StackdriverOptions opts;
+    opts.project_id = std::string(project_id_);
+    opts.opencensus_task = "test_task";
+    StackdriverExporter::Register(opts);
   }
 
   // Retrieves data exported under 'descriptor'.

opencensus/exporters/stats/stackdriver/internal/stackdriver_exporter.cc

@@ -43,7 +43,7 @@ constexpr int kTimeSeriesBatchSize = 200;
 
 class Handler : public ::opencensus::stats::StatsExporter::Handler {
  public:
-  Handler(absl::string_view project_id, absl::string_view opencensus_task);
+  explicit Handler(const StackdriverOptions& opts);
 
   void ExportViewData(
       const std::vector<std::pair<opencensus::stats::ViewDescriptor,
@@ -59,18 +59,17 @@ class Handler : public ::opencensus::stats::StatsExporter::Handler {
   bool MaybeRegisterView(const opencensus::stats::ViewDescriptor& descriptor)
       EXCLUSIVE_LOCKS_REQUIRED(mu_);
 
+  const StackdriverOptions opts_;
   const std::string project_id_;
-  const std::string opencensus_task_;
   const std::unique_ptr<google::monitoring::v3::MetricService::Stub> stub_;
   mutable absl::Mutex mu_;
   std::unordered_map<std::string, opencensus::stats::ViewDescriptor>
       registered_descriptors_ GUARDED_BY(mu_);
 };
 
-Handler::Handler(absl::string_view project_id,
-                 absl::string_view opencensus_task)
-    : project_id_(absl::StrCat(kProjectIdPrefix, project_id)),
-      opencensus_task_(opencensus_task),
+Handler::Handler(const StackdriverOptions& opts)
+    : opts_(opts),
+      project_id_(absl::StrCat(kProjectIdPrefix, opts.project_id)),
       stub_(google::monitoring::v3::MetricService::NewStub(
           ::grpc::CreateChannel(kGoogleStackdriverStatsAddress,
                                 ::grpc::GoogleDefaultCredentials()))) {}
@@ -86,7 +85,7 @@ void Handler::ExportViewData(
       continue;
     }
     const auto view_time_series =
-        MakeTimeSeries(datum.first, datum.second, opencensus_task_);
+        MakeTimeSeries(datum.first, datum.second, opts_.opencensus_task);
     time_series.insert(time_series.end(), view_time_series.begin(),
                        view_time_series.end());
   }
@@ -161,10 +160,18 @@ bool Handler::MaybeRegisterView(
 }  // namespace
 
 // static
+void StackdriverExporter::Register(const StackdriverOptions& opts) {
+  opencensus::stats::StatsExporter::RegisterPushHandler(
+      absl::WrapUnique(new Handler(opts)));
+}
+
+// static, DEPRECATED
 void StackdriverExporter::Register(absl::string_view project_id,
                                    absl::string_view opencensus_task) {
-  opencensus::stats::StatsExporter::RegisterPushHandler(
-      absl::WrapUnique(new Handler(project_id, opencensus_task)));
+  StackdriverOptions opts;
+  opts.project_id = std::string(project_id);
+  opts.opencensus_task = std::string(opencensus_task);
+  Register(opts);
 }
 
 }  // namespace stats

opencensus/exporters/stats/stackdriver/stackdriver_exporter.h

@@ -15,22 +15,36 @@
 #ifndef OPENCENSUS_EXPORTERS_STATS_STACKDRIVER_STACKDRIVER_EXPORTER_H_
 #define OPENCENSUS_EXPORTERS_STATS_STACKDRIVER_STACKDRIVER_EXPORTER_H_
 
+#include <string>
+
+#include "absl/base/macros.h"
 #include "absl/strings/string_view.h"
 
 namespace opencensus {
 namespace exporters {
 namespace stats {
 
+struct StackdriverOptions {
+  // The Stackdriver project ID to use.
+  std::string project_id;
+
+  // The opencensus_task is used to uniquely identify the task in Stackdriver.
+  // The recommended format is "{LANGUAGE}-{PID}@{HOSTNAME}". If PID is not
+  // available, a random number may be used.
+  std::string opencensus_task;
+};
+
 // Exports stats for registered views (see opencensus/stats/stats_exporter.h) to
 // Stackdriver. StackdriverExporter is thread-safe.
 class StackdriverExporter {
  public:
-  // Registers the exporter and sets the project ID and task value. project_id
-  // should be the exact id of the project, as in the GCP console, with no
-  // prefix--e.g. "sample-project-id". opencensus_task is used to uniquely
-  // identify the task in Stackdriver. The recommended format is
-  // "{LANGUAGE}-{PID}@{HOSTNAME}"; if {PID} is not available a random number
-  // may be used.
+  // Registers the exporter.
+  static void Register(const StackdriverOptions& opts);
+
+  // TODO: Retire this:
+  ABSL_DEPRECATED(
+      "Register() without StackdriverOptions is deprecated and "
+      "will be removed on or after 2019-03-20")
   static void Register(absl::string_view project_id,
                        absl::string_view opencensus_task);
 

opencensus/exporters/trace/stackdriver/BUILD

@@ -32,6 +32,7 @@ cc_library(
         "//opencensus/common/internal/grpc:status",
         "//opencensus/trace",
         "@com_github_grpc_grpc//:grpc++",
+        "@com_google_absl//absl/base",
         "@com_google_absl//absl/memory",
         "@com_google_absl//absl/strings",
     ],

opencensus/exporters/trace/stackdriver/internal/stackdriver_exporter.cc

@@ -277,11 +277,19 @@ void Handler::Export(
 
 }  // namespace
 
-void StackdriverExporter::Register(absl::string_view project_id) {
+// static
+void StackdriverExporter::Register(const StackdriverOptions& opts) {
   auto creds = grpc::GoogleDefaultCredentials();
   auto channel = ::grpc::CreateChannel(kGoogleStackdriverTraceAddress, creds);
   ::opencensus::trace::exporter::SpanExporter::RegisterHandler(
-      absl::make_unique<Handler>(project_id, channel));
+      absl::make_unique<Handler>(opts.project_id, channel));
+}
+
+// static, DEPRECATED
+void StackdriverExporter::Register(absl::string_view project_id) {
+  StackdriverOptions opts;
+  opts.project_id = std::string(project_id);
+  Register(opts);
 }
 
 }  // namespace trace

opencensus/exporters/trace/stackdriver/stackdriver_exporter.h

@@ -15,15 +15,29 @@
 #ifndef OPENCENSUS_EXPORTERS_TRACE_STACKDRIVER_STACKDRIVER_EXPORTER_H_
 #define OPENCENSUS_EXPORTERS_TRACE_STACKDRIVER_STACKDRIVER_EXPORTER_H_
 
+#include <string>
+
+#include "absl/base/macros.h"
 #include "absl/strings/string_view.h"
 
 namespace opencensus {
 namespace exporters {
 namespace trace {
 
+struct StackdriverOptions {
+  // The Stackdriver project ID to use.
+  std::string project_id;
+};
+
 class StackdriverExporter {
  public:
-  // Registers the exporter and sets the project ID.
+  // Registers the exporter.
+  static void Register(const StackdriverOptions& opts);
+
+  // TODO: Retire this:
+  ABSL_DEPRECATED(
+      "Register() without StackdriverOptions is deprecated and "
+      "will be removed on or after 2019-03-20")
   static void Register(absl::string_view project_id);
 
  private: