C++ 및 OpenTelemetry

이 페이지는 OpenTelemetry를 사용하여 C++ 애플리케이션용 Cloud Trace 데이터를 수집하려는 애플리케이션 개발자를 위해 설계되었습니다. OpenTelemetry는 trace 및 측정항목 데이터를 수집하는 데 사용할 수 있는 공급업체 중립적인 계측 프레임워크입니다. 코드를 계측하는 방법은 계측 및 관측 가능성을 참조하세요.

이 페이지에서는 다음 단계를 안내합니다.

  • OpenTelemetry 패키지를 설치합니다.
  • Cloud Trace로 스팬을 내보내도록 애플리케이션을 구성합니다.
  • 플랫폼을 구성합니다.

출시 정보는 다음을 참조하세요.

OpenTelemetry 참조 콘텐츠는 다음을 확인하세요.

C++용 OpenTelemetry에 대한 최신 세부정보 및 추가 문서와 예시는 OpenTelemetry를 참조하세요.

시작하기 전에

Enable the Cloud Trace API.

Enable the API

OpenTelemetry 패키지 설치

Cloud Trace로 스팬 내보내기 구성

Trace 데이터 내보내기를 구성하려면 main() 메서드에서 google::cloud::otel::ConfigureBasicTracing(...) 메서드를 호출합니다.

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

  MyApplicationCode();
}

project_id 필드는 Trace를 저장할 Google Cloud 프로젝트입니다.

ConfigureBasicTracing(...) 메서드는 Cloud Trace 내보내기 도구를 구현하는 TracerProvider 객체를 인스턴스화합니다. ConfigureBasicTracing(...) 호출에서 반환된 객체가 범위를 벗어나면 이전 TracerProvider 객체가 있는 경우 복구됩니다.

샘플링 레이트 구성

애플리케이션은 대량의 Trace 데이터를 생성할 수 있습니다. 다음 샘플은 샘플링 레이트를 구성하는 방법을 보여줍니다.

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

커스텀 TracerProvider를 사용하여 Cloud Trace로 내보내기

사용 사례에 따라서는 커스텀 TracerProvider 객체가 필요할 수 있습니다. 예를 들어 여러 내보내기 도구를 동시에 사용하려면 커스텀 TracerProvider 객체를 만들어야 합니다. 이러한 경우 Cloud Trace 내보내기 도구를 직접 사용할 수 있습니다.

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

자체 애플리케이션 계측

trace 스팬 캡처를 위해 애플리케이션을 구성하는 방법은 OpenTelemetry Trace를 참조하세요. 이 페이지에서는 다음 모든 작업의 수행 방법을 설명합니다.

  • 스팬 만들기
  • 중첩 스팬 만들기
  • 스팬 속성 설정
  • 이벤트로 스팬 만들기
  • 링크로 스팬 만들기
// 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();
}

샘플 애플리케이션

샘플 애플리케이션은 빠른 시작을 참조하세요.

플랫폼 구성

Google Cloud 및 기타 플랫폼에서 Cloud Trace를 사용할 수 있습니다.

Google Cloud에서 실행

애플리케이션이 Google Cloud에서 실행되는 경우 클라이언트 라이브러리에 서비스 계정 형식으로 사용자 인증 정보를 제공할 필요가 없습니다. 하지만 Google Cloud Platform에 Cloud Trace API 액세스 범위가 사용 설정되어 있는지 확인해야 합니다.

지원되는 Google Cloud 환경 목록은 환경 지원을 참조하세요.

다음 구성에서는 기본 액세스 범위 설정이 Cloud Trace API를 사용 설정합니다.

커스텀 액세스 범위를 사용하는 경우 Cloud Trace API 액세스 범위가 사용 설정되어 있는지 확인해야 합니다.

  • Google Cloud 콘솔을 사용하여 환경의 액세스 범위를 구성하는 방법에 대한 자세한 내용은 Google Cloud 프로젝트 구성을 참조하세요.

  • gcloud 사용자의 경우 --scopes 플래그를 사용하여 액세스 범위를 지정하고 trace.append Cloud Trace API 액세스 범위를 포함합니다. 예를 들어 Cloud Trace API만 사용 설정된 GKE 클러스터를 만들려면 다음을 수행합니다.

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

로컬 및 기타 위치에서 실행

애플리케이션이 Google Cloud 외부에서 실행되는 경우 클라이언트 라이브러리에 사용자 인증 정보를 서비스 계정 형식으로 제공해야 합니다. 서비스 계정에는 Cloud Trace 에이전트 역할이 포함되어야 합니다. 자세한 내용은 서비스 계정 만들기를 참조하세요.

Google Cloud 클라이언트 라이브러리는 애플리케이션 기본 사용자 인증 정보(ADC)를 사용하여 애플리케이션의 사용자 인증 정보를 찾습니다.

세 가지 방법 중 하나로 이러한 사용자 인증 정보를 제공할 수 있습니다.

  • gcloud auth application-default login 실행

  • 운영체제의 기본 경로에 서비스 계정을 배치합니다. 다음은 Windows 및 Linux의 기본 경로를 보여줍니다.

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

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

  • GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 서비스 계정 경로로 설정합니다.

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"

trace 보기

Google Cloud 콘솔에서 Trace 탐색기 페이지로 이동합니다.

Trace 탐색기로 이동

검색창을 사용하여 이 페이지를 찾을 수도 있습니다.

문제 해결

Cloud Trace 문제 해결에 대한 자세한 내용은 문제 해결 페이지를 참조하세요.

C++ Cloud Trace 내보내기 도구를 디버깅하려면 참조 문서의 문제 해결 섹션을 참조하세요.

리소스