Bermigrasi dari Eksporter trace ke endpoint OTLP

Anda dapat memigrasikan aplikasi Java, Go, Python, dan Node.js yang diinstrumentasikan secara manual dari pengekspor trace Google Cloud ke pengekspor OTLP OpenTelemetry dalam proses. Pengekspor OTLP mengirimkan data trace langsung ke Telemetry (OTLP) API di project Google Cloud Anda menggunakan protokol ekspor yang didukung (gRPC atau http/protobuf).

Konfigurasi ini hanya mengekspor data trace dan hanya berlaku untuk pengekspor dalam proses. Jika aplikasi Anda menggunakan kolektor OpenTelemetry, lihat Contoh instrumentasi berbasis kolektor dan Kolektor OpenTelemetry Buatan Google.

Alasan Anda harus bermigrasi

OpenTelemetry SDK menghasilkan data log, metrik, dan trace dalam format yang umumnya konsisten dengan file proto yang ditentukan oleh Protokol OpenTelemetry. Namun, kolom dapat dikonversi dari jenis data khusus OpenTelemetry ke jenis data JSON sebelum penyimpanan.

Saat aplikasi mengekspor data tersebut ke project Google 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 trace, sebaiknya migrasikan aplikasi Anda agar 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.

Sampel yang tersedia

Aplikasi contoh yang dirujuk di halaman ini tersedia di GitHub. Sebagian besar aplikasi dikonfigurasi untuk mengekspor data trace menggunakan gRPC, yang berarti aplikasi tersebut mengirim data yang dienkode protobuf dalam format wire gRPC melalui koneksi HTTP/2. Kode contoh juga disediakan untuk aplikasi yang dikonfigurasi untuk mengekspor data trace sebagai data berenkode protobuf melalui koneksi HTTP:

  • Aplikasi Java

    Aplikasi contoh dikonfigurasi untuk mengekspor trace sebagai data berenkode protobuf melalui koneksi HTTP. Jika Anda lebih suka menggunakan gRPC, instrumentasi dalam contoh ini dapat diterapkan. Namun, Anda perlu mengubah properti sistem yang digunakan modul konfigurasi otomatis. Aplikasi contoh menentukan pengekspor http/protobuf. Untuk menggunakan gRPC, ubah setelan ini menjadi grpc.

    Sebaiknya aplikasi Java Anda, seperti aplikasi contoh, menggunakan modul Konfigurasi Otomatis OpenTelemetry SDK untuk mengonfigurasi SDK.

  • Aplikasi Go yang menggunakan gRPC dan Aplikasi Go yang menggunakan HTTP

    Ada dua repositori Go. Dalam satu repositori, aplikasi contoh menggunakan gRPC. Contoh di repositori lain menggunakan data yang dienkode protobuf melalui koneksi HTTP.

  • Repositori Python

    Repositori ini berisi dua contoh, satu untuk gRPC dan satu lagi yang menggunakan data berenkode protobuf melalui koneksi HTTP.

  • Aplikasi Node.js

    Repositori ini berisi dua contoh, satu untuk gRPC dan satu lagi yang menggunakan data berenkode protobuf melalui koneksi HTTP.

Sebelum memulai

Sebelum memigrasikan aplikasi untuk mengirim data trace 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

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

Konfigurasikan izin

Panduan migrasi untuk instrumentasi manual

Bagian ini menjelaskan cara mengubah aplikasi agar mengirimkan data trace ke project Google Cloud menggunakan Telemetry API.

Menambahkan dependensi

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

Java

Untuk aplikasi Java, tambahkan dependensi berikut dalam skrip build.gradle Anda:

implementation("io.opentelemetry:opentelemetry-exporter-otlp:1.62.0")
implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure:1.62.0")

Go

Bagian ini mengilustrasikan perubahan yang perlu Anda lakukan pada dependensi saat menggunakan gRPC untuk ekspor. Jika Anda menggunakan data berenkode protobuf melalui koneksi HTTP untuk ekspor, sertakan paket otlptracehttp sebagai dependensi. Untuk informasi selengkapnya, lihat Aplikasi Go yang menggunakan HTTP.

Untuk aplikasi Go yang menggunakan gRPC untuk ekspor, perbarui file go.mod agar menyertakan dependensi berikut:

require (
	// ...
	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.44.0
)

Python

Bagian ini mengilustrasikan perubahan yang perlu Anda lakukan pada dependensi saat menggunakan gRPC untuk ekspor. Jika Anda menggunakan data berenkode protobuf melalui koneksi HTTP untuk ekspor, sertakan paket opentelemetry-exporter-otlp-proto-http sebagai persyaratan. Untuk mengetahui informasi selengkapnya, lihat repositori Python.

Untuk aplikasi Python yang menggunakan gRPC untuk ekspor, instal dependensi berikut atau update file requirements.txt:

opentelemetry-exporter-otlp-proto-grpc==1.42.1
grpcio==1.80.0

Node.js

Bagian ini mengilustrasikan perubahan yang perlu Anda lakukan pada dependensi saat menggunakan gRPC untuk ekspor. Jika Anda menggunakan data berenkode protobuf melalui koneksi HTTP untuk ekspor, sertakan paket @opentelemetry/exporter-trace-otlp-proto sebagai dependensi. Untuk mengetahui informasi selengkapnya, lihat Aplikasi Node.js.

Untuk aplikasi Node.js yang mengekspor data trace menggunakan gRPC, tambahkan dependensi berikut:

"@opentelemetry/exporter-trace-otlp-grpc": "0.221.0",
"@grpc/grpc-js": "1.14.4"

Mengganti penggunaan pengekspor Google Cloud dengan pengekspor OTLP

Perbarui kode aplikasi Anda sehingga SDK OpenTelemetry dikonfigurasi untuk menggunakan pengekspor OTLP OpenTelemetry, bukan pengekspor trace Google Cloud . Perubahan yang diperlukan bersifat spesifik per bahasa.

Java

Untuk aplikasi Java, lakukan hal berikut:

  1. Tambahkan pernyataan impor berikut:

    import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;

  2. Update kode aplikasi untuk menggunakan modul Konfigurasi Otomatis SDK OpenTelemetry guna mengonfigurasi SDK:

    public static void main(String[] args) {
  // Configure the OpenTelemetry pipeline with Auto configuration
  openTelemetrySdk = AutoConfiguredOpenTelemetrySdk.initialize().getOpenTelemetrySdk();

  // ...
}

  3. Konfigurasikan properti sistem yang digunakan modul autoconfigure saat runtime. Modul tersebut menggunakan properti tersebut untuk melakukan bootstrap SDK. Anda juga dapat menggunakan variabel lingkungan, bukan properti sistem. Untuk mengetahui informasi selengkapnya, lihat Variabel lingkungan dan properti sistem.

    Aplikasi contoh menentukan properti sistem dalam skrip build.gradle:

    // You can switch the desired protocol here by changing `otel.exporter.otlp.protocol`.
def autoconf_config = [
	'-Dotel.exporter.otlp.endpoint=https://telemetry.googleapis.com',
	'-Dotel.traces.exporter=otlp',
	'-Dotel.logs.exporter=none',
	'-Dotel.metrics.exporter=none',
	'-Dotel.service.name=otlptrace-example',
	'-Dotel.exporter.otlp.protocol=http/protobuf',
	'-Dotel.java.global-autoconfigure.enabled=true',
]

    Selain itu, teruskan konfigurasi sebagai argumen JVM:

    application {
	mainClassName = 'com.google.cloud.opentelemetry.samples.otlptrace.OTLPTraceExample'
	// Pass the config as JVM arguments to the Java application
	applicationDefaultJvmArgs = autoconf_config
}

    Jika Anda lebih suka mengekspor data trace menggunakan gRPC, tetapkan protokol OTLP ke grpc, bukan http/protobuf.

Go

Bagian ini mengilustrasikan perubahan yang perlu Anda lakukan saat menggunakan gRPC untuk ekspor. Jika Anda menggunakan data berenkode protobuf melalui koneksi HTTP untuk ekspor, Anda harus mengimpor paket otlptracehttp dan juga mengonfigurasi pengekspor dengan opsi yang sesuai. Untuk mengetahui informasi selengkapnya, lihat Aplikasi Go yang menggunakan HTTP.

Untuk aplikasi Go yang menggunakan gRPC untuk ekspor, tambahkan pernyataan impor berikut:

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

	// ...
)

Selain itu, perbarui kode inisialisasi untuk mengonfigurasi TraceProvider dengan pengekspor gRPC:

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

// Configure gRPC client with Google Application Default Credentials
creds, err := oauth.NewApplicationDefault(ctx)
if err != nil {
	panic(err)
}

// set OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=<project_id>"
// set endpoint with OTEL_EXPORTER_OTLP_ENDPOINT=https://<endpoint>
// set OTEL_EXPORTER_OTLP_HEADERS="x-goog-user-project=<project_id>"
// Configure exporter to use the credentials
exporter, err := otlptracegrpc.New(ctx, otlptracegrpc.WithDialOption(grpc.WithPerRPCCredentials(creds)))
if err != nil {
	panic(err)
}

tp := sdktrace.NewTracerProvider(
	// For this example code we use sdktrace.AlwaysSample sampler to sample all traces.
	// In a production application, use sdktrace.TraceIDRatioBased with a desired probability.
	sdktrace.WithSampler(sdktrace.AlwaysSample()),
	sdktrace.WithBatcher(exporter))

otel.SetTracerProvider(tp)

Python

Bagian ini mengilustrasikan perubahan yang perlu Anda lakukan saat menggunakan gRPC untuk ekspor. Jika Anda menggunakan data yang dienkode protobuf melalui koneksi HTTP untuk ekspor, Anda harus mengimpor dari paket opentelemetry.exporter.otlp.proto.http dan juga mengonfigurasi pengekspor dengan opsi yang sesuai. Untuk mengetahui informasi selengkapnya, lihat repositori Python.

Untuk aplikasi Python yang menggunakan gRPC untuk ekspor, tambahkan impor berikut:

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
    OTLPSpanExporter,
)

Selain itu, perbarui kode inisialisasi untuk mengonfigurasi TraceProvider dengan pengekspor gRPC:

# Initialize OpenTelemetry with OTLP exporters
# channel_creds: configure Application Default Credentials
trace_provider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(
    OTLPSpanExporter(
        credentials=channel_creds,
        endpoint="https://telemetry.googleapis.com:443/v1/traces",
    )
)
trace_provider.add_span_processor(processor)
trace.set_tracer_provider(trace_provider)
tracer = trace.get_tracer("my.tracer.name")

Node.js

Bagian ini mengilustrasikan perubahan yang perlu Anda lakukan saat menggunakan gRPC untuk ekspor. Jika Anda menggunakan data berenkode protobuf melalui koneksi HTTP untuk ekspor, impor paket @opentelemetry/exporter-trace-otlp-proto. Untuk mengetahui informasi selengkapnya, lihat Aplikasi Node.js.

Untuk aplikasi Node.js yang menggunakan gRPC untuk ekspor, tambahkan impor berikut:

import {OTLPTraceExporter} from '@opentelemetry/exporter-trace-otlp-grpc';

Selain itu, perbarui kode inisialisasi untuk mengonfigurasi TraceProvider dengan pengekspor gRPC:

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    credentials: credentials.combineChannelCredentials(
      credentials.createSsl(),
      credentials.createFromGoogleCredential({
        async getRequestHeaders(
          url?: string,
        ): Promise<{[index: string]: string}> {
          const rawHeaders = await authenticatedClient.getRequestHeaders(url);
          return Object.fromEntries(rawHeaders.entries());
        },
      }),
    ),
  }),
});
sdk.start();

Mengonfigurasi autentikasi

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

Untuk mengonfigurasi autentikasi, lakukan hal berikut:

  1. Konfigurasikan header autentikasi untuk panggilan ekspor.
  2. Konfigurasikan 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 pengekspor dengan Google Cloud Kredensial Default Aplikasi (ADC) Anda, tambahkan Library Auth Google khusus bahasa.

Java

Untuk aplikasi Java yang menggunakan modul Konfigurasi Otomatis OpenTelemetry SDK, sebaiknya Anda juga menggunakan Ekstensi Autentikasi Google Cloud.

implementation("io.opentelemetry.contrib:opentelemetry-gcp-auth-extension:1.56.0-alpha")

Go

Untuk aplikasi Go yang menggunakan gRPC untuk ekspor, perbarui file go.mod agar menyertakan dependensi berikut:

// When using gRPC based OTLP exporter, the auth is built in.
google.golang.org/grpc v1.82.1

Untuk aplikasi Go yang menggunakan HTTP untuk ekspor, update file go.mod untuk menyertakan dependensi berikut:

// When using http based OTLP exporter, use explicit auth library
golang.org/x/oauth2 v0.36.0

Python

Untuk aplikasi Python, tambahkan dependensi berikut ke file requirements.txt Anda:

# Google Auth Library
google-auth==2.53.0

Node.js

Untuk aplikasi Node.js, tambahkan dependensi berikut:

"google-auth-library": "10.5.0"

Selanjutnya, perbarui kode aplikasi yang membuat pengekspor span OTLP sehingga menambahkan token otorisasi yang diambil dari library ke header. Langkah ini bersifat spesifik per bahasa, tetapi penerapannya serupa untuk semua bahasa.

Java

Jika Anda memiliki aplikasi Java yang menggunakan modul Konfigurasi Otomatis OpenTelemetry SDK dan Ekstensi Autentikasi Google Cloud, Anda tidak perlu melakukan langkah khusus apa pun selama inisialisasi aplikasi. Modul konfigurasi otomatis akan otomatis melakukan langkah-langkah yang diperlukan untuk mengonfigurasi ADC.

Go

Bagian ini mengilustrasikan perubahan yang perlu Anda lakukan saat menggunakan gRPC untuk ekspor. Jika Anda menggunakan data berenkode protobuf melalui koneksi HTTP untuk ekspor, Anda harus mengimpor paket otlptracehttp dan mengonfigurasi pengekspor menjadi objek otlptracehttp. Untuk mengetahui informasi selengkapnya, lihat Aplikasi Go yang menggunakan HTTP.

Untuk aplikasi Go yang menggunakan gRPC untuk ekspor, tambahkan pernyataan impor berikut:

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

Selain itu, perbarui kode inisialisasi untuk mengonfigurasi ADC sebelum Anda membuat instance pengekspor gRPC:

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

// Configure gRPC client with Google Application Default Credentials
creds, err := oauth.NewApplicationDefault(ctx)
if err != nil {
	panic(err)
}

// set OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=<project_id>"
// set endpoint with OTEL_EXPORTER_OTLP_ENDPOINT=https://<endpoint>
// set OTEL_EXPORTER_OTLP_HEADERS="x-goog-user-project=<project_id>"
// Configure exporter to use the credentials
exporter, err := otlptracegrpc.New(ctx, otlptracegrpc.WithDialOption(grpc.WithPerRPCCredentials(creds)))
if err != nil {
	panic(err)
}

tp := sdktrace.NewTracerProvider(
	// For this example code we use sdktrace.AlwaysSample sampler to sample all traces.
	// In a production application, use sdktrace.TraceIDRatioBased with a desired probability.
	sdktrace.WithSampler(sdktrace.AlwaysSample()),
	sdktrace.WithBatcher(exporter))

otel.SetTracerProvider(tp)

Python

Bagian ini mengilustrasikan perubahan yang perlu Anda lakukan saat menggunakan gRPC untuk ekspor. Jika Anda menggunakan data berenkode protobuf melalui koneksi HTTP untuk ekspor, gunakan kredensial default. Anda juga harus meneruskan kredensial ini saat membuat instance BatchSpanProcessor. Untuk mengetahui informasi selengkapnya, lihat repositori Python.

Untuk aplikasi Python yang menggunakan gRPC untuk ekspor, tambahkan impor berikut:

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

Selain itu, perbarui kode inisialisasi untuk mengonfigurasi ADC sebelum Anda membuat instance pengekspor gRPC:

credentials, _ = google.auth.default()
request = google.auth.transport.requests.Request()
resource = Resource.create(attributes={SERVICE_NAME: "otlp-gcp-grpc-sample"})

auth_metadata_plugin = AuthMetadataPlugin(credentials=credentials, request=request)
channel_creds = grpc.composite_channel_credentials(
    grpc.ssl_channel_credentials(),
    grpc.metadata_call_credentials(auth_metadata_plugin),
)

Node.js

Bagian ini mengilustrasikan perubahan yang perlu Anda lakukan saat menggunakan gRPC untuk ekspor. Jika Anda menggunakan data berenkode protobuf melalui koneksi HTTP untuk ekspor, perubahan yang perlu Anda lakukan sedikit berbeda dari yang dijelaskan di sini. Untuk mempelajari lebih lanjut, lihat file app-http-proto-export.ts yang disertakan dalam aplikasi Node.js.

Untuk aplikasi Node.js yang menggunakan gRPC untuk ekspor, tambahkan impor berikut:

import {AuthClient, GoogleAuth} from 'google-auth-library';
import {credentials} from '@grpc/grpc-js';

Selain itu, perbarui kode inisialisasi untuk mengonfigurasi ADC sebelum Anda membuat instance pengekspor gRPC:

async function getAuthenticatedClient(): Promise<AuthClient> {
  const auth: GoogleAuth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/cloud-platform',
  });
  return await auth.getClient();
}

// Express App that exports traces via gRPC with protobuf
async function main() {
  const authenticatedClient: AuthClient = await getAuthenticatedClient();

  // ...
}

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 nilainya, gunakan ID project Google Cloud Anda.

Contoh:

export OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=PROJECT_ID"

Jika Anda menggunakan Java dan mengonfigurasi aplikasi untuk menggunakan Ekstensi Autentikasi Google Cloud, seperti yang dilakukan aplikasi Java contoh, Anda tidak perlu menetapkan project ID sebagai bagian dari atribut resource OpenTelemetry. Namun, menetapkan atribut ini tidak akan menimbulkan masalah.

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

Menetapkan ID project kuota

Project kuota adalah project Google Cloud 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 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.

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

Jika Anda menggunakan Java dan modul konfigurasi otomatis, Anda dapat menetapkan endpoint pengekspor menggunakan properti sistem, seperti yang dilakukan aplikasi Java contoh. Anda tidak perlu menetapkan variabel lingkungan pengekspor untuk konfigurasi tersebut.

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