Application Real-Time Monitoring Service:Report trace data from PHP applications through OpenTelemetry

Obtenir un endpoint

1. Connectez-vous à la console ARMS.

2. Dans le volet de navigation de gauche, cliquez sur Integration Center.

3. Dans la section Server-side Applications, cliquez sur la carte OpenTelemetry.

4. Dans le panneau OpenTelemetry, cliquez sur l'onglet Start Integration et sélectionnez une région.

   Lorsque vous accédez à une région pour la première fois, les ressources y sont automatiquement initialisées.

5. Définissez Connection Type et Export Protocol, puis copiez l'endpoint.

   Paramètre	Options	Conseils
   Connection Type	Alibaba Cloud VPC Network, Public Network	Utilisez VPC si votre service s'exécute dans la même région Alibaba Cloud. Sinon, utilisez Public Network.
   Export Protocol	HTTP (recommandé), gRPC	Choisissez en fonction de la prise en charge du protocole par votre client.

   

Étape 1 : Créer l'application

1. Initialisez le projet :

      mkdir <project-name> && cd <project-name>

      composer init \
        --no-interaction \
        --stability beta \
        --require slim/slim:"^4" \
        --require slim/psr7:"^1"
      composer update

2. Créez un fichier index.php dans le répertoire du projet :

      <?php
      use Psr\Http\Message\ResponseInterface as Response;
      use Psr\Http\Message\ServerRequestInterface as Request;
      use Slim\Factory\AppFactory;
   
      require __DIR__ . '/vendor/autoload.php';
   
      $app = AppFactory::create();
   
      $app->get('/rolldice', function (Request $request, Response $response) {
          $result = random_int(1,6);
          $response->getBody()->write(strval($result));
          return $response;
      });
   
      $app->run();

3. Vérifiez que l'application s'exécute : ouvrez http://localhost:8080/rolldice dans un navigateur. Vous devriez voir un nombre aléatoire entre 1 et 6.

      php -S localhost:8080

Étape 2 : Compiler l'extension PHP OpenTelemetry

1. Installez les dépendances de compilation :

   • macOS :

     brew install gcc make autoconf

   • Linux (apt) :

     sudo apt-get install gcc make autoconf

2. Compilez et installez l'extension avec PECL. Une compilation réussie se termine par une sortie similaire à :

      pecl install opentelemetry

      Build process completed successfully
      Installing '/opt/homebrew/Cellar/php/8.2.8/pecl/20220829/opentelemetry.so'
      install ok: channel://pecl.php.net/opentelemetry-1.0.0beta6
      Extension opentelemetry enabled in php.ini

3. (Facultatif) Si la sortie n'inclut pas Extension opentelemetry enabled in php.ini, ajoutez manuellement l'extension à votre fichier php.ini :

      [opentelemetry]
      extension=opentelemetry.so

4. Vérifiez que l'extension est chargée. Sortie attendue :

      php -m | grep opentelemetry

      opentelemetry

   Vous pouvez également exécuter php --ri opentelemetry pour obtenir des informations détaillées sur l'extension :

      opentelemetry
      opentelemetry support => enabled
      extension version => 1.0.0beta6

Étape 3 : Installer les dépendances d'instrumentation

# Install the gRPC extension (may take several minutes)
pecl install grpc

composer config allow-plugins.php-http/discovery false
composer require \
  open-telemetry/sdk \
  open-telemetry/opentelemetry-auto-slim \
  open-telemetry/exporter-otlp \
  php-http/guzzle7-adapter \
  open-telemetry/transport-grpc

Étape 4 : Exécuter l'application instrumentée

Démarrez l'application avec des variables d'environnement qui configurent le SDK OpenTelemetry :

env OTEL_PHP_AUTOLOAD_ENABLED=true \
    OTEL_SERVICE_NAME=<your-service-name> \
    OTEL_TRACES_EXPORTER=otlp \
    OTEL_METRICS_EXPORTER=none \
    OTEL_LOGS_EXPORTER=none \
    OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
    OTEL_EXPORTER_OTLP_ENDPOINT=<endpoint> \
    OTEL_EXPORTER_OTLP_HEADERS=Authentication=<token> \
    OTEL_PROPAGATORS=baggage,tracecontext \
    php -S localhost:8080

Remplacez les espaces réservés suivants par vos valeurs :

Vérification

1. Ouvrez http://localhost:8080/rolldice dans un navigateur. Chaque requête génère automatiquement une trace.

2. Connectez-vous à la console Managed Service for OpenTelemetry.

3. Sur la page Applications, recherchez votre application et cliquez sur son nom pour afficher les traces.

L'affichage des traces dans la console peut prendre quelques minutes. Si les traces n'apparaissent toujours pas, vérifiez que l'extension OpenTelemetry est chargée ( php -m | grep opentelemetry ) et que votre endpoint et votre jeton sont corrects.

Étape 1 : Créer l'application

Suivez les mêmes étapes que dans la section Instrumentation automatique > Étape 1 pour créer l'application de lancer de dés basée sur Slim.

Étape 2 : Installer les dépendances du SDK OpenTelemetry

Installez la bibliothèque de client HTTP et les packages du SDK OpenTelemetry. Choisissez l'onglet correspondant à votre protocole d'exportation.

composer require guzzlehttp/guzzle

composer require \
  open-telemetry/sdk \
  open-telemetry/exporter-otlp

# Install the gRPC extension if not already installed
pecl install grpc
composer require open-telemetry/transport-grpc

composer require guzzlehttp/guzzle

composer require \
  open-telemetry/sdk \
  open-telemetry/exporter-otlp

Étape 3 : Écrire le code d'initialisation

Créez un fichier opentelemetry_util.php dans le même répertoire que index.php. Ce fichier configure le TracerProvider, l'exportateur et l'échantillonneur.

<?php
use OpenTelemetry\API\Common\Instrumentation\Globals;
use OpenTelemetry\API\Trace\Propagation\TraceContextPropagator;
use OpenTelemetry\Contrib\Otlp\SpanExporter;
use OpenTelemetry\SDK\Common\Attribute\Attributes;
use OpenTelemetry\SDK\Common\Export\Stream\StreamTransportFactory;
use OpenTelemetry\SDK\Resource\ResourceInfo;
use OpenTelemetry\SDK\Resource\ResourceInfoFactory;
use OpenTelemetry\SDK\Sdk;
use OpenTelemetry\SDK\Trace\Sampler\AlwaysOnSampler;
use OpenTelemetry\SDK\Trace\Sampler\ParentBased;
use OpenTelemetry\SDK\Trace\SpanProcessor\SimpleSpanProcessor;
use OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessorBuilder;
use OpenTelemetry\SDK\Trace\TracerProvider;
use OpenTelemetry\SemConv\ResourceAttributes;
use OpenTelemetry\Contrib\Grpc\GrpcTransportFactory;
use OpenTelemetry\Contrib\Otlp\OtlpUtil;
use OpenTelemetry\API\Signals;

function initOpenTelemetry()
{
    // 1. Define the service resource
    $resource = ResourceInfoFactory::emptyResource()->merge(ResourceInfo::create(Attributes::create([
        ResourceAttributes::SERVICE_NAME => '<your-service-name>',  // Required
        ResourceAttributes::HOST_NAME => '<your-host-name>'         // Optional
    ])));

    // 2. Create a SpanExporter that sends data over gRPC
    $headers = [
        'Authentication' => '<your-token>',
    ];
    $transport = (new GrpcTransportFactory())->create(
        '<grpc-endpoint>' . OtlpUtil::method(Signals::TRACE),
        'application/x-protobuf',
        $headers
    );
    $spanExporter = new SpanExporter($transport);

    // 3. Build and register the global TracerProvider
    $tracerProvider = TracerProvider::builder()
        ->addSpanProcessor(
            (new BatchSpanProcessorBuilder($spanExporter))->build()
        )
        ->setResource($resource)
        ->setSampler(new ParentBased(new AlwaysOnSampler()))
        ->build();

    Sdk::builder()
        ->setTracerProvider($tracerProvider)
        ->setPropagator(TraceContextPropagator::getInstance())
        ->setAutoShutdown(true)   // Flush pending spans on shutdown
        ->buildAndRegisterGlobal();
}
?>

<?php
use OpenTelemetry\API\Common\Instrumentation\Globals;
use OpenTelemetry\API\Trace\Propagation\TraceContextPropagator;
use OpenTelemetry\Contrib\Otlp\SpanExporter;
use OpenTelemetry\SDK\Common\Attribute\Attributes;
use OpenTelemetry\SDK\Common\Export\Stream\StreamTransportFactory;
use OpenTelemetry\SDK\Resource\ResourceInfo;
use OpenTelemetry\SDK\Resource\ResourceInfoFactory;
use OpenTelemetry\SDK\Sdk;
use OpenTelemetry\SDK\Trace\Sampler\AlwaysOnSampler;
use OpenTelemetry\SDK\Trace\Sampler\ParentBased;
use OpenTelemetry\SDK\Trace\SpanProcessor\SimpleSpanProcessor;
use OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessorBuilder;
use OpenTelemetry\SDK\Trace\TracerProvider;
use OpenTelemetry\SemConv\ResourceAttributes;
use OpenTelemetry\Contrib\Otlp\OtlpHttpTransportFactory;
use OpenTelemetry\SDK\Common\Export\TransportFactoryInterface;

function initOpenTelemetry()
{
    // 1. Define the service resource
    $resource = ResourceInfoFactory::emptyResource()->merge(ResourceInfo::create(Attributes::create([
        ResourceAttributes::SERVICE_NAME => '<your-service-name>',  // Required
        ResourceAttributes::HOST_NAME => '<your-host-name>'         // Optional
    ])));

    // 2. Create a SpanExporter that sends data over HTTP
    $transport = (new OtlpHttpTransportFactory())->create(
        '<http-endpoint>',
        'application/x-protobuf'
    );
    $spanExporter = new SpanExporter($transport);

    // 3. Build and register the global TracerProvider
    $tracerProvider = TracerProvider::builder()
        ->addSpanProcessor(
            (new BatchSpanProcessorBuilder($spanExporter))->build()
        )
        ->setResource($resource)
        ->setSampler(new ParentBased(new AlwaysOnSampler()))
        ->build();

    Sdk::builder()
        ->setTracerProvider($tracerProvider)
        ->setPropagator(TraceContextPropagator::getInstance())
        ->setAutoShutdown(true)   // Flush pending spans on shutdown
        ->buildAndRegisterGlobal();
}
?>

Étape 4 : Ajouter l'instrumentation à l'application

Mettez à jour index.php pour initialiser OpenTelemetry et créer des spans.

1. Importez les packages requis et initialisez OpenTelemetry au début de index.php :

      <?php
      use OpenTelemetry\API\Common\Instrumentation\Globals;
      use OpenTelemetry\SDK\Common\Attribute\Attributes;
      use OpenTelemetry\SDK\Trace\TracerProvider;
   
      require __DIR__ . '/opentelemetry_util.php';
   
      // Initialize OpenTelemetry: configure service name, exporter, and global TracerProvider
      initOpenTelemetry();

2. Créez un span dans la route /rolldice pour capturer le traçage au niveau de la requête :

      $app->get('/rolldice', function (Request $request, Response $response) {
          // Get a tracer instance
          $tracer = \OpenTelemetry\API\Globals::tracerProvider()->getTracer('my-tracer');
   
          // Start a span for this operation
          $span = $tracer->spanBuilder("/rolldice")->startSpan();
          $span->setAttribute("http.method", "GET");
          $span->addEvent("Init");
   
          // Configure events with attributes
          $eventAttributes = Attributes::create([
              "key1" => "value",
              "key2" => 3.14159,
          ]);
   
          // Business logic
          $result = random_int(1,6);
          $response->getBody()->write(strval($result));
   
          $span->addEvent("End");
          $span->end();
   
          return $response;
      });

3. Créez des spans imbriqués pour tracer les opérations en plusieurs étapes. La route /rolltwodices suivante illustre une relation parent-enfant entre les spans :

      $app->get('/rolltwodices', function (Request $request, Response $response) {
          $tracer = \OpenTelemetry\API\Globals::tracerProvider()->getTracer('my-tracer');
   
          // Create a parent span
          $parentSpan = $tracer->spanBuilder("/rolltwodices/parent")->startSpan();
          $scope = $parentSpan->activate();
   
          $value1 = random_int(1,6);
   
          // Create a child span within the parent scope
          $childSpan = $tracer->spanBuilder("/rolltwodices/parent/child")->startSpan();
   
          // Business logic
          $value2 = random_int(1,6);
          $result = "dice1: " . $value1 . ", dice2: " . $value2;
   
          // End spans and detach scope
          $childSpan->end();
          $parentSpan->end();
          $scope->detach();
   
          $response->getBody()->write(strval($result));
          return $response;
      });

4. Enregistrez les exceptions sur les spans. La route /error suivante illustre la gestion des erreurs :

      $app->get('/error', function (Request $request, Response $response) {
          $tracer = \OpenTelemetry\API\Globals::tracerProvider()->getTracer('my-tracer');
          $span3 = $tracer->spanBuilder("/error")->startSpan();
   
          try {
              // Simulate an exception
              throw new \Exception('exception!');
          } catch (\Throwable $t) {
              // Mark the span as an error
              $span3->setStatus(\OpenTelemetry\API\Trace\StatusCode::STATUS_ERROR, "exception in span3!");
              // Record the exception with stack trace
              $span3->recordException($t, ['exception.escaped' => true]);
          } finally {
              $span3->end();
              $response->getBody()->write("error");
              return $response;
          }
      });

Étape 5 : Exécuter et vérifier

1. Démarrez l'application :

      php -S localhost:8080

2. Envoyez des requêtes pour générer des données de trace :

      http://localhost:8080/rolldice
      http://localhost:8080/rolltwodices
      http://localhost:8080/error

3. Connectez-vous à la console Managed Service for OpenTelemetry. Sur la page Applications, recherchez votre application et cliquez sur son nom pour afficher les traces.

L'affichage des traces dans la console peut prendre quelques minutes. Si les traces n'apparaissent toujours pas, vérifiez que votre endpoint et votre jeton sont corrects, et que votre serveur peut atteindre l'endpoint via le réseau.