Bermigrasi dari Eksporter trace ke endpoint OTLP

Dokumen ini menjelaskan cara memigrasikan aplikasi yang dilengkapi dengan instrumentasi OpenTelemetry dan mengandalkan eksportir Google Cloud , untuk menggunakan eksportir OTLP OpenTelemetry. Kedua konfigurasi tersebut mengirimkan telemetri ke project Google Cloud Anda. Langkah-langkah dalam dokumen ini ditujukan 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

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

  1. Mengubah data yang dicatat dari format OTLP menjadi format eksklusif yang ditentukan oleh Cloud Logging API, Cloud Monitoring API, atau Cloud Trace API.
  2. Mengirim data yang 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 guna 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.

Panduan migrasi untuk instrumentasi manual

Bagian ini menjelaskan cara mengubah aplikasi agar mengirimkan data rekaman aktivitas ke project Google Cloud menggunakan Telemetry API. 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 update 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 eksportir OTLP OpenTelemetry, bukan pengekspor trace Google Cloud . Perubahan yang diperlukan bersifat spesifik per 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 ekspor untuk mengirim rekaman aktivitas tersebut ke project Google Cloud Anda.

Untuk mengonfigurasi autentikasi, lakukan hal berikut:

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

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 mengautentikasi ke Trace, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca 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 mengautentikasi ke Trace, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca 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 mengautentikasi ke Trace, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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

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

Java

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

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(() -> {
                try {
                    credentials.refreshIfExpired();
                } catch (IOException e) {
                    // Handle authentication error
                    throw new RuntimeException(e);
                }
                return Map.of("Authorization", "Bearer " + credentials.getAccessToken().getTokenValue());
            })
            .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 dan header OTLP yang diperlukan

Tetapkan variabel lingkungan OpenTelemetry berikut:

  • OTEL_RESOURCE_ATTRIBUTES: Konfigurasikan variabel lingkungan ini untuk menetapkan kunci gcp.project_id di atribut resource OpenTelemetry. Tetapkan nilainya sebagai ID project Google Cloud Anda.

  • OTEL_EXPORTER_OTLP_HEADERS: Konfigurasikan variabel lingkungan ini untuk menambahkan header x-goog-user-project. Nilainya harus berupa ID project Google Cloud Anda tempat kuota layanan akan digunakan. Biasanya, nilai ditetapkan ke nilai yang sama dengan kunci gcp.project_id.

Contoh:

export OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=PROJECT_ID"
export OTEL_EXPORTER_OTLP_HEADERS="x-goog-user-project=QUOTA_PROJECT_ID"

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

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.

Izin yang diperlukan

Ada peran dan izin Identity and Access Management (IAM) yang memberi Anda, atau akun layanan, kemampuan untuk menulis data rekaman aktivitas ke Telemetry API dan menyimpan data tersebut di project Google Cloud Anda. Misalnya, jika Anda hanya diberi izin atau peran Cloud Trace, izin tersebut tidak akan memungkinkan Anda menulis data menggunakan Telemetry API.

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

Untuk informasi selengkapnya, lihat Cara kerja Kredensial Default Aplikasi dan Menyiapkan Kredensial Default Aplikasi (ADC) untuk lingkungan pengembangan lokal.

API yang diperlukan

Telemetry API dinonaktifkan secara default. Anda harus mengaktifkan API ini. Berikut ini informasi tentang API yang diperlukan untuk mengirim data telemetri ke project Google Cloud, dan untuk melihat data ini:

Konsol Google Cloud

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

Enable the APIs

Google Cloud CLI

Enable the Telemetry API, Cloud Logging, and Cloud Monitoring, and Cloud Trace APIs:

gcloud services enable telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com