C++ y OpenTelemetry

Puedes instrumentar una aplicación de C++ con OpenTelemetry y configurar el exportador deGoogle Cloud C++ OpenTelemetry para enviar intervalos de seguimiento a Cloud Trace en tu proyecto de Google Cloud . Puedes usar una configuración de registro básica, configurar la tasa de muestreo del registro o usar un objeto TracerProvider personalizado. Para obtener información general sobre la instrumentación de aplicaciones, consulta Instrumentación y observabilidad.

Antes de comenzar

Habilita la API de Cloud Trace si aún no está habilitada.

Roles necesarios para habilitar las APIs

Para habilitar APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

Habilitar la API

Instala los paquetes de OpenTelemetry

Configura la exportación de intervalos a Cloud Trace

Para configurar la exportación de datos de seguimiento, llama a la función google::cloud::otel::ConfigureBasicTracing(...) en tu función 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 Google Cloud en el que deseas almacenar los registros.

La función ConfigureBasicTracing(...) crea una instancia de un objeto TracerProvider que implementa un exportador de Cloud Trace. Si el objeto que devuelve la llamada a ConfigureBasicTracing(...) queda fuera del alcance, se restablece el objeto TracerProvider anterior, si existe.

Configura la frecuencia de muestreo

Las aplicaciones pueden generar un gran volumen de datos de seguimiento. En el siguiente ejemplo, se ilustra 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();
}

Exporta a Cloud Trace con un TracerProvider personalizado

Es posible que tengas casos de uso que requieran un objeto TracerProvider personalizado. Por ejemplo, si deseas 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>());
}

Instrumenta tu propia aplicación

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

  • Crear un intervalo
  • Crear intervalos anidados
  • Establecer atributos de intervalo
  • Crear intervalos con eventos
  • Crear intervalos con vínculos
// 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.

Configura tu plataforma

Puedes usar Cloud Trace en Google Cloud y otras plataformas.

Se ejecuta en Google Cloud

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

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

Para las siguientes opciones de configuración, la configuración predeterminada del permiso de acceso habilita la API de Cloud Trace:

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

  • Si deseas obtener información para configurar los permisos de acceso para tu entorno con la consola de Google Cloud , consulta Configura tu proyecto de Google Cloud .

  • Para los usuarios de gcloud, especifica los niveles de acceso con la marca --scopes y, también, incluye el permiso de acceso a la API de Cloud Trace trace.append. Por ejemplo, para crear un clúster de GKE solo con la API de Cloud Trace habilitada, sigue estos pasos:

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

Ejecuta de forma local y en otros lugares

Si tu aplicación se ejecuta fuera de Google Cloud, debes proporcionar credenciales de autenticación en forma de una cuenta de servicio a la biblioteca cliente. La cuenta de servicio debe contener el rol de agente de Cloud Trace. Para obtener instrucciones, consulta Crea una cuenta de servicio.

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

Puedes proporcionar estas credenciales de tres maneras:

  • Ejecuta gcloud auth application-default login

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

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

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

  • Configura la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ruta de acceso 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"

Ver seguimientos

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

Ve al Explorador de seguimiento

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

Soluciona problemas

Para obtener información sobre cómo solucionar problemas con Cloud Trace, ve a 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

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

Para obtener información sobre la versión, consulta lo siguiente:

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

En el caso de los repositorios de GitHub, consulta lo siguiente: