C++ y OpenTelemetry

Esta página está dirigida a desarrolladores de aplicaciones que quieran recoger datos de Cloud Trace para aplicaciones de C++ mediante OpenTelemetry. OpenTelemetry es un framework de instrumentación independiente del proveedor que puedes usar para recoger datos de trazas y métricas. Para obtener información sobre cómo instrumentar tu código, consulta Instrumentación y observabilidad.

En esta página se explican los siguientes pasos:

  • Instala los paquetes de OpenTelemetry.
  • Configura tu aplicación para exportar spans a Cloud Trace.
  • Configura tu plataforma.

Para obtener información sobre las versiones, consulta lo siguiente:

Para consultar contenido de referencia de OpenTelemetry, consulta lo siguiente:

Para obtener los detalles más recientes sobre OpenTelemetry para C++, así como documentación y ejemplos adicionales, consulta OpenTelemetry.

Antes de empezar

Enable the Cloud Trace API.

Enable the API

Instalar los paquetes de OpenTelemetry

Configurar la exportación de intervalos a Cloud Trace

Para configurar la exportación de datos de seguimiento, llama al método google::cloud::otel::ConfigureBasicTracing(...) en tu método main():

namespace gc = ::google::cloud;
[](std::string project_id) {
  auto project = gc::Project(std::move(project_id));
  auto configuration = gc::otel::ConfigureBasicTracing(project);

  MyApplicationCode();
}

El campo project_id es el proyecto en el que quieres almacenar las trazas. Google Cloud

El método ConfigureBasicTracing(...) crea una instancia de un objeto TracerProvider que implementa un exportador de Cloud Trace. Si el objeto devuelto por la llamada a ConfigureBasicTracing(...) queda fuera del ámbito, se restablece el objeto TracerProvider anterior, si existe.

Configurar la frecuencia de muestreo

Las aplicaciones pueden generar un gran volumen de datos de traza. En el siguiente ejemplo se muestra cómo configurar la frecuencia de muestreo:

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

Exportar a Cloud Trace con un TracerProvider personalizado

Puede que haya casos prácticos que requieran un objeto TracerProvider personalizado. Por ejemplo, si quieres usar varios exportadores al mismo tiempo, debes crear un objeto TracerProvider personalizado. En estos casos, puedes usar el exportador de Cloud Trace directamente:

namespace gc = ::google::cloud;
using ::opentelemetry::trace::Scope;
[](std::string project_id) {
  // Use the Cloud Trace Exporter directly.
  auto project = gc::Project(std::move(project_id));
  auto exporter = gc::otel::MakeTraceExporter(project);

  // Advanced use cases may need to create their own tracer provider, e.g. to
  // export to Cloud Trace and another backend simultaneously. In this
  // example, we just tweak some OpenTelemetry settings that google-cloud-cpp
  // does not expose.
  opentelemetry::sdk::trace::BatchSpanProcessorOptions options;
  options.schedule_delay_millis = std::chrono::milliseconds(1000);
  auto processor =
      opentelemetry::sdk::trace::BatchSpanProcessorFactory::Create(
          std::move(exporter), options);

  // Create a tracer provider and set it as the global trace provider
  opentelemetry::trace::Provider::SetTracerProvider(
      std::shared_ptr<opentelemetry::trace::TracerProvider>(
          opentelemetry::sdk::trace::TracerProviderFactory::Create(
              std::move(processor))));

  MyApplicationCode();

  // Clear the global trace provider
  opentelemetry::trace::Provider::SetTracerProvider(
      opentelemetry::nostd::shared_ptr<
          opentelemetry::trace::TracerProvider>());
}

Instrumentar tu propia aplicación

Para obtener información sobre cómo configurar su aplicación para que capture intervalos de seguimiento, consulte Seguimiento de OpenTelemetry. En esta página se describe cómo hacer lo siguiente:

  • Crear un intervalo
  • Crear intervalos anidados
  • Definir atributos de intervalo
  • Crear intervalos con eventos
  • Crear intervalos con enlaces
// For more details on the OpenTelemetry code in this sample, see:
//     https://opentelemetry.io/docs/instrumentation/cpp/manual/
namespace gc = ::google::cloud;
using ::opentelemetry::trace::Scope;
[](std::string project_id) {
  auto project = gc::Project(std::move(project_id));
  auto configuration = gc::otel::ConfigureBasicTracing(project);

  // Initialize the `Tracer`. This would typically be done once.
  auto provider = opentelemetry::trace::Provider::GetTracerProvider();
  auto tracer = provider->GetTracer("my-application");

  // If your application makes multiple client calls that are logically
  // connected, you may want to instrument your application.
  auto my_function = [tracer] {
    // Start an active span. The span is ended when the `Scope` object is
    // destroyed.
    auto scope = Scope(tracer->StartSpan("my-function-span"));

    // Any spans created by the client library will be children of
    // "my-function-span". i.e. In the distributed trace, the client calls are
    // sub-units of work of `my_function()`, and will be displayed as such in
    // Cloud Trace.
    Client client;
    client.CreateFoo();
    client.DeleteFoo();
  };

  // As an example, start a span to cover both calls to `my_function()`.
  auto scope = Scope(tracer->StartSpan("my-application-span"));
  my_function();
  my_function();
}

Aplicación de ejemplo

Para ver una aplicación de ejemplo, consulta la guía de inicio rápido.

Configurar tu plataforma

Puedes usar Cloud Trace en Google Cloud y otras plataformas.

Se está ejecutando en Google Cloud

Cuando tu aplicación se ejecuta en Google Cloud, no es necesario que proporciones credenciales de autenticación en forma de cuenta de servicio a la biblioteca de cliente. Sin embargo, debes asegurarte de que tu plataforma tenga habilitado el ámbito de acceso de la API Cloud Trace. Google Cloud

Para ver una lista de los Google Cloud entornos compatibles, consulta Compatibilidad con entornos.

En las siguientes configuraciones, los ajustes de ámbito de acceso predeterminados habilitan la API Cloud Trace:

Si usas permisos de acceso personalizados, debes asegurarte de que el permiso de acceso a la API Cloud Trace esté habilitado:

  • Para obtener información sobre cómo configurar los ámbitos de acceso de tu entorno mediante la consola Google Cloud , consulta Configurar tu proyecto de Google Cloud .

  • En el caso de los usuarios de gcloud, especifica los permisos de acceso mediante la marca --scopes e incluye el permiso de acceso a la API Cloud Trace trace.append. Por ejemplo, para crear un clúster de GKE con solo la API Cloud Trace habilitada, haz lo siguiente:

    gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

Ejecutar localmente y en otro lugar

Si tu aplicación se ejecuta fuera de Google Cloud, debes proporcionar credenciales de autenticación en forma de cuenta de servicio a la biblioteca de cliente. La cuenta de servicio debe tener el rol de agente de Cloud Trace. Para ver instrucciones, consulta el artículo Crear una cuenta de servicio.

Las bibliotecas de clienteGoogle Cloud usan las credenciales de aplicación predeterminadas (ADC) para encontrar las credenciales de tu aplicación.

Puedes proporcionar estas credenciales de tres formas:

  • Ejecutar gcloud auth application-default login

  • Coloca la cuenta de servicio en una ruta predeterminada de tu sistema operativo. A continuación se indican las rutas predeterminadas para Windows y Linux:

    • Windows: %APPDATA%/gcloud/application_default_credentials.json

    • Linux: $HOME/.config/gcloud/application_default_credentials.json

  • Asigna a la variable de entorno GOOGLE_APPLICATION_CREDENTIALS la ruta a tu cuenta de servicio:

Linux/macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

Mostrar trazas

En la Google Cloud consola, ve a la página Explorador de trazas:

Ir a Explorador de trazas

También puedes encontrar esta página mediante la barra de búsqueda.

Solución de problemas

Para obtener información sobre cómo solucionar problemas con Cloud Trace, consulta la página de solución de problemas.

Para depurar el exportador de Cloud Trace de C++, consulta la sección Solución de problemas de la documentación de referencia.

Recursos