Namespace google::cloud::otel (2.42.0-rc)

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, as described in this library's quickstart.

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();
  }

Troubleshooting

By design, OpenTelemetry exporters fail silently. To troubleshoot problems, enable logging in the client library. Errors during the export are logged at a WARNING level.

Look through the logs for mentions of "BatchWriteSpans". These mentions are likely accompanied by actionable error messages.

If "BatchWriteSpans" is not mentioned in the logs, the client library did not attempt to export any traces. In this case, check that the project ID is not empty and that the sample rate is high enough. Also ensure that OpenTelemetry tracing is enabled in the library.

See also: https://cloud.google.com/trace/docs/troubleshooting#no-data

See Also

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