Vom Trace-Exporteur zum OTLP-Endpunkt migrieren

In diesem Dokument wird beschrieben, wie Sie eine Anwendung, die mit OpenTelemetry instrumentiert ist und Google Cloud -Exporter verwendet, auf die OpenTelemetry-OTLP-Exporter umstellen. Bei beiden Konfigurationen wird Telemetrie an Ihr Google Cloud-Projekt gesendet. Die Schritte in diesem Dokument beziehen sich auf den In-Process-Export, der vom OpenTelemetry SDK ausgeführt wird.

In diesem Dokument wird beschrieben, wie Sie bei manueller Instrumentierung Ablaufdaten exportieren. Diese Anleitung gilt für Java, Go und Python und nicht für das Senden von Protokoll- oder Messwertdaten an Ihr Google Cloud-Projekt.

Vorteile der Migration

Die OpenTelemetry SDKs generieren Protokoll-, Messwert- und Trace-Daten im OTLP-Format. Wenn eine Anwendung diese Daten mithilfe eines Google Cloud -Exporters in ein Google Cloud-Projekt exportiert, führt dieser Exporter die folgenden Schritte aus:

  1. Wandelt die aufgezeichneten Daten aus dem OTLP-Format in ein proprietäres Format um, das von der Cloud Logging API, der Cloud Monitoring API oder der Cloud Trace API definiert wird.
  2. Die transformierten Daten werden an die entsprechende API gesendet, die dann in Ihrem Google Cloud-Projekt gespeichert wird.

Für Trace-Daten empfehlen wir, Ihre Anwendung so zu migrieren, dass Daten mit der Telemetry (OTLP) API exportiert werden, da für diesen Export keine Datentransformation erforderlich ist. Die Datentransformation kann zu Datenverlusten führen. So kann es beispielsweise sein, dass das proprietäre Format für bestimmte Felder niedrigere Limits hat oder einige OTLP-Felder nicht einem Feld im proprietären Format zugeordnet werden.

Migrationsanleitung für manuelle Instrumentierung

In diesem Abschnitt wird beschrieben, wie Sie Ihre Anwendung so ändern, dass sie Ihre Trace-Daten mithilfe der Telemetry API an Ihr Google Cloud-Projekt sendet. Sie können keine Messwert- oder Protokolldaten an diesen Endpunkt senden.

Abhängigkeiten hinzufügen

Als Erstes müssen Sie Ihrer Anwendung Abhängigkeiten für den OTLP-Trace-Exporter von OpenTelemetry hinzufügen. Wählen Sie die Abhängigkeitsversionen aus, die für Ihre Anwendung und Ihr Build-System geeignet sind.

Java

Für eine Java-Anwendung, die das Gradle-Buildsystem verwendet:

// build.gradle
implementation("io.opentelemetry:opentelemetry-exporter-otlp:1.47.0")

Go

Achten Sie bei einer Golang-Anwendung darauf, dass die Datei go.mod die folgenden Abhängigkeiten enthält:

// 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

Installieren Sie für eine Python-Anwendung die folgenden Abhängigkeiten oder aktualisieren Sie die requirements.txt-Datei:

# 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

Google Cloud -Exporteure durch OTLP-Exporteure ersetzen

Aktualisieren Sie den Anwendungscode so, dass das OpenTelemetry SDK so konfiguriert ist, dass die OpenTelemetry OTLP-Exporter anstelle des Google Cloud -Trace-Exporters verwendet werden. Die erforderlichen Änderungen sind sprachspezifisch.

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)

Authentifizierung konfigurieren

Durch die vorherigen Änderungen an der OpenTelemetry SDK-Konfiguration ist Ihre Anwendung so konfiguriert, dass Traces mithilfe der OpenTelemetry OTLP-Exporter entweder über gRPC oder HTTP exportiert werden. Als Nächstes müssen Sie die Exporte so konfigurieren, dass diese Traces an Ihr Google Cloud-Projekt gesendet werden.

So konfigurieren Sie die Authentifizierung:

  1. Authentifizierungsheader für die Exportaufrufe konfigurieren
  2. Konfigurieren Sie die erforderlichen OpenTelemetry-Ressourcenattribute und OTLP-Header.
  3. Konfigurieren Sie den Exporter-Endpunkt.

In diesem Abschnitt werden die einzelnen Schritte beschrieben.

Authentifizierungsheader für die Exportaufrufe konfigurieren

Wenn Sie den Exporteur mit Ihren Google Cloud Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) konfigurieren möchten, fügen Sie eine sprachspezifische Google Auth-Bibliothek hinzu.

Java

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Google Cloud Observability zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 

// build.gradle
// Google Auth Library
implementation("com.google.auth:google-auth-library-oauth2-http:1.32.1")

Go

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Google Cloud Observability zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 

// 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

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Google Cloud Observability zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 

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

Aktualisieren Sie als Nächstes den Anwendungscode, der den OTLP-Span-Exporteur erstellt, sodass die Autorisierungstokens, die aus der Bibliothek abgerufen wurden, den Headern hinzugefügt werden. Dieser Schritt ist sprachspezifisch, die Implementierung ist jedoch für alle Sprachen ähnlich.

Java

Wir empfehlen die Verwendung der Google Cloud Authentication Extension, wenn Sie das OpenTelemetry SDK Autoconfigure-Modul verwenden. Ein vollständiges Beispiel für die Verwendung dieser Erweiterung finden Sie unter OTLP-Trace mit Google Auth-Beispiel.

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

Erforderliche OpenTelemetry-Ressourcenattribute und OTLP-Header konfigurieren

Legen Sie die folgenden OpenTelemetry-Umgebungsvariablen fest:

  • OTEL_RESOURCE_ATTRIBUTES: Konfigurieren Sie diese Umgebungsvariable, um den Schlüssel gcp.project_id in den OpenTelemetry-Ressourcenattributen festzulegen. Der Wert sollte die ID Ihres Google Cloud-Projekts sein.

  • OTEL_EXPORTER_OTLP_HEADERS: Konfigurieren Sie diese Umgebungsvariable, um den x-goog-user-project-Header hinzuzufügen. Der Wert sollte die ID Ihres Google Cloud-Projekts sein, für das das Dienstkontingent verwendet wird. Normalerweise wird der Wert auf denselben Wert wie für den Schlüssel gcp.project_id festgelegt.

Beispiel:

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

Weitere Informationen zu OpenTelemetry-Umgebungsvariablen finden Sie unter Allgemeine SDK-Konfiguration.

Exporter-Endpunkt konfigurieren

Legen Sie den Wert der Umgebungsvariablen OTEL_EXPORTER_OTLP_ENDPOINT auf den OLTP-Endpunkt für Google Cloudfest.

Beispiel:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://telemetry.googleapis.com

Weitere Informationen zu OpenTelemetry-Umgebungsvariablen finden Sie unter Allgemeine SDK-Konfiguration.

Erforderliche Berechtigungen

Es gibt IAM-Rollen und ‑Berechtigungen, die Ihnen oder einem Dienstkonto die Möglichkeit geben, Trace-Daten in die Telemetry API zu schreiben und diese Daten in Ihrem Google Cloud-Projekt zu speichern. Wenn Ihnen beispielsweise nur Cloud Trace-Rollen oder ‑Berechtigungen gewährt wurden, können Sie mit diesen Berechtigungen keine Daten mit der Telemetry API schreiben.

  • Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie benötigen, damit die Beispielanwendungen Protokoll-, Messwert- und Ablaufdaten schreiben können:

Weitere Informationen finden Sie unter Funktionsweise von Standardanmeldedaten für Anwendungen und Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) für eine lokale Entwicklungsumgebung einrichten.

Erforderliche APIs

Die Telemetry API ist standardmäßig deaktiviert. Sie müssen diese API aktivieren. Im Folgenden finden Sie Informationen zu den APIs, die zum Senden von Telemetry-Daten an ein Google Cloud-Projekt und zum Ansehen dieser Daten erforderlich sind:

Google Cloud Console

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