Vom Trace-Exporteur zum OTLP-Endpunkt migrieren

In diesem Dokument wird beschrieben, wie Sie eine Anwendung migrieren, die mit OpenTelemetry instrumentiert ist und auf Google Cloud -Exportern basiert, um die OTLP-Exporter von OpenTelemetry zu verwenden. 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 Tracedaten exportieren, wenn Sie die manuelle Instrumentierung verwenden. Diese Anleitung für Java, Go und Python gilt nicht für das Senden von Log- oder Messwertdaten an Ihr Google Cloud -Projekt.

Gründe für die Migration

Die OpenTelemetry SDKs generieren Log-, Messwert- und Trace-Daten im OTLP-Format. Wenn eine Anwendung diese Daten in einGoogle Cloud -Projekt exportiert, indem sie einen Google Cloud -Exporter verwendet, 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 und dann in Ihrem Google Cloud -Projekt gespeichert.

Für Trace-Daten empfehlen wir, Ihre Anwendung für den Export von Daten zur Verwendung der Telemetry (OTLP) API zu migrieren, da für diesen Export keine Datentransformation erforderlich ist. Bei der Datentransformation können einige Daten verloren gehen. So kann das proprietäre Format beispielsweise niedrigere Grenzwerte für bestimmte Felder haben oder einige OTLP-Felder lassen sich nicht einem Feld im proprietären Format zuordnen.

Hinweise

Bevor Sie Ihre Anwendung migrieren, um Tracedaten an den OTLP-Endpunkt zu senden, müssen Sie die Telemetry API aktivieren und dafür sorgen, dass Ihnen die erforderlichen IAM-Rollen (Identity and Access Management) zugewiesen wurden. Möglicherweise müssen Sie einem Dienstkonto auch IAM-Rollen zuweisen.

Telemetry API aktivieren

Achten Sie darauf, dass die Telemetry API, die Cloud Logging API, die Cloud Monitoring API und die Cloud Trace API für Ihr Projekt aktiviert sind. Die Telemetry API ist standardmäßig deaktiviert.

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

Berechtigungen konfigurieren

Migrationsanleitung für die manuelle Instrumentierung

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

Abhängigkeiten hinzufügen

Als Erstes müssen Sie die Abhängigkeiten für den OTLP-Trace-Exporter von OpenTelemetry in Ihrer Anwendung 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

Prüfen Sie bei einer Golang-Anwendung, ob 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 Datei 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

Google Cloud -Exporteure durch OTLP-Exporteure ersetzen

Aktualisieren Sie Ihren Anwendungscode so, dass das OpenTelemetry SDK für die Verwendung der OpenTelemetry OTLP-Exporter anstelle des Google Cloud -Trace-Exporters konfiguriert ist. 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

Mit den vorherigen Änderungen an der OpenTelemetry SDK-Konfiguration ist Ihre Anwendung so konfiguriert, dass Traces mit den OpenTelemetry OTLP-Exportern über gRPC oder HTTP exportiert werden. Als Nächstes müssen Sie die Exporter 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. Exporter-Endpunkt konfigurieren

In diesem Abschnitt werden die einzelnen Schritte beschrieben.

Authentifizierungsheader für die Exportaufrufe konfigurieren

Wenn Sie den Exporter mit Ihren Google Cloud Standardanmeldedaten für Anwendungen konfigurieren möchten, fügen Sie eine sprachspezifische Google Auth-Bibliothek hinzu.

Java

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Trace 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 Trace 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 Trace 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-Exporter erstellt, sodass die aus der Bibliothek abgerufenen Autorisierungstokens 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, in dem diese Erweiterung verwendet wird, finden Sie unter OTLP-Trace mit Google-Authentifizierung.

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

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.

Beispiel:

export OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=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 OTLP-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.