Cloud Trace für PHP einrichten

Sie können Cloud Trace für PHP-Anwendungen mit OpenCensus aktivieren. OpenCensus ist eine Sammlung von Instrumentenbibliotheken zum Erfassen von Trace- und Messwertdaten, die mit mehreren Back-Ends funktionieren. Die neuesten Informationen zu OpenCensus für PHP sowie weitere Dokumentation und Beispiele finden Sie unter opencensus-php-exporter-stackdriver.

Bibliothek installieren

  1. Installieren Sie das OpenCensus-Stackdriver-Exporter-Composer-Paket:

    composer require opencensus/opencensus-exporter-stackdriver
    

    Mit dem vorherigen Befehl werden auch die OpenCensus- und Trace-Composer-Pakete installiert.

  2. Installieren Sie die OpenCensus-Erweiterung, um die in einem späteren Abschnitt auf dieser Seite erläuterten Framework-Integrationen zu nutzen:

    pecl install opencensus-alpha
    
  3. Fügen Sie der Datei php.ini die folgende Zeile hinzu:

    extension=opencensus.so
    
  4. Wenn Sie mit Windows arbeiten, laden Sie von der pecl-Downloadseite die DLL-Datei in das Erweiterungsverzeichnis Ihrer PHP-Installation herunter und fügen Sie die folgende Zeile in die Datei php.ini ein:

    extension=opencensus.dll
    

Client konfigurieren

Führen Sie folgende Schritte aus, um die OpenCensus-Bibliothek für PHP zu aktivieren:

  1. Importieren Sie die erforderlichen Klassen:

    use OpenCensus\Trace\Exporter\StackdriverExporter;
    use OpenCensus\Trace\Tracer;
    
  2. Initialisieren Sie das StackdriverExporter-Objekt.

    $exporter = new StackdriverExporter([
        'clientConfig' => [
            'projectId' => $projectId
        ]
    ]);

    Wenn Sie mit der Google Cloud-Infrastruktur arbeiten, müssen Sie projectId nicht auf Ihre Google Cloud-Projekt-ID festsetzen. Wenn Sie dieses Feld nicht festlegen, erfasst die Clientbibliothek für PHP diese Daten automatisch von einem Google Cloud-Metadatenserver.

    Wenn Sie nicht die Google Cloud-Infrastruktur ausführen, müssen Sie Ihre Google Cloud-Projekt-ID für Ihre Anwendung angeben.

    Wenn Sie die Google Cloud-Projekt-ID nicht explizit festlegen, ermittelt die PHP-Bibliothek google-cloud, die von OpenCensus aufgerufen wird, unabhängig von Ihrer Infrastruktur automatisch, ob die Umgebungsvariable Wenn GOOGLE_CLOUD_PROJECT festgelegt ist, verwendet die Bibliothek den Wert von GOOGLE_CLOUD_PROJECT als Google Cloud-Projekt-ID. Weitere Informationen finden Sie unter Authentifizierung. So legen Sie die Umgebungsvariable fest:

    Linux oder macOS

    export GOOGLE_CLOUD_PROJECT=your-project-id

    Windows

    set GOOGLE_CLOUD_PROJECT=your-project-id

    PowerShell:

    $env:GOOGLE_CLOUD_PROJECT="your-project-id"
  3. Starten Sie den Tracer:

    Tracer::start($exporter);

Erstellen Sie den Exporter und starten Sie den Tracer in Ihrer Anwendung so früh wie möglich.

Anpassungen

Sie können das Verhalten der Cloud Trace-Bibliothek für PHP anpassen. Eine Liste der Konfigurationsoptionen für den Exporter finden Sie unter opencensus-php-exporter-stackdriver oder OpenCensus PHP API.

Mit der flexiblen App Engine-Umgebung können Sie die Auswirkungen auf die Leistung bei der Berichterstellung von Trace-Daten reduzieren, indem die Daten von einem Hintergrundprozess gesendet werden. So aktivieren Sie Hintergrundberichte:

  1. Ändern Sie den Abschnitt runtime_config der Datei app.yaml, um das Flag enable_stackdriver_integration anzugeben:

    enable_stackdriver_integration: true

    Dieses Flag bewirkt, dass der PHP-Batchverarbeitungs-Daemon BatchRunner erstellt wird.

  2. Setzen Sie die Umgebungsvariable IS_BATCH_DAEMON_RUNNING auf true.

  3. Fügen Sie die Option async mit dem Wert true in die clientConfig-Optionen ein, die an OpenCensus StackdriverExporter übergeben werden. Weitere Informationen finden Sie unter StackdriverExporter.

Benutzerdefinierten Trace-Span hinzufügen

Die Cloud Trace-Bibliothek für PHP erstellt automatisch einen Trace-Eintrag für jede HTTP-Anfrage. Sie können innerhalb der Anfrage auch benutzerdefinierte Trace-Spans hinzufügen:

Tracer::inSpan(
    ['name' => 'slow_function'],
    function () {
        sleep(1);
    }
);

Framework-Integrationen

Die OpenCensus-Bibliothek bietet nützliche Integrationen für Web-Frameworks und -Funktionen. Weitere Informationen finden Sie in den verfügbaren Integrationen und Beispielen für einige Frameworks.

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, müssen Sie dafür sorgen, dass der Zugriffsbereiche der Cloud Trace API aktiviert ist:

  • 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 Zugriffsbereiche mit dem Flag --scopes an und fügen Sie den Zugriffsbereich trace.append der Cloud Trace API hinzu. 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 geben diese Anmeldedaten an, indem Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS festlegen:

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 im Trace Viewer der Cloud Console anzeigen.

Trace-Anzeige öffnen

Fehlerbehebung

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

Ressourcen