Python-Beispiel für die Instrumentierung

In diesem Dokument wird beschrieben, wie Sie eine Python-Anwendung instrumentieren, um Trace- und Messwertdaten mit dem OpenTelemetry SDK und einem OpenTelemetry-Collector zu erfassen. Außerdem wird beschrieben, wie Sie strukturierte JSON-Logs in die Standardausgabe schreiben. Wenn Sie die Instrumentierung testen möchten, laden Sie die Beispielanwendung herunter und führen Sie sie aus. Diese Anwendung verwendet das Web-Framework Flask und generiert Log-, Messwert- und Trace-Daten.

Wenn Sie einen OpenTelemetry-Collector verwenden, instrumentieren Sie Ihre Anwendung mit dem SDK und dem OTLP-In-Process-Exporter des SDKs. Diese Instrumentierung ist anbieterneutral. Außerdem stellen Sie einen OpenTelemetry Collector bereit, der Telemetriedaten vom In-Process-Exporter empfängt und diese dann in Ihr Google Cloud -Projekt exportiert. Weitere Informationen zu Collectors finden Sie unter Von Google entwickelter OpenTelemetry Collector.

Wir empfehlen, einen OpenTelemetry-Collector zu verwenden, um Ihre Telemetriedaten zu exportieren, wenn Ihre Umgebung die Verwendung eines Collectors unterstützt. In einigen Umgebungen müssen Sie einen In-Process-Exporter verwenden, der Daten direkt an IhrGoogle Cloud -Projekt sendet. Weitere Informationen zur In-Process-Instrumentierung finden Sie unter Vom Trace-Exporter zum OTLP-Endpunkt migrieren.

Weitere Informationen zur Instrumentierung finden Sie in den folgenden Dokumenten:

Manuelle und Zero-Code-Instrumentierung

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

In diesem Dokument wird die Instrumentierung ohne Code nicht beschrieben. Weitere Informationen zu diesem Thema finden Sie unter Python-Instrumentierung ohne Code.

Allgemeine Informationen finden Sie unter OpenTelemetry-Instrumentierung für Python.

Hinweis

Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

Installieren Sie die Google Cloud CLI.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

gcloud init

Erstellen Sie ein Google Cloud Projekt oder wählen Sie eines aus.

Rollen, die zum Auswählen oder Erstellen eines Projekts erforderlich sind

Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können jedes Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Projektersteller“ (roles/resourcemanager.projectCreator), die die Berechtigung resourcemanager.projects.create enthält. Weitere Informationen zum Zuweisen von Rollen

So erstellen Sie ein Google Cloud -Projekt:
```
gcloud projects create PROJECT_ID
```
Ersetzen Sie PROJECT_ID durch einen Namen für das Google Cloud -Projekt, das Sie erstellen.
Wählen Sie das von Ihnen erstellte Google Cloud Projekt aus:
```
gcloud config set project PROJECT_ID
```
Ersetzen Sie PROJECT_ID durch den Namen Ihres Projekts in Google Cloud .

Prüfen Sie, ob für Ihr Google Cloud Projekt die Abrechnung aktiviert ist.

Aktivieren Sie die APIs Cloud Logging, Cloud Monitoring, Cloud Trace und Telemetry:

Rollen, die zum Aktivieren von APIs erforderlich sind

Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Weitere Informationen zum Zuweisen von Rollen

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

Installieren Sie die Google Cloud CLI.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

gcloud init

Erstellen Sie ein Google Cloud Projekt oder wählen Sie eines aus.

Rollen, die zum Auswählen oder Erstellen eines Projekts erforderlich sind

Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können jedes Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Projektersteller“ (roles/resourcemanager.projectCreator), die die Berechtigung resourcemanager.projects.create enthält. Weitere Informationen zum Zuweisen von Rollen

So erstellen Sie ein Google Cloud -Projekt:
```
gcloud projects create PROJECT_ID
```
Ersetzen Sie PROJECT_ID durch einen Namen für das Google Cloud -Projekt, das Sie erstellen.
Wählen Sie das von Ihnen erstellte Google Cloud Projekt aus:
```
gcloud config set project PROJECT_ID
```
Ersetzen Sie PROJECT_ID durch den Namen Ihres Projekts in Google Cloud .

Prüfen Sie, ob für Ihr Google Cloud Projekt die Abrechnung aktiviert ist.

Aktivieren Sie die APIs Cloud Logging, Cloud Monitoring, Cloud Trace und Telemetry:

Rollen, die zum Aktivieren von APIs erforderlich sind

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

Wenn Sie das Beispiel in Cloud Shell, auf Google Cloud-Ressourcen oder in einer lokalen Entwicklungsumgebung ausführen, reichen die in diesem Abschnitt aufgeführten Berechtigungen aus. Bei Produktionsanwendungen werden die Anmeldedaten zum Schreiben von Log-, Messwert- und Tracedaten in der Regel von einem Dienstkonto bereitgestellt.

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 schreiben kann:
- Log-Autor (roles/logging.logWriter)
- Monitoring-Messwert-Autor (roles/monitoring.metricWriter)
- Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)
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:
- 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.

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

Führen Sie die folgenden Schritte aus, um Ihre Anwendung so zu instrumentieren, dass Trace- und Messwertdaten erfasst und strukturiertes JSON in die Standardausgabe geschrieben wird, wie in den folgenden Abschnitten dieses Dokuments beschrieben:

OpenTelemetry konfigurieren
Strukturiertes Logging konfigurieren

OpenTelemetry konfigurieren

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

Das folgende Codebeispiel zeigt ein Python-Modul zum Einrichten von OpenTelemetry. Wenn Sie das vollständige Beispiel sehen möchten, klicken Sie auf Mehr und wählen Sie dann Auf GitHub ansehen aus.

def setup_opentelemetry() -> None:
    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()}",
        }
    )
    # Set up OpenTelemetry Python SDK
    tracer_provider = TracerProvider(resource=resource)
    tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
    trace.set_tracer_provider(tracer_provider)

    logger_provider = LoggerProvider(resource=resource)
    logger_provider.add_log_record_processor(BatchLogRecordProcessor(OTLPLogExporter()))
    logs.set_logger_provider(logger_provider)

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

Die Flask-App verwendet Gunicorn, um HTTP-Anfragen gemäß den Empfehlungen im Leitfaden zur Bereitstellung in der Produktion von Flask zu verarbeiten. Gunicorn startet mehrere Kopien Ihrer App, die in unabhängigen Worker-Prozessen ausgeführt werden, um den Durchsatz zu erhöhen. Damit sich die Messwerte aus den Worker-Prozessen nicht gegenseitig beeinträchtigen, empfehlen wir, dass jeder Worker-Prozess einen eindeutigen Wert für das Ressourcenattribut service.instance.id festlegt. Eine Möglichkeit dazu ist, die Prozess-ID in 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 App so, dass JSON-formatierte Logs mit Schlüsseln, die Trace-Informationen enthalten, in die Standardausgabe geschrieben werden. Das folgende Codebeispiel zeigt, wie Sie die Standardbibliothek logging für die Ausgabe strukturierter JSON-Logs mit der Bibliothek python-json-logger konfigurieren und wie Sie das Paket opentelemetry-instrumentation-logging verwenden, um Trace-Informationen einzufügen.

class JsonFormatter(jsonlogger.JsonFormatter):
    def formatTime(self, record: logging.LogRecord, datefmt: Optional[str] = None):
        # Format the timestamp as RFC 3339 with microsecond precision
        isoformat = datetime.fromtimestamp(record.created).isoformat()
        return f"{isoformat}Z"


def setup_structured_logging() -> None:
    LoggingInstrumentor().instrument()

    log_handler = logging.StreamHandler()
    formatter = 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",
        },
    )
    log_handler.setFormatter(formatter)
    logging.basicConfig(
        level=logging.INFO,
        handlers=[log_handler],
    )

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 Instrumentierung in der Beispielanwendung verwendet anbieterneutrale Formate wie JSON für Logdaten und OTLP für Messwert- und Trace-Daten. Die Beispielanwendung verwendet auch Flask, um HTTP-Anfragen zu verarbeiten, und die requests-Bibliothek, um HTTP-Anfragen zu stellen. Der OpenTelemetry-Collector sendet Log- und Messwertdaten mithilfe von Google-Exportern an Ihr Projekt. Die Tracedaten werden mit der Telemetry API, die OTLP verwendet, an Ihr Projekt gesendet.

Um Messwerte und Traces für den HTTP-Client und -Server zu generieren, werden in der Beispiel-App die Instrumentierungsbibliotheken opentelemetry-instrumentation-flask und opentelemetry-instrumentation-requests installiert:

logger = logging.getLogger(__name__)

# Initialize OpenTelemetry Python SDK and structured logging
setup_opentelemetry()
setup_structured_logging()

app = Flask(__name__)

# Add instrumentation
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."""
    sub_requests = randint(3, 7)
    logger.info("handle /multi request", extra={"subRequests": sub_requests})
    for _ in range(sub_requests):
        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)
    logger.info("handle /single request", extra={"duration": duration})
    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 das auf der Seite des Metrics Explorer auf:
Zu Metrics Explorer

Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Monitoring ist.
Wählen Sie in der Symbolleiste der Google Cloud Console Ihr Projekt von Google Cloud aus. Wählen Sie für App Hub-Konfigurationen das App Hub-Hostprojekt oder das Verwaltungsprojekt des für Apps aktivierten Ordners aus.
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.
Verwenden Sie das Element Filter, um Filter hinzuzufügen, mit denen Zeitreihen aus den Abfrageergebnissen entfernt werden.
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

Es kann einige Minuten dauern, bis Ihre Tracedaten verfügbar sind. Wenn beispielsweise Trace-Daten in Ihrem Projekt eingehen, muss Google Cloud Observability möglicherweise eine Datenbank zum Speichern dieser Daten erstellen. Das Erstellen der Datenbank kann einige Minuten dauern. In dieser Zeit sind keine Tracedaten verfügbar.

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 Tabellenbereich der Seite eine Zeile mit dem Spannen-Namen /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 das und 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 Logging 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.

Ihre Protokolldaten sind möglicherweise einige Minuten vor Ihren Tracedaten verfügbar. Wenn beim Aufrufen von Trace-Daten ein Fehler auftritt, entweder durch Suchen nach einem Trace anhand der ID oder durch Ausführen der Schritte in dieser Aufgabe, warten Sie ein bis zwei Minuten und versuchen Sie es noch einmal.

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