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:
- Mengubah data yang direkam dari format OTLP menjadi format eksklusif yang ditentukan oleh Cloud Logging API, Cloud Monitoring API, atau Cloud Trace API.
- 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.
Google Cloud CLI
Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:
gcloud services enable telemetry.googleapis.comlogging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com
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
)
-
Cloud Telemetry Traces Writer (
-
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 khusus atau peran bawaan lainnya.
-
Logs Viewer (
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:
- Konfigurasi header autentikasi untuk panggilan ekspor.
- Konfigurasi atribut resource OpenTelemetry dan header OTLP yang diperlukan.
- 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 kuncigcp.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.