Bermigrasi dari Eksporter trace ke endpoint OTLP

Dokumen ini menjelaskan cara memigrasikan aplikasi yang diinstrumentasikan dengan OpenTelemetry dan mengandalkan pengekspor Google Cloud , untuk menggunakan pengekspor OTLP OpenTelemetry. Kedua konfigurasi mengirimkan telemetri ke project Google Cloud Anda. Langkah-langkah dalam dokumen ini adalah untuk ekspor dalam proses yang dilakukan oleh OpenTelemetry SDK.

Dokumen ini menjelaskan cara mengekspor data rekaman aktivitas saat Anda menggunakan instrumentasi manual. Panduan ini, yang disediakan untuk Java, Go, dan Python, tidak berlaku untuk mengirim data log atau metrik ke project Google Cloud Anda.

Alasan Anda harus melakukan migrasi

SDK OpenTelemetry membuat data log, metrik, dan trace dalam format OTLP. Saat aplikasi mengekspor data tersebut ke projectGoogle Cloud menggunakan pengekspor Google Cloud , pengekspor tersebut akan melakukan langkah-langkah berikut:

1. Mengubah data yang direkam dari format OTLP menjadi format eksklusif yang ditentukan oleh Cloud Logging API, Cloud Monitoring API, atau Cloud Trace API.
2. Mengirim data yang telah diubah ke API yang sesuai, yang kemudian disimpan di project Google Cloud Anda.

Untuk data rekaman aktivitas, sebaiknya migrasikan aplikasi Anda untuk menggunakan Telemetry (OTLP) API untuk mengekspor data, karena ekspor ini tidak memerlukan transformasi data. Transformasi data dapat menyebabkan hilangnya beberapa data. Misalnya, format eksklusif mungkin memiliki batas yang lebih rendah untuk kolom tertentu, atau beberapa kolom OTLP mungkin tidak dipetakan ke kolom dalam format eksklusif.

Catatan: Telemetry API hanya menerima data rekaman aktivitas. Anda tidak dapat mengirim data log atau metrik ke project Google Cloud menggunakan endpoint ini.

Sebelum memulai

Sebelum memigrasikan aplikasi untuk mengirim data rekaman aktivitas ke endpoint OTLP, aktifkan Telemetry API dan pastikan Anda telah diberi peran Identity and Access Management (IAM) yang diperlukan. Anda mungkin juga perlu memberikan peran IAM ke akun layanan.

Mengaktifkan penagihan dan Telemetry API

Catatan: Telemetry API dinonaktifkan secara default.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

Konfigurasikan izin

• Untuk mendapatkan izin yang Anda perlukan agar aplikasi contoh dapat mengirim data log, metrik, dan rekaman aktivitas ke project Anda, minta administrator Anda untuk memberi Anda peran IAM berikut di project Anda:

  • Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)
  • Logs Writer (roles/logging.logWriter)
  • Monitoring Metric Writer (roles/monitoring.metricWriter)
  Catatan: Jika Anda mengonfigurasi aplikasi sehingga Kredensial Default Aplikasi (ADC) mengandalkan akun layanan, maka berikan peran IAM sebelumnya ke akun layanan tersebut. Untuk mengetahui informasi selengkapnya, lihat Cara kerja Kredensial Default Aplikasi dan Menyiapkan Kredensial Default Aplikasi (ADC) untuk lingkungan pengembangan lokal.

• Untuk mendapatkan izin yang Anda perlukan guna melihat data log, metrik, dan rekaman aktivitas, minta administrator Anda untuk memberi Anda peran IAM berikut di project Anda:

  • Logs Viewer (roles/logging.viewer)
  • Monitoring Viewer (roles/monitoring.viewer)
  • Cloud Trace User (roles/cloudtrace.user)

  Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

  Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran kustom atau peran yang telah ditentukan lainnya.

Panduan migrasi untuk instrumentasi manual

Bagian ini menjelaskan cara mengubah aplikasi Anda agar mengirimkan data rekaman aktivitas ke project Anda menggunakan Telemetry API. Google Cloud Anda tidak dapat mengirim data metrik atau log ke endpoint ini.

Menambahkan dependensi

Langkah pertama adalah menambahkan dependensi untuk pengekspor rekaman aktivitas OTLP OpenTelemetry di aplikasi Anda. Pilih versi dependensi yang sesuai untuk aplikasi dan sistem build Anda.

Java

Untuk aplikasi Java yang menggunakan sistem build Gradle:

// build.gradle
implementation("io.opentelemetry:opentelemetry-exporter-otlp:1.47.0")

Go

Untuk aplikasi Golang, pastikan file go.mod memiliki dependensi berikut:

// go.mod file
require(
  // OTLP exporter that uses grpc protocol for export
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.34.0
  // Alternatively, for export using http/protobuf protocol, use:
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.34.0
)

Python

Untuk aplikasi Python, instal dependensi berikut atau perbarui file requirements.txt:

# Requirements.txt - use appropriate versions
#
# OTLP exporter that uses grcp protocol for export
opentelemetry-exporter-otlp-proto-grpc==1.30.0
grpcio==1.70.0
# Alternatively, for export using http/protobuf protocol, use:
opentelemetry-exporter-otlp-proto-http==1.30.0

Mengganti penggunaan pengekspor Google Cloud dengan pengekspor OTLP

Perbarui kode aplikasi Anda sehingga OpenTelemetry SDK dikonfigurasi untuk menggunakan pengekspor OTLP OpenTelemetry, bukan pengekspor rekaman aktivitas Google Cloud . Perubahan yang diperlukan bergantung pada bahasa.

Java

import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
import io.opentelemetry.sdk.trace.export.SpanExporter;
import io.opentelemetry.sdk.trace.samplers.Sampler;

// Initialize OpenTelemetry SDK with OTLP exporters
public static OpenTelemetry initOpenTelemetry() {
    // Initialize the OTLP gRPC exporter
    SpanExporter otlpGrpcSpanExporter =
        OtlpGrpcSpanExporter.builder()
            .setTimeout(2, TimeUnit.SECONDS)
            .build();

    // Initialize OpenTelemetry tracer provider
    SdkTracerProvider tracerProvider = SdkTracerProvider.builder()
        .setResource(resource)
        .setSampler(Sampler.traceIdRatioBased(0.02))
        .addSpanProcessor(
            BatchSpanProcessor.builder(otlpGrpcSpanExporter)
                .setScheduleDelay(100, TimeUnit.MILLISECONDS)
                .build());

    // Configure OpenTelemetry SDK instacne to use the tracer provider
    // configured with OTLP exporter
    OpenTelemetrySdk openTelemetrySdk =
        OpenTelemetrySdk.builder()
            .setTracerProvider(tracerProvider)
            .build();
}

Go

import (
    "context"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    // other dependencies
)

// Initializes OpenTelemetry with OTLP exporters
func init() {
    ctx := context.Background()

    // Initialize the OTLP gRPC exporter
    exporter, err := otlptracegrpc.New(ctx)
    if err != nil {
        panic(err)
    }
    // initialize OpenTelemetry tracer provdier
    tp := sdktrace.NewTracerProvider(
        sdktrace.WithSampler(sdktrace.TraceIDRatioBased(0.02)),
        sdktrace.WithBatcher(exporter)
    )

    // configure OpenTelemetry SDK instance to use the tracer provider
    // configured with OTLP exporter
    otel.SetTracerProvider(tp)
}

Python

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
    OTLPSpanExporter,
)
from opentelemetry.sdk.resources import SERVICE_NAME, Resource

# Initialize OpenTelemetry with OTLP exporters
def init():
    # Initialize the OTLP gRPC or http exporter
    otlp_grpc_exporter = OTLPSpanExporter()

    # Initialize OpenTelemetry TracerProvider
    trace_provider = TracerProvider(resource=resource).add_span_processor(
    BatchSpanProcessor(otlp_grpc_exporter)
    )

    # Configure OpenTelemetry tracing API with the initialized tracer provider
    trace.set_tracer_provider(trace_provider)

Mengonfigurasi autentikasi

Dengan perubahan sebelumnya pada konfigurasi OpenTelemetry SDK, aplikasi Anda dikonfigurasi untuk mengekspor rekaman aktivitas menggunakan eksportir OTLP OpenTelemetry menggunakan gRPC atau HTTP. Selanjutnya, Anda perlu mengonfigurasi pengekspor untuk mengirim rekaman aktivitas tersebut ke project Google Cloud Anda.

Untuk mengonfigurasi autentikasi, lakukan hal berikut:

1. Konfigurasi header autentikasi untuk panggilan ekspor.
2. Konfigurasi atribut resource OpenTelemetry dan header OTLP yang diperlukan.
3. Konfigurasi endpoint pengekspor.

Bagian ini menjelaskan setiap langkah tersebut.

Mengonfigurasi header autentikasi untuk panggilan ekspor

Untuk mengonfigurasi eksportir dengan Google Cloud Kredensial Default Aplikasi (ADC), tambahkan Google Auth Library khusus bahasa.

Java

Untuk melakukan autentikasi ke Google Cloud Observability, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

// build.gradle
// Google Auth Library
implementation("com.google.auth:google-auth-library-oauth2-http:1.32.1")

Go

Untuk melakukan autentikasi ke Google Cloud Observability, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

// go.mod file
require (
    // When using gRPC based OTLP exporter, auth is built-in
    google.golang.org/grpc v1.70.0
    // When using http based OTLP exported, use explicit auth library
    golang.org/x/oauth2 v0.26.0
)

Python

Untuk melakukan autentikasi ke Google Cloud Observability, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

# requirements.txt
# Google Auth Library
google-auth==2.38.0

Selanjutnya, perbarui kode aplikasi yang membuat eksportir rentang OTLP sehingga menambahkan token otorisasi yang diambil dari library ke header. Langkah ini khusus untuk bahasa tertentu, tetapi implementasinya serupa untuk semua bahasa.

Java

Sebaiknya gunakan Ekstensi Autentikasi Google Cloud saat Anda menggunakan modul Autoconfigure SDK OpenTelemetry. Untuk contoh lengkap yang menggunakan ekstensi ini, lihat Contoh OTLP Trace dengan Google Auth.

import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
import io.opentelemetry.sdk.trace.export.SpanExporter;
import io.opentelemetry.sdk.trace.samplers.Sampler;

import com.google.auth.oauth2.GoogleCredentials;

// Initialize OpenTelemetry SDK with OTLP exporters
public static OpenTelemetry initOpenTelemetry() {
    // Retrieve and store application-default credentials
    GoogleCredentials credentials;
    try {
       credentials = GoogleCredentials.getApplicationDefault();
    } catch (IOException e) {
      // Handle authentication error
      throw new RuntimeException(e);
    }

    // Update gRPC span exporter to add the authorization headers
    // If you are using the Autoconfigure module, we recommend using
    // Google Cloud Authentication Extension.
    // See https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/gcp-auth-extension
    SpanExporter otlpGrpcSpanExporter =
        OtlpGrpcSpanExporter.builder()
            .setHeaders(
                () -> {
                  Map<String, List<String>> gcpHeaders;
                  try {
                    credentials.refreshIfExpired();
                    gcpHeaders = credentials.getRequestMetadata();
                  } catch (IOException e) {
                    // Handle authentication error
                    throw new RuntimeException(e);
                  }
                  Map<String, String> flattenedHeaders =
                      gcpHeaders.entrySet().stream()
                          .collect(
                              Collectors.toMap(
                                  Map.Entry::getKey,
                                  entry ->
                                      entry.getValue().stream()
                                          .filter(Objects::nonNull)
                                          .filter(s -> !s.isEmpty())
                                          .collect(Collectors.joining(",")),
                                  (v1, v2) -> v2));
                  return flattenedHeaders;
                })
            .setTimeout(2, TimeUnit.SECONDS)
            .build();

  // Other OpenTelemetry configuration remains unaffected
}

Go

import (
    "context"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/oauth"
)

// Initializes OpenTelemetry with OTLP exporters
func init() {
    ctx := context.Background()

    // Retrieve and store Google application-default credentials
    creds, err := oauth.NewApplicationDefault(ctx)
    if err != nil {
        panic(err)
    }

    // Update the previously created OTLP gRPC span exporter to
    // add authorization headers
    exporter, err := otlptracegrpc.New(
        ctx,
        otlptracegrpc.WithDialOption(grpc.WithPerRPCCredentials(creds))
    )

    // Other OpenTelemetry configuration remains unaffected.
}

Python

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
    OTLPSpanExporter,
)
from opentelemetry.sdk.resources import SERVICE_NAME, Resource

import google.auth
import google.auth.transport.grpc
import google.auth.transport.requests
import grpc
from google.auth.transport.grpc import AuthMetadataPlugin

# Initialize OpenTelemetry with OTLP exporters
def init():
    # Retrieve and store Google application-default credentials
    credentials, project_id = google.auth.default()
    # Request used to refresh credentials upon expiry
    request = google.auth.transport.requests.Request()

    # Supply the request and credentials to AuthMetadataPlugin
    # AuthMeatadataPlugin inserts credentials into each request
    auth_metadata_plugin = AuthMetadataPlugin(
        credentials=credentials, request=request
    )

    # Initialize gRPC channel credentials using the AuthMetadataPlugin
    channel_creds = grpc.composite_channel_credentials(
        grpc.ssl_channel_credentials(),
        grpc.metadata_call_credentials(auth_metadata_plugin),
    )

    # Update the previously created OTLP gRPC span exporter to add authorization
    # credentials
    otlp_grpc_exporter = OTLPSpanExporter(credentials=channel_creds)

    # Other OpenTelementry configuration remains unaffected

Mengonfigurasi atribut resource OpenTelemetry yang diperlukan

Tambahkan pasangan nilai kunci yang menentukan project Anda ke variabel lingkungan OTEL_RESOURCE_ATTRIBUTES. Untuk kunci, gunakan gcp.project_id. Untuk nilai, gunakan ID project Google Cloud Anda.

Contoh:

export OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=PROJECT_ID"

Untuk mengetahui informasi selengkapnya tentang variabel lingkungan OpenTelemetry, lihat Konfigurasi SDK Umum.

Menetapkan ID project kuota

Project kuota adalah Google Cloud project yang melacak penggunaan permintaan API Anda. Karena Telemetry API adalah API berbasis klien, cara Anda melakukan autentikasi akan menentukan apakah project kuota diidentifikasi secara otomatis. Misalnya, Anda tidak perlu menentukan project kuota saat menggunakan akun layanan untuk autentikasi. Namun, Anda perlu menentukan project kuota saat kredensial pengguna digunakan untuk autentikasi.

Anda dapat menetapkan project kuota menggunakan variabel lingkungan. Untuk menentukan variabel lingkungan mana yang akan ditetapkan untuk bahasa pemrograman Anda, lihat Menetapkan project kuota menggunakan variabel lingkungan.

Misalnya, untuk Go, Anda dapat menetapkan project kuota sebagai berikut:

export GOOGLE_CLOUD_QUOTA_PROJECT="QUOTA_PROJECT_ID"

Untuk mengetahui informasi tentang cara mengatasi error autentikasi, lihat Kredensial pengguna tidak berfungsi.

Catatan: Jangan perbarui variabel lingkungan OTEL_EXPORTER_OTLP_HEADERS dengan pasangan nilai kunci yang menggunakan kunci x-goog-user-project. Konfigurasi ini dapat menghasilkan nilai duplikat dalam permintaan, dan hal itu menyebabkan perintah API gagal.

Mengonfigurasi endpoint pengekspor

Tetapkan nilai variabel lingkungan OTEL_EXPORTER_OTLP_ENDPOINT ke endpoint OTLP untuk Google Cloud.

Contoh:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://telemetry.googleapis.com

Untuk mengetahui informasi selengkapnya tentang variabel lingkungan OpenTelemetry, lihat Konfigurasi SDK Umum.