Vom Trace-Exporteur zum OTLP-Endpunkt migrieren

In diesem Dokument wird beschrieben, wie Sie den In-Process-Export von Tracedaten durch das OpenTelemetry SDK in Ihr Google Cloud -Projekt konfigurieren. Die Beispiele für Java, Go, Python und Node.js zeigen, wie Sie das SDK so konfigurieren, dass Tracedaten an die Telemetry API (OTLP) gesendet werden, wenn Sie die manuelle Instrumentierung verwenden. Auf der Seite finden Sie für jede Sprache Informationen zur Verwendung von OTLP-Exportern zum Senden von Tracedaten über die unterstützten Exportprotokolle.

Die auf dieser Seite beschriebene Instrumentierung gilt nur für Tracedaten. Es werden keine Log- oder Messwertdaten an Ihr Google Cloud -Projekt gesendet.

Wenn Ihre Anwendung auf einen OpenTelemetry-Collector angewiesen ist, um Trace-Daten an Ihr Google Cloud -Projekt zu senden, gilt dieses Dokument nicht:

• Beispiele für die Instrumentierung finden Sie unter Beispiele für die Collector-basierte Instrumentierung.
• Informationen zu Collectors finden Sie unter Von Google entwickelter OpenTelemetry Collector.

Gründe für die Migration

Die OpenTelemetry SDKs generieren Log-, Messwert- und Tracedaten in einem Format, das im Allgemeinen mit den von OpenTelemetry OTLP Protocol definierten Protobuf-Dateien übereinstimmt. Felder werden jedoch möglicherweise vor der Speicherung von einem OpenTelemetry-spezifischen Datentyp in einen JSON-Datentyp konvertiert.

Wenn eine Anwendung diese Daten in ein Google 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.

Verfügbare Stichproben

Die auf dieser Seite erwähnten Beispielanwendungen sind auf GitHub verfügbar. Die meisten Anwendungen sind so konfiguriert, dass sie Tracedaten über gRPC exportieren. Das bedeutet, dass sie protobuf-codierte Daten im gRPC-Wire-Format über HTTP/2-Verbindungen verwenden. Außerdem wird Beispielcode für Anwendungen bereitgestellt, die so konfiguriert sind, dass sie Tracedaten als protobuf-codierte Daten über HTTP-Verbindungen exportieren:

• Java-Anwendung

  Die Beispielanwendung ist so konfiguriert, dass Traces als protobuf-codierte Daten über HTTP-Verbindungen exportiert werden. Wenn Sie gRPC verwenden möchten, ist die Instrumentierung in diesem Beispiel anwendbar. Sie müssen jedoch die Systemeigenschaften ändern, die vom Modul für die automatische Konfiguration verwendet werden. In der Beispielanwendung wird der http/protobuf-Exporter angegeben. Wenn Sie gRPC verwenden möchten, ändern Sie diese Einstellung in grpc.

  Wir empfehlen, dass Ihre Java-Anwendungen, wie die Beispielanwendung, das OpenTelemetry SDK Autoconfigure-Modul verwenden, um das SDK zu konfigurieren.

• Go-Anwendung, die gRPC verwendet und Go-Anwendung, die HTTP verwendet

  Es gibt zwei Go-Repositories. In einem Repository verwendet die Beispielanwendung gRPC. Im Beispiel im anderen Repository werden protobuf-codierte Daten über HTTP-Verbindungen verwendet.

• Python-Anwendung

  Dieses Repository enthält zwei Beispiele: eines für gRPC und eines, das protobuf-codierte Daten über HTTP-Verbindungen verwendet.

• Node.js-Anwendung

  Dieses Repository enthält zwei Beispiele: eines für gRPC und eines, das protobuf-codierte Daten über HTTP-Verbindungen verwendet.

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.

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.

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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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.

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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Berechtigungen konfigurieren

• Weisen Sie dem Dienstkonto, das von Ihrer Anwendung verwendet wird, die folgenden IAM-Rollen zu:

  • Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)
  • Log-Autor (roles/logging.logWriter) |
  • Monitoring-Messwert-Autor (roles/monitoring.metricWriter)

  Weitere Informationen zu Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) 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 das Projekt zuzuweisen, damit Sie die nötigen Berechtigungen zum Aufrufen Ihrer Log-, Messwert- und Tracedaten haben:

  • Logbetrachter (roles/logging.viewer)
  • Monitoring Viewer (roles/monitoring.viewer)
  • Cloud Trace User (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

Hinweis :Wir empfehlen, das SDK mit dem OpenTelemetry SDK Autoconfigure-Modul zu konfigurieren. Die Beispielanwendung verwendet dieses Modul.

Fügen Sie für eine Java-Anwendung in Ihrem build.gradle-Skript die folgenden Abhängigkeiten hinzu:

// use the latest versions
implementation("io.opentelemetry:opentelemetry-exporter-otlp:1.56.0")
implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure:1.56.0")

Go

In diesem Abschnitt werden die Änderungen veranschaulicht, die Sie an Ihren Abhängigkeiten vornehmen müssen, wenn Sie gRPC für den Export verwenden. Wenn Sie protobuf-codierte Daten über HTTP-Verbindungen für den Export verwenden, fügen Sie das otlptracehttp-Paket als Abhängigkeit ein. Weitere Informationen finden Sie unter Go-Anwendung, die HTTP verwendet.

Wenn Sie eine Go-Anwendung verwenden, die gRPC für den Export nutzt, aktualisieren Sie die Datei go.mod, damit sie die folgende Abhängigkeit enthält:

// go.mod file
require(
  // OTLP exporter that uses grpc protocol for export
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.38.0
)

Python

In diesem Abschnitt werden die Änderungen veranschaulicht, die Sie an Ihren Abhängigkeiten vornehmen müssen, wenn Sie gRPC für den Export verwenden. Wenn Sie protobuf-codierte Daten über HTTP-Verbindungen für den Export verwenden, fügen Sie das opentelemetry-exporter-otlp-proto-http-Paket als Anforderung hinzu. Weitere Informationen finden Sie unter Python-Anwendung.

Für eine Python-Anwendung, die gRPC für den Export verwendet, installieren Sie 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.39.0
grpcio==1.76.0

Node.js

In diesem Abschnitt werden die Änderungen veranschaulicht, die Sie an Ihren Abhängigkeiten vornehmen müssen, wenn Sie gRPC für den Export verwenden. Wenn Sie protobuf-codierte Daten über HTTP-Verbindungen für den Export verwenden, müssen Sie das @opentelemetry/exporter-trace-otlp-proto-Paket als Abhängigkeit einbinden. Weitere Informationen finden Sie unter Node.js-Anwendung.

Fügen Sie für eine Node.js-Anwendung, die gRPC verwendet, die folgenden Abhängigkeiten hinzu.

"@opentelemetry/exporter-trace-otlp-grpc": "0.203.0",
"@grpc/grpc-js": "1.13.4",

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

Gehen Sie für eine Java-Anwendung so vor:

1. Fügen Sie die folgenden Importanweisungen hinzu:

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

2. Aktualisieren Sie den Anwendungscode, um das OpenTelemetry SDK Autoconfigure-Modul zum Konfigurieren des SDK zu verwenden:

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

3. Konfigurieren Sie die Systemeigenschaften, die vom Modul für die automatische Konfiguration zur Laufzeit verwendet werden. In diesem Modul werden diese Attribute verwendet, um das SDK zu starten. Sie können auch Umgebungsvariablen anstelle von Systemeigenschaften verwenden. Weitere Informationen finden Sie unter Umgebungsvariablen und Systemattribute.

   In der Beispielanwendung werden die Systemattribute im build.gradle-Script definiert:

   // 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=my-service',
     '-Dotel.exporter.otlp.protocol=http/protobuf',
     '-Dotel.java.global-autoconfigure.enabled=true',
     // ID of your Google Cloud Project, required by the auth extension
     '-Dgoogle.cloud.project=PROJECT_ID',
   ]
   
   // Now pass the config as JVM arguments to your java application:
   application {
           // Replace with the fully qualified name of your Main class.
     mainClassName = 'com.example.Main'
     applicationDefaultJvmArgs = autoconf_config
   }
   

   Wenn Sie Tracedaten lieber mit gRPC exportieren möchten, legen Sie das OTLP-Protokoll auf grpc fest, anstatt es auf http/protobuf zu setzen.

Go

In diesem Abschnitt werden die Änderungen beschrieben, die Sie vornehmen müssen, wenn Sie gRPC für den Export verwenden. Wenn Sie protobuf-codierte Daten über HTTP-Verbindungen für den Export verwenden, müssen Sie das otlptracehttp-Paket importieren und den Exporter mit entsprechenden Optionen konfigurieren. Weitere Informationen finden Sie unter Go-Anwendung, die HTTP verwendet.

Fügen Sie für eine Go-Anwendung, die gRPC für den Export verwendet, die folgenden Importanweisungen hinzu:

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

Aktualisieren Sie außerdem den Initialisierungscode, um TraceProvider mit dem gRPC-Exporter zu konfigurieren:

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

// creds: configure Application Default Credentials

// Initialize the OTLP gRPC exporter
exporter, err := otlptracegrpc.New(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>"
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

In diesem Abschnitt werden die Änderungen beschrieben, die Sie vornehmen müssen, wenn Sie gRPC für den Export verwenden. Wenn Sie protobuf-codierte Daten über HTTP-Verbindungen für den Export verwenden, müssen Sie das opentelemetry.exporter.otlp.proto.http-Paket importieren und den Exporter mit den entsprechenden Optionen konfigurieren. Weitere Informationen finden Sie unter Python-Anwendung.

Fügen Sie für eine Python-Anwendung, die gRPC für den Export verwendet, die folgenden Importe hinzu:

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
    OTLPSpanExporter,
)
from opentelemetry.sdk.resources import SERVICE_NAME, Resource

Aktualisieren Sie außerdem den Initialisierungscode, um TraceProvider mit dem gRPC-Exporter zu konfigurieren:

# 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

In diesem Abschnitt werden die Änderungen beschrieben, die Sie vornehmen müssen, wenn Sie gRPC für den Export verwenden. Wenn Sie protobuf-codierte Daten über HTTP-Verbindungen für den Export verwenden, importieren Sie das @opentelemetry/exporter-trace-otlp-proto-Paket. Weitere Informationen finden Sie unter Node.js-Anwendung.

Fügen Sie für eine Node.js-Anwendung, die gRPC für den Export verwendet, die folgenden Importe hinzu:

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

Aktualisieren Sie außerdem den Initialisierungscode, um TraceProvider mit dem gRPC-Exporter zu konfigurieren:

// Express App that exports traces via gRPC with protobuf
async function main() {
  // authenticatedClient: configure Application Default Credentials

  // Configure the TraceExporter
  const sdk = new NodeSDK({
    traceExporter: new OTLPTraceExporter({
      credentials: credentials.combineChannelCredentials(
        credentials.createSsl(),
        credentials.createFromGoogleCredential(authenticatedClient),
      ),
    }),
  });
  sdk.start();
}

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 im Detail 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 zur Authentifizierung bei Trace die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

Für eine Java-Anwendung, die das OpenTelemetry SDK Autoconfigure-Modul verwendet, empfehlen wir, auch die Google Cloud Authentication Extension zu verwenden.

// build.gradle
implementation("io.opentelemetry.contrib:opentelemetry-gcp-auth-extension:1.52.0-alpha")

Go

Richten Sie zur Authentifizierung bei Trace die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

Wenn Sie eine Go-Anwendung verwenden, die gRPC für den Export nutzt, aktualisieren Sie die Datei go.mod, damit sie die folgende Abhängigkeit enthält:

// go.mod file
require (
    // When using gRPC based OTLP exporter, auth is built-in
    google.golang.org/grpc v1.75.1
)

Aktualisieren Sie für eine Go-Anwendung, die HTTP für den Export verwendet, die Datei go.mod, um die folgende Abhängigkeit einzuschließen:

// go.mod file
require (
    // When using http based OTLP exported, use explicit auth library
  golang.org/x/oauth2 v0.31.0
)

Python

Richten Sie zur Authentifizierung bei Trace die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

Fügen Sie für eine Python-Anwendung die folgenden Importe hinzu:

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

Node.js

Richten Sie zur Authentifizierung bei Trace die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

Fügen Sie für eine Node.js-Anwendung die folgenden Abhängigkeiten hinzu:

"google-auth-library": "9.15.1",

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

Wenn Sie eine Java-Anwendung haben, die das OpenTelemetry SDK Autoconfigure-Modul und die Google Cloud Authentication Extension verwendet, müssen Sie bei der Initialisierung Ihrer Anwendung keine besonderen Schritte ausführen. Das Modul für die automatische Konfiguration führt automatisch die erforderlichen Schritte zum Konfigurieren von ADC aus.

Go

In diesem Abschnitt werden die Änderungen beschrieben, die Sie vornehmen müssen, wenn Sie gRPC für den Export verwenden. Wenn Sie protobuf-codierte Daten über HTTP-Verbindungen für den Export verwenden, müssen Sie das otlptracehttp-Paket importieren und den Exporter als otlptracehttp-Objekt konfigurieren. Weitere Informationen finden Sie unter Go-Anwendung, die HTTP verwendet.

Fügen Sie für eine Go-Anwendung, die gRPC für den Export verwendet, die folgenden Importanweisungen hinzu:

import (
    "context"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    // other dependencies
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/oauth"
)

Aktualisieren Sie außerdem den Initialisierungscode, um ADC zu konfigurieren, bevor Sie den gRPC-Exporter instanziieren:

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

// Retrieve and store 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>"
exporter, err := otlptracegrpc.New(ctx, otlptracegrpc.WithDialOption(grpc.WithPerRPCCredentials(creds)))
if err != nil {
  panic(err)
}

// Other OpenTelemetry configuration remains unaffected.

Python

In diesem Abschnitt werden die Änderungen beschrieben, die Sie vornehmen müssen, wenn Sie gRPC für den Export verwenden. Wenn Sie protobuf-codierte Daten über HTTP-Verbindungen für den Export verwenden, verwenden Sie die Standardanmeldedaten. Sie müssen diese Anmeldedaten auch übergeben, wenn Sie die BatchSpanProcessor instanziieren. Weitere Informationen finden Sie unter Python-Anwendung.

Fügen Sie für eine Python-Anwendung, die gRPC für den Export verwendet, die folgenden Importe hinzu:

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

Aktualisieren Sie außerdem den Initialisierungscode, um ADC zu konfigurieren, bevor Sie den gRPC-Exporter instanziieren:

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),
)

# Configure the TraceProvider

Node.js

In diesem Abschnitt werden die Änderungen beschrieben, die Sie vornehmen müssen, wenn Sie gRPC für den Export verwenden. Wenn Sie protobuf-codierte Daten über HTTP-Verbindungen für den Export verwenden, müssen Sie etwas andere Änderungen vornehmen als hier beschrieben. Weitere Informationen finden Sie in der Datei app-http-proto-export.ts, die in der Node.js-Anwendung enthalten ist.

Fügen Sie für eine Node.js-Anwendung, die gRPC für den Export verwendet, die folgenden Importe hinzu:

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

Aktualisieren Sie außerdem den Initialisierungscode, um ADC zu konfigurieren, bevor Sie den gRPC-Exporter instanziieren:

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();

  // Configure the TraceExporter
}

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"

Wenn Sie Java verwenden und Ihre Anwendung so konfigurieren, dass sie die Google Cloud Authentication Extension verwendet, wie in der Beispiel-Java-Anwendung, müssen Sie die Projekt-ID nicht als Teil der OpenTelemetry-Ressourcenattribute festlegen. Das Festlegen dieses Attributs ist jedoch nicht schädlich.

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 Umgebungsvariable OTEL_EXPORTER_OTLP_ENDPOINT auf den OTLP-Endpunkt für Google Cloudfest.

Beispiel:

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

Wenn Sie Java und das Modul „autoconfigure“ verwenden, können Sie den Exporter-Endpunkt mithilfe von Systemeigenschaften festlegen, wie in der Beispiel-Java-Anwendung. Sie müssen die Umgebungsvariable des Exporters für diese Konfiguration nicht festlegen.

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