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-Exporte 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. Beispielsweise kann das proprietäre Format niedrigere Grenzwerte für bestimmte Felder haben oder einige OTLP-Felder werden nicht einem Feld im proprietären Format zugeordnet.

Hinweis :Die Telemetry API akzeptiert nur Tracedaten. Sie können mit diesem Endpunkt keine Messwert- oder Logdaten an Ihr Google Cloud -Projekt senden.

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.

Abrechnung und Telemetry API aktivieren

Hinweis: Die Telemetry API ist standardmäßig deaktiviert.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

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

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

Berechtigungen konfigurieren

• Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie benötigen, damit die Beispielanwendung Log-, Messwert- und Tracedaten an Ihr Projekt senden kann:

  • Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)
  • Log-Autor (roles/logging.logWriter)
  • Monitoring-Messwert-Autor (roles/monitoring.metricWriter)
  Hinweis: Wenn Sie Ihre Anwendung so konfigurieren, dass die Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) auf einem Dienstkonto basieren, weisen Sie dem Dienstkonto die vorherigen IAM-Rollen zu. 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.

• Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Aufrufen Ihrer Log-, Messwert- und Tracedaten benötigen:

  • Logs Viewer (roles/logging.viewer)
  • Monitoring Viewer (roles/monitoring.viewer)
  • Cloud Trace-Nutzer (roles/cloudtrace.user)

  Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

  Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

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 (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-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 konfigurieren

Fügen Sie der Umgebungsvariable OTEL_RESOURCE_ATTRIBUTES das Schlüssel/Wert-Paar hinzu, das Ihr Projekt angibt. Verwenden Sie für den Schlüssel gcp.project_id. Verwenden Sie als Wert die ID Ihres Google Cloud Projekts.

Beispiel:

export OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=PROJECT_ID"

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

Kontingentprojekt-ID festlegen

Das Kontingentprojekt ist das Google Cloud Projekt, in dem Ihre Nutzung von API-Anfragen erfasst wird. Da die Telemetry API eine clientbasierte API ist, hängt es von der Authentifizierung ab, ob das Kontingentprojekt automatisch identifiziert wird. Wenn Sie ein Dienstkonto für die Authentifizierung verwenden, müssen Sie beispielsweise das Kontingentprojekt nicht angeben. Sie müssen das Kontingentprojekt jedoch angeben, wenn Nutzeranmeldedaten für die Authentifizierung verwendet werden.

Sie können ein Kontingentprojekt mit einer Umgebungsvariablen festlegen. Informationen dazu, welche Umgebungsvariable für Ihre Programmiersprache festgelegt werden muss, finden Sie unter Kontingentprojekt mit einer Umgebungsvariablen festlegen.

In Go können Sie das Kontingentprojekt beispielsweise so festlegen:

export GOOGLE_CLOUD_QUOTA_PROJECT="QUOTA_PROJECT_ID"

Informationen zum Beheben von Authentifizierungsfehlern finden Sie unter Nutzeranmeldedaten funktionieren nicht.

Hinweis :Aktualisieren Sie die Umgebungsvariable OTEL_EXPORTER_OTLP_HEADERS nicht mit einem Schlüssel/Wert-Paar, das den Schlüssel x-goog-user-project verwendet. Diese Konfiguration kann zu doppelten Werten in der Anfrage führen, was dazu führt, dass API-Befehle fehlschlagen.

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.