Python und OpenTelemetry

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Diese Seite richtet sich an Anwendungsentwickler, die Cloud Trace-Daten für Python-Anwendungen mithilfe von OpenTelemetry erfassen möchten. OpenTelemetry bietet eine Reihe von Instrumentierungsbibliotheken zum Erfassen von Trace- und Messwertdaten. Diese Bibliotheken funktionieren mit mehreren Back-Ends. So erfassen Sie Traces mit OpenTelemetry und Python, wie auf dieser Seite beschrieben:

  • Installieren Sie die OpenTelemetry-Pakete.
  • Anwendung für den Export von Spans nach Cloud Trace konfigurieren
  • Konfigurieren Sie Ihre Plattform.

Releaseinformationen finden Sie hier:

Aktuelle Informationen zu OpenTelemetry für Python sowie zusätzliche Dokumentation und Beispiele finden Sie unter OpenTelemetry.

Hinweis

  • Sie müssen Python 3.6 oder höher verwenden.
  • Prüfen Sie, ob die Cloud Trace API für Ihr Google Cloud-Projekt aktiviert ist:

    1. Klicken Sie auf die folgende Schaltfläche oder wählen Sie in der Google Cloud Console APIs &Dienste und dann Cloud Trace API aus:

      Zur Trace API

    2. Wenn auf der Seite Cloud Trace API eine Schaltfläche mit der Bezeichnung Aktivieren angezeigt wird, klicken Sie darauf. Wenn diese Schaltfläche nicht angezeigt wird, ist die Cloud Trace API für das ausgewählte Projekt aktiviert.

OpenTelemetry-Pakete installieren

So installieren Sie die erforderlichen OpenTelemetry-Pakete:

  1. (Optional) Führen Sie ein Upgrade auf die neueste Version von pip durch:

    pip install --upgrade pip
    
  2. Installieren Sie die folgenden OpenTelemetry-Pakete mit pip:

    pip install opentelemetry-api \
      opentelemetry-sdk \
      opentelemetry-exporter-gcp-trace
    

Trace-Pakete importieren

Aktualisieren Sie Ihre Anwendung und importieren Sie die folgenden Pakete und Klassen:

  • trace
  • CloudTraceSpanExporter
  • TracerProvider
  • Ein Exportprozessor:

    • Verwenden Sie den Prozessor BatchSpanProcessor, um Spans mit einem Hintergrundprozess zu senden. Wir empfehlen die Verwendung dieses Prozessors, sofern Sie nicht Cloud Run verwenden. Cloud Run unterstützt keine Hintergrundprozesse.

    • Verwenden Sie den Prozessor SimpleSpanProcessor, um Spans mit einem Vordergrundprozess zu senden. Wenn Sie Cloud Run verwenden, müssen Sie diesen Prozessor verwenden. Dieser Prozessor verlangsamt möglicherweise Ihre Anwendung.

  • (Optional) Wenn Sie Spans verknüpfen möchten, importieren Sie die Klasse Link

Das folgende Beispiel veranschaulicht diese Importanweisungen:


from opentelemetry import trace
from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.trace import Link

Export von Spans nach Cloud Trace konfigurieren

Wenn Sie Spans an Cloud Trace senden möchten, ändern Sie Ihre Anwendung so, dass sie den Exporter CloudTraceSpanExporter verwendet. Das folgende Beispiel veranschaulicht die erforderlichen Schritte:


tracer_provider = TracerProvider()
cloud_trace_exporter = CloudTraceSpanExporter()
tracer_provider.add_span_processor(
    # BatchSpanProcessor buffers spans and sends them in batches in a
    # background thread. The default parameters are sensible, but can be
    # tweaked to optimize your performance
    BatchSpanProcessor(cloud_trace_exporter)
)
trace.set_tracer_provider(tracer_provider)

tracer = trace.get_tracer(__name__)

Attribute zu einem Span hinzufügen

Rufen Sie die Methode set_attribute des Spans auf, um einem Span ein Attribut hinzuzufügen. Der folgende Code fügt beispielsweise mehrere Attribute zum Span mit dem Namen foo_with_attribute hinzu:


with tracer.start_span("foo_with_attribute") as current_span:
    do_work()

    # Add attributes to the spans of various types
    current_span.set_attribute("string_attribute", "str")
    current_span.set_attribute("bool_attribute", False)
    current_span.set_attribute("int_attribute", 3)
    current_span.set_attribute("float_attribute", 3.14)

Ereignisse zu einem Span hinzufügen

Rufen Sie die Methode add_event des Spans auf, um ein Ereignis zu einem Span hinzuzufügen. Der folgende Code fügt beispielsweise dem Span ein Ereignis hinzu.foo_with_event:


# Adding events to spans
with tracer.start_as_current_span("foo_with_event") as current_span:
    do_work()
    current_span.add_event(name="event_name")

Wenn Sie zwei Spans verknüpfen möchten, importieren Sie die Link-Klasse und verwenden Sie dann das links-Feld in der Methode start_as_current_span. Wenn Sie zwei Spans verknüpfen, können Sie Attribute in das Feld links aufnehmen.

Der folgende Code zeigt zwei verschiedene Möglichkeiten, wie Sie einen Span mit dem Span namens link_target verknüpfen können:


# Adding links to spans
with tracer.start_as_current_span("link_target") as link_target:
    # Using start_as_current_span() instead of start_span() will make spans
    # created within this scope children of foo_with_attribute

    # Creates a span "span_with_link" and a link from
    # "span_with_link" -> "link_target"
    with tracer.start_as_current_span(
        "span_with_link", links=[Link(link_target.context)]
    ):
        do_work()

    # Creates a span "span_with_link" and a link from
    # "span_with_link" -> "link_target". This link also has the attribute
    # {"link_attr": "string"}
    with tracer.start_as_current_span(
        "span_with_link_and_link_attributes",
        links=[Link(link_target.context, attributes={"link_attr": "string"})],
    ):
        do_work()

Beispiel-Flask-Anwendung

Die Flask-Instrumentierung von OpenTelemetry soll die Erfassung von Trace-Inhalten im Zusammenhang mit HTTP-Anfragen vereinfachen. Dies bedeutet, dass Sie Ihren Routen für diese Anfragen keine bestimmte Instrumentierung hinzufügen müssen:

  • Flask verwendet den konfigurierten Propagator, um den Span-Kontext aus den eingehenden HTTP-Anfragen zu extrahieren.
  • Flask erstellt automatisch Spans mit Attributen, die die Anfrage und die Antwort beschreiben.

Ein End-to-End-Beispiel mit Flask und OpenTelemetry finden Sie unter flask_e2e. Die Git-README-Datei enthält Informationen zum Installieren, Konfigurieren und Ausführen des Beispiels.

In diesem Abschnitt werden Flask-spezifische Konfigurationsschritte hervorgehoben, die in der Datei server.py des Beispiels enthalten sind. Die Client-Datei client.py verwendet die Instrumentierung Requests, um das Tracing von HTTP-Anfragen durch die Bibliothek requests zu ermöglichen.

Import und Konfiguration

Zur Verwendung der Flask-Instrumentierung von OpenTelemetry müssen Sie den FlaskInstrumentor importieren.

Wenn Sie dafür sorgen möchten, dass Spans, die von verschiedenen Google Cloud-Produkten erstellt wurden, demselben Trace zugeordnet werden, müssen Sie den Propagator mit dem Cloud Trace-Propagator konfigurieren. Dieser Propagator gibt die Verwendung des Headers X-Cloud-Trace-Context an. Wenn Sie keinen Propagator konfigurieren, verwendet OpenTelemetry den Standardpropagator. In diesem Fall befinden sich Spans, die von verschiedenen Google Cloud-Produkten wie Cloud Run und App Engine erstellt wurden, in separaten Traces.

Im folgenden Beispiel werden die erforderlichen Import- und Konfigurationsanweisungen sowie die Konfiguration des Cloud Trace-Propagator veranschaulicht:


import time

from flask import Flask
from opentelemetry import trace
from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
from opentelemetry.instrumentation.flask import FlaskInstrumentor
from opentelemetry.propagate import set_global_textmap
from opentelemetry.propagators.cloud_trace_propagator import (
    CloudTraceFormatPropagator,
)
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

set_global_textmap(CloudTraceFormatPropagator())

Sie müssen keine Flask-spezifischen Anweisungen hinzufügen, wenn Sie den CloudTraceSpanExporter-Exporter konfigurieren. Die unter Export von Spans nach Cloud Trace konfigurieren angezeigte Konfiguration ist ausreichend.

Flask initialisieren

Konfigurieren Sie FlaskInstrumentor, um Ihre Anwendung zu instrumentieren. Das folgende Beispiel zeigt, wie dieser Schritt ausgeführt wird:


app = Flask(__name__)
FlaskInstrumentor().instrument_app(app)

@app.route("/")
def hello_world():
    # You can still use the OpenTelemetry API as usual to create custom spans
    # within your trace
    with tracer.start_as_current_span("do_work"):
        time.sleep(0.1)

    return "Hello, World!"

Plattform konfigurieren

Sie können Cloud Trace in Google Cloud und auf anderen Plattformen verwenden.

In Google Cloud ausführen

Wenn Ihre Anwendung in Google Cloud ausgeführt wird, müssen Sie für die Clientbibliothek keine Anmeldedaten zur Authentifizierung in der Clientbibliothek angeben. Für die Google Cloud Platform muss jedoch der Zugriffsbereich der Cloud Trace API aktiviert sein.

Eine Liste der unterstützten Google Cloud-Umgebungen finden Sie unter Umgebungsunterstützung.

Für die folgenden Konfigurationen wird die Cloud Trace API über die Standardeinstellungen für den Zugriffsbereich aktiviert:

  • Flexible App Engine-Umgebung
  • App Engine-Standardumgebung

  • Google Kubernetes Engine (GKE)

  • Compute Engine

  • Cloud Run

Wenn Sie benutzerdefinierte Zugriffsbereiche verwenden, muss der Zugriffsbereich der Cloud Trace API aktiviert sein:

  • Informationen zum Konfigurieren der Zugriffsbereiche für Ihre Umgebung mithilfe der Google Cloud Console finden Sie unter Google Cloud-Projekt konfigurieren.

  • Geben Sie für gcloud-Nutzer mithilfe des Flags --scopes Zugriffsbereiche an und beziehen Sie den Zugriffsbereich der Cloud Trace API trace.append ein. So erstellen Sie beispielsweise einen GKE-Cluster, für den nur die Cloud Trace API aktiviert ist:

    gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

Lokal und extern ausführen

Wenn Ihre Anwendung außerhalb von Google Cloud ausgeführt wird, müssen Sie Anmeldedaten zur Authentifizierung in Form eines Dienstkontos für die Clientbibliothek angeben. Das Dienstkonto muss die Rolle "Cloud Trace-Agent" enthalten. Informationen dazu finden Sie unter Dienstkonto erstellen.

Google Cloud-Clientbibliotheken verwenden Standardanmeldedaten für Anwendungen für die Suche nach den Anmeldedaten Ihrer Anwendung.

Sie haben drei Möglichkeiten, diese Anmeldedaten anzugeben:

  • Führen Sie gcloud auth application-default login aus

  • Legen Sie das Dienstkonto in einem Standardpfad für Ihr Betriebssystem ab. Im Folgenden sind die Standardpfade für Windows und Linux aufgeführt:

    • Windows: %APPDATA%/gcloud/application_default_credentials.json

    • Linux: $HOME/.config/gcloud/application_default_credentials.json

  • Legen Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS auf den Pfad zu Ihrem Dienstkonto fest:

Linux/macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

Traces ansehen

Nach der Bereitstellung können Sie die Traces in der Trace-Anzeige der Google Cloud Console ansehen.

Trace-Anzeige öffnen

Fehlerbehebung

Informationen zur Fehlerbehebung bei Cloud Trace finden Sie auf der Seite Fehlerbehebung.

Ressourcen