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:
- Mengubah data yang dicatat dari format OTLP menjadi format eksklusif yang ditentukan oleh Cloud Logging API, Cloud Monitoring API, atau Cloud Trace API.
- 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:
- Konfigurasikan header autentikasi untuk panggilan ekspor.
- Konfigurasi atribut resource OpenTelemetry dan header OTLP yang diperlukan.
- 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 kuncigcp.project_id
di atribut resource OpenTelemetry. Tetapkan nilainya sebagai ID project Google Cloud Anda.OTEL_EXPORTER_OTLP_HEADERS
: Konfigurasikan variabel lingkungan ini untuk menambahkan headerx-goog-user-project
. Nilainya harus berupa ID project Google Cloud Anda tempat kuota layanan akan digunakan. Biasanya, nilai ditetapkan ke nilai yang sama dengan kuncigcp.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:
-
Telemetry Writer (
roles/telemetry.tracesWriter
) -
Logs Writer (
roles/logging.logWriter
) -
Monitoring Metric Writer (
roles/monitoring.metricWriter
)
-
Telemetry Writer (
-
Untuk mendapatkan izin yang Anda perlukan guna melihat data log, metrik, dan rekaman aktivitas, minta administrator 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 khusus atau peran bawaan lainnya.
-
Logs Viewer (
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.
Google Cloud CLI
Enable the Telemetry API, Cloud Logging, and Cloud Monitoring, and Cloud Trace APIs:
gcloud services enable telemetry.googleapis.comlogging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com