Configurer Cloud Trace pour PHP

Vous pouvez activer Cloud Trace pour les applications PHP à l'aide d'OpenCensus. OpenCensus est un ensemble de bibliothèques d'instrumentation permettant de collecter des données de trace et de métrique compatibles avec plusieurs backends. Pour obtenir les dernières informations sur OpenCensus pour PHP, ainsi que de la documentation supplémentaire et des exemples, consultez la page opencensus-php-exporter-stackdriver.

Installer la bibliothèque

  1. Installez le package du compositeur d'exportateur OpenCensus Stackdriver :

    composer require opencensus/opencensus-exporter-stackdriver

    La commande précédente installe également les packages combinés d'OpenCensus et Trace.

  2. Pour utiliser les intégrations de framework décrites dans une section ultérieure de cette page, installez l'extension OpenCensus :

    pecl install opencensus-alpha

  3. Ajoutez la ligne suivante à votre fichier php.ini :

    extension=opencensus.so

  4. Sous Windows, téléchargez le fichier DLL depuis la page de téléchargement pecl dans le répertoire de votre installation PHP, puis ajoutez la ligne suivante à votre fichier php.ini :

    extension=opencensus.dll

Configurer le client

Pour activer la bibliothèque OpenCensus pour PHP, procédez comme suit :

  1. Importez les classes obligatoires :

    use OpenCensus\Trace\Exporter\StackdriverExporter;
use OpenCensus\Trace\Tracer;

  2. Initialisez l'objet StackdriverExporter :

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

    Si vous utilisez une infrastructure Google Cloud, vous n'avez pas besoin de définir projectId sur votre ID de projet Google Cloud. Si vous ne définissez pas ce champ, la bibliothèque cliente pour PHP collecte automatiquement ces données à partir d'un serveur de métadonnées Google Cloud.

    Si vous n'exécutez pas sur l'infrastructure Google Cloud, vous devez fournir l'ID de votre projet Google Cloud à votre application.

    Quelle que soit votre infrastructure, pour PHP, lorsque vous ne définissez pas explicitement l'ID de projet Google Cloud, la bibliothèque PHP google-cloud, appelée par OpenCensus, détermine automatiquement si la variable d'environnement GOOGLE_CLOUD_PROJECT est défini. Si tel est le cas, la bibliothèque utilise la valeur de GOOGLE_CLOUD_PROJECT comme ID de votre projet Google Cloud. Pour en savoir plus, consultez la section Authentification. Pour définir la variable d'environnement, procédez comme suit :

    Linux ou 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. Démarrez le traceur :

    Tracer::start($exporter);

Créez l'exportateur et démarrez le traceur dès que possible dans votre application.

Personnalisations

Vous pouvez personnaliser le comportement de la bibliothèque Cloud Trace pour PHP. Pour obtenir la liste des options de configuration de l'exportateur, accédez à opencensus-php-exporter-stackdriver ou à l'API OpenCensus PHP.

L'environnement flexible App Engine vous permet de réduire l'impact sur les performances des rapports de données de trace en envoyant les données par un processus en arrière-plan. Pour activer la création de rapports en arrière-plan, procédez comme suit :

  1. Modifiez la section runtime_config de votre fichier app.yaml pour spécifier l'indicateur enable_stackdriver_integration :

    enable_stackdriver_integration: true

    Cette option entraîne la génération du daemon de traitement par lot PHP, BatchRunner.

  2. Définissez la variable d'environnement IS_BATCH_DAEMON_RUNNING sur true.

  3. Incluez l'option async avec la valeur définie sur true dans les options clientConfig transmises à l'option OpenCensus StackdriverExporter. Pour en savoir plus, consultez StackdriverExporter.

Ajouter un délai de trace personnalisé

La bibliothèque Cloud Trace pour PHP crée automatiquement un enregistrement de trace pour chaque requête HTTP. Vous pouvez également ajouter des délais de trace personnalisés dans la requête :

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

Intégration pour les frameworks

La bibliothèque OpenCensus offre des intégrations utiles pour les frameworks et les fonctions Web. Pour en savoir plus, consultez les intégrations disponibles et les exemples pour certains frameworks.

Configurer votre plate-forme

Vous pouvez utiliser Cloud Trace sur Google Cloud et d'autres plates-formes.

Exécuter des applications sur Google Cloud

Lorsque votre application s'exécute sur Google Cloud, vous n'avez pas besoin de fournir des identifiants d'authentification sous la forme d'un compte de service à la bibliothèque cliente. Cependant, vous devez vous assurer que le niveau d'accès de l'API Cloud Trace est activé sur votre plate-forme Google Cloud.

Pour obtenir la liste des environnements Google Cloud compatibles, consultez la page Environnements compatibles.

Pour les configurations suivantes, les paramètres de niveau d'accès par défaut activent l'API Cloud Trace :

  • Environnement flexible App Engine

  • Environnement standard App Engine

  • Google Kubernetes Engine (GKE)

  • Compute Engine

  • Cloud Run

Si vous utilisez des champs d'application d'accès personnalisés, vous devez vous assurer que le niveau d'accès à l'API Cloud Trace est activé:

  • Pour savoir comment configurer les niveaux d'accès pour votre environnement à l'aide de Google Cloud Console, consultez la page Configurer votre projet Google Cloud.

  • Pour les utilisateurs gcloud, spécifiez les niveaux d'accès à l'aide de l'option --scopes et incluez les champs d'application d'accès à l'API Cloud Trace trace.append. Par exemple, pour créer un cluster GKE avec uniquement l'API Cloud Trace activée, procédez comme suit :

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

Exécuter en local et depuis un autre emplacement

Si votre application s'exécute en dehors de Google Cloud, vous devez fournir les identifiants d'authentification sous la forme d'un compte de service à la bibliothèque cliente. Le compte de service doit contenir le rôle d'agent Cloud Trace. Pour savoir comment faire, consultez la page Créer un compte de service.

Les bibliothèques clientes Google Cloud utilisent les identifiants par défaut de l'application (ADC) pour trouver les identifiants de votre application. Vous fournissez ces identifiants en définissant la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS :

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"

Afficher les traces

Après le déploiement, vous pouvez afficher les traces dans la visionneuse de traces de Cloud Console.

Accéder à la page Lecteur de traces

Dépannage

Pour en savoir plus sur la résolution des problèmes liés à Cloud Trace, consultez la page Dépannage.

Ressources