Diese Seite wurde von der Cloud Translation API übersetzt.

Traces und Messwerte mit Python generieren

In diesem Dokument wird beschrieben, wie Sie eine Python-Anwendung so ändern, dass Trace- und Messwertdaten mithilfe des Open-Source-Frameworks OpenTelemetry erfasst werden, und wie Sie strukturierte JSON-Logs zum Standard-Out schreiben. Dieses Dokument enthält auch Informationen zu einer Python-Beispielanwendung, die Sie installieren und ausführen können. Die Anwendung verwendet das Web-Framework Flask und ist so konfiguriert, dass Messwerte, Traces und Logs generiert werden.

Weitere Informationen zur Instrumentierung finden Sie in den folgenden Dokumenten:

Manuelle und automatische Instrumentierung

Für diese Sprache definiert OpenTelemetry die automatische Instrumentierung als das Erfassen von Telemetriedaten aus Bibliotheken und Frameworks, ohne Änderungen am Code vorzunehmen. Sie müssen jedoch Module installieren und Umgebungsvariablen festlegen.

In diesem Dokument wird die automatische Instrumentierung nicht beschrieben. Informationen zu diesem Thema finden Sie unter Automatische Instrumentierung für Python.

Allgemeine Informationen finden Sie unter OpenTelemetry-Instrumentation for Python.

Hinweise

Cloud Logging, Cloud Monitoring, and Cloud Trace APIs aktivieren.

Aktivieren Sie die APIs

Anwendung für die Erfassung von Traces, Messwerten und Logs instrumentieren

Führen Sie die folgenden Schritte aus, wie in den folgenden Abschnitten dieses Dokuments beschrieben, um Ihre Anwendung so zu instrumentieren, dass Trace- und Messwertdaten erfasst und strukturierte JSON-Daten für Standard-Out geschrieben werden:

OpenTelemetry konfigurieren
Strukturiertes Logging konfigurieren

OpenTelemetry konfigurieren

Diese Beispielanwendung ist so konfiguriert, dass das OpenTelemetry Python SDK verwendet wird, um Traces und Messwerte mithilfe des OTLP-Protokolls zu exportieren. Das Python SDK von OpenTelemetry verwendet standardmäßig das Format W3C Trace Context zur Weitergabe von Trace-Kontext. Dadurch wird sichergestellt, dass Spans in einem Trace die richtige hierarchische Beziehung haben.

Das folgende Codebeispiel zeigt ein Python-Modul zum Einrichten von OpenTelemetry. Zum Aufrufen des vollständigen Beispiels klicken Sie auf Mehr und wählen dann Auf GitHub ansehen aus.

resource = Resource.create(attributes={
    # Use the PID as the service.instance.id to avoid duplicate timeseries
    # from different Gunicorn worker processes.
    SERVICE_INSTANCE_ID: f"worker-{os.getpid()}",
})

traceProvider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(OTLPSpanExporter())
traceProvider.add_span_processor(processor)
trace.set_tracer_provider(traceProvider)

reader = PeriodicExportingMetricReader(
    OTLPMetricExporter()
)
meterProvider = MeterProvider(metric_readers=[reader], resource=resource)
metrics.set_meter_provider(meterProvider)

Die Flask-Anwendung verwendet Gunicorn zum Bereitstellen von HTTP-Anfragen gemäß den Empfehlungen im Flask-Leitfaden Für die Produktion bereitstellen. Gunicorn startet mehrere Kopien Ihrer Anwendung, die in unabhängigen Worker-Prozessen ausgeführt werden, um den Durchsatz zu erhöhen. Damit Messwerte aus den Worker-Prozessen nicht miteinander in Konflikt stehen, empfehlen wir, für jeden Worker-Prozess einen eindeutigen Wert für das Ressourcenattribut service.instance.id festzulegen. Eine Möglichkeit dazu besteht darin, die Prozess-ID in den service.instance.id aufzunehmen. Weitere Informationen finden Sie unter Zeitreihenkollisionen.

Weitere Informationen und Konfigurationsoptionen finden Sie unter OpenTelemetry Python-Instrumentierung.

Strukturiertes Logging konfigurieren

Wenn Sie strukturierte Logs schreiben möchten, die mit Traces verknüpft sind, konfigurieren Sie Ihre Anwendung so, dass Logs im JSON-Format ausgegeben werden, um Standardschlüssel mit Trace-Informationen zu verwenden. Das folgende Codebeispiel zeigt, wie Sie die Standardbibliothek logging so konfigurieren, dass strukturierte JSON-Logs mithilfe der Bibliothek python-json-logger ausgegeben werden. Außerdem wird gezeigt, wie Sie mithilfe des Pakets opentelemetry-instrumentation-logging Traceinformationen einbinden.

LoggingInstrumentor().instrument()

logHandler = logging.StreamHandler()
formatter = jsonlogger.JsonFormatter(
    "%(asctime)s %(levelname)s %(message)s %(otelTraceID)s %(otelSpanID)s %(otelTraceSampled)s",
    rename_fields={
        "levelname": "severity",
        "asctime": "timestamp",
        "otelTraceID": "logging.googleapis.com/trace",
        "otelSpanID": "logging.googleapis.com/spanId",
        "otelTraceSampled": "logging.googleapis.com/trace_sampled",
        },
    datefmt="%Y-%m-%dT%H:%M:%SZ",
)
logHandler.setFormatter(formatter)
logging.basicConfig(
    level=logging.INFO,
    handlers=[logHandler],
)

Die vorherige Konfiguration extrahiert Informationen zum aktiven Span aus der Lognachricht und fügt diese Informationen dann als Attribute dem strukturierten JSON-Log hinzu. Mit diesen Attributen können Sie dann ein Log mit einem Trace korrelieren:

logging.googleapis.com/trace: Der Ressourcenname des Trace, das mit dem Logeintrag verknüpft ist.
logging.googleapis.com/spanId: Die Span-ID mit dem Trace, das dem Logeintrag zugeordnet ist.
logging.googleapis.com/trace_sampled: Der Wert dieses Felds muss true oder false sein.

Weitere Informationen zu diesen Feldern finden Sie in der LogEntry-Struktur.

Beispielanwendung ausführen, die für die Erfassung von Telemetriedaten konfiguriert ist

Die Beispielanwendung verwendet anbieterneutrale Formate, einschließlich JSON für Logs und OTLP für Messwerte und Traces. Die Telemetrie der Anwendung wird über die mit Google-Exportern konfigurierte OpenTelemetry-Collector an Google Cloud weitergeleitet. Dabei wird Flask verwendet, um HTTP-Anfragen zu verarbeiten, und die requests-Bibliothek zum Senden von HTTP-Anfragen. Die Beispielanwendung installiert die Instrumentierungsbibliotheken opentelemetry-instrumentation-flask und opentelemetry-instrumentation-requests, um Messwerte und Traces für den HTTP-Client und -Server zu generieren:

logger = logging.getLogger(__name__)

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

Die Anwendung hat zwei Endpunkte:

Der /multi-Endpunkt wird von der multi-Funktion verarbeitet. Der Lastgenerator in der Anwendung gibt Anfragen an den Endpunkt /multi aus. Wenn dieser Endpunkt eine Anfrage empfängt, sendet er zwischen drei und sieben Anfragen an den Endpunkt /single auf dem lokalen Server.

@app.route('/multi')
def multi():
    """Handle an http request by making 3-7 http requests to the /single endpoint."""
    subRequests = randint(3, 7)
    logger.info("handle /multi request", extra={'subRequests': subRequests})
    for _ in range(subRequests):
        requests.get(url_for('single', _external=True))
    return 'ok'

Der /single-Endpunkt wird von der single-Funktion verarbeitet. Wenn dieser Endpunkt eine Anfrage empfängt, wechselt er für eine kurze Verzögerung in den Ruhemodus und antwortet dann mit einem String.

@app.route('/single')
def single():
    """Handle an http request by sleeping for 100-200 ms, and write the number of seconds slept as the response."""
    duration = uniform(0.1, 0.2)
    time.sleep(duration)
    return f'slept {duration} seconds'

Anwendung herunterladen und bereitstellen

So führen Sie das Beispiel aus:

Aktivieren Sie Cloud Shell in der Google Cloud Console.

Cloud Shell aktivieren

Unten in der Google Cloud Console wird eine Cloud Shell-Sitzung gestartet und eine Eingabeaufforderung angezeigt. Cloud Shell ist eine Shell-Umgebung, in der das Google Cloud CLI bereits installiert ist und Werte für Ihr aktuelles Projekt bereits festgelegt sind. Das Initialisieren der Sitzung kann einige Sekunden dauern.

Klonen Sie das Repository:

git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-python

Gehen Sie zum Beispielverzeichnis:

cd opentelemetry-operations-python/samples/instrumentation-quickstart

Erstellen Sie das Beispiel und führen Sie es aus:
```
docker compose up --abort-on-container-exit
```
Wenn Sie Cloud Shell nicht ausführen, führen Sie die Anwendung mit der Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS aus, die auf eine Datei mit Anmeldedaten verweist. Standardanmeldedaten für Anwendungen stellt eine Datei mit Anmeldedaten unter $HOME/.config/gcloud/application_default_credentials.json bereit.
```
# Set environment variables
export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
export USERID="$(id -u)"

# Run
docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit
```

Messwerte ansehen

Die OpenTelemetry-Instrumentierung in der Beispielanwendung generiert Prometheus-Messwerte, die Sie mit dem Metrics Explorer aufrufen können:

Prometheus/http_server_duration_milliseconds/histogram zeichnet die Dauer von Serveranfragen auf und speichert die Ergebnisse in einem Histogramm.
Prometheus/http_client_duration_milliseconds/histogram zeichnet die Dauer von Clientanfragen auf und speichert die Ergebnisse in einem Histogramm.

So rufen Sie die von der Beispielanwendung generierten Messwerte auf:

Rufen Sie in der Google Cloud Console die Seite Metrics Explorer auf.
Zum Metrics Explorer

Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Monitoring ist.
Maximieren Sie im Element Messwert das Menü Messwert auswählen, geben Sie http_server in die Filterleiste ein und wählen Sie dann über die Untermenüs einen bestimmten Ressourcentyp und Messwert aus:
1. Wählen Sie im Menü Aktive Ressourcen die Option Prometheus-Ziel aus.
2. Wählen Sie im Menü Aktive Messwertkategorien die Option Http aus.
3. Wählen Sie im Menü Aktive Messwerte einen Messwert aus.
4. Klicken Sie auf Übernehmen.
Konfigurieren Sie, wie die Daten angezeigt werden.
Wenn die Messungen für einen Messwert kumulativ sind, normalisiert Metrics Explorer die gemessenen Daten automatisch nach dem Ausrichtungszeitraum. Dadurch wird im Diagramm eine Rate angezeigt. Weitere Informationen finden Sie unter Arten, Typen und Umwandlungen.

Wenn ganzzahlige oder doppelte Werte gemessen werden, z. B. mit den beiden counter-Messwerten, summiert der Metrics Explorer automatisch alle Zeitachsen. Wenn Sie die Daten für die HTTP-Routen /multi und /single aufrufen möchten, legen Sie im ersten Menü des Eintrags Aggregation die Option Keine fest.

Weitere Informationen zum Konfigurieren eines Diagramms finden Sie unter Messwerte bei Verwendung von Metrics Explorer auswählen.

Traces ansehen

So rufen Sie Ihre Trace-Daten auf:

Rufen Sie in der Google Cloud Console die Seite Trace Explorer auf:
Zum Trace Explorer

Sie können diese Seite auch über die Suchleiste finden.
Wählen Sie im Streudiagramm einen Trace mit dem URI /multi aus.
Wählen Sie im Gantt-Diagramm im Bereich Trace-Details den Span mit der Bezeichnung /multi aus.

Ein Steuerfeld mit Informationen zur HTTP-Anfrage wird geöffnet. Zu diesen Details gehören die Methode, der Statuscode, die Anzahl der Byte und der User-Agent des Aufrufers.
Wählen Sie den Tab Logs und Ereignisse aus, um die mit diesem Trace verknüpften Logs aufzurufen.

Auf dem Tab werden einzelne Logs angezeigt. Maximieren Sie den Logeintrag, um die Details anzusehen. Sie können auch auf Logs ansehen klicken und das Log mit dem Log-Explorer aufrufen.

Weitere Informationen zur Verwendung von Cloud Trace-Explorer finden Sie unter Traces suchen und untersuchen.

Logs ansehen

Im Log-Explorer können Sie Ihre Logs prüfen und sich auch die zugehörigen Traces ansehen, sofern vorhanden.

Rufen Sie in der Google Cloud Console die Seite Log-Explorer auf.
Zum Log-Explorer

Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Monitoring ist.
Suchen Sie ein Log mit der Beschreibung handle /multi request.

Erweitern Sie den Logeintrag, um die Details des Logs aufzurufen.
Klicken Sie auf Traces für einen Logeintrag mit der Nachricht "handle /multi request" und wählen Sie dann Trace-Details anzeigen aus.

Der Bereich Trace-Details wird geöffnet und zeigt den ausgewählten Trace an.

Weitere Informationen zur Verwendung des Log-Explorers finden Sie unter Logs mit dem Log-Explorer ansehen.