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.

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 Telemetry API

Pastikan Telemetry API, Cloud Logging API, Cloud Monitoring API, dan Cloud Trace API diaktifkan untuk project Anda. Telemetry API dinonaktifkan secara default.

Google Cloud console

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

Enable the APIs

Google Cloud CLI

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

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

Konfigurasikan izin

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 eksportir 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 dan header OTLP yang diperlukan

Tetapkan variabel lingkungan OpenTelemetry berikut:

  • OTEL_RESOURCE_ATTRIBUTES: Konfigurasi variabel lingkungan ini untuk menetapkan kunci gcp.project_id dalam atribut resource OpenTelemetry. Nilai yang ditetapkan harus berupa 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.

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.