Namespace google::cloud::otel (2.14.0)

This function configures basic request tracing to Cloud Trace. The google-cloud-cpp libraries use OpenTelemetry to provide observability into their operation at runtime.

You do not need to add OpenTelemetry instrumentation to your code. The C++ client libraries are already instrumented and all sampled RPCs will be sent to Cloud Trace. However, you may want to add instrumentation if multiple RPCs are performed as part of a single logical "operation" in your application.

OpenTelemetry traces, including those reported by the C++ client libraries start as soon as this function returns. Tracing stops when the object returned by this function is deleted.

OpenTelemetry is very configurable, supporting different sampling rates and filters, multiple "exporters" to send the collected data to different services, and multiple mechanisms to chain requests as they move from one program to the next. We do not expect this function will meet the needs of all applications. However, some applications will want a basic configuration that works with Gooogle Cloud Trace.

This function uses the OpenTelemetry C++ API to change the global trace provider (opentelemetry::trace::Provider::#SetTraceProvider()). Do not use this function if your application needs fine control over OpenTelemetry settings.

Usage Example

Change your build scripts to also build and link the library that provides this function.

Change your application to call this function once, for example in main() as follows:

#include <google/cloud/opentelemetry/configure_basic_tracing.h>

...

int main(...) {
...
  auto tracing_project = std::string([TRACING PROJECT]);
  auto tracing = google::cloud::opentelemetry::ConfigureBasicTracing(
      google::cloud::Project(tracing_project));
}

Where [TRACING PROJECT] is the project id where you want to store the traces.

Permissions

The principal (user or service account) running your application will need cloud.traces.patch permissions on the project where you send the traces. These permissions are typically granted as part of the roles/cloudtrace.agent role. If the principal configured in your Application Default Credentials does not have these permissions you will need to provide a different set of credentials:

auto credentials = google::cloud::MakeServiceAccountCredentials(...);
auto tracing = google::cloud::opentelemetry::ConfigureBasicTracing(
    google::cloud::Project(tracing_project),
    google::cloud::Options{}
        .set<google::cloud::UnifiedCredentialsOption>(credentials));

Sampling Rate

By default this function configures the application to trace all requests. This is useful for troubleshooting, but it is excessive if you want to enable tracing by default and use the results to gather latency statistics. To reduce the sampling rate use @refBasicTracingRateOption. If desired, you can use an environment variable (or any other configuration source) to initialize its value.

  namespace gc = ::google::cloud;
  [](std::string project_id) {
    auto project = gc::Project(std::move(project_id));
    auto options = gc::Options{}.set<gc::otel::BasicTracingRateOption>(.001);
    auto configuration = gc::otel::ConfigureBasicTracing(project, options);

    MyApplicationCode();
  }

See Also

https://cloud.google.com/trace/docs/iam for more information about IAM permissions for Cloud Trace.