Application Real-Time Monitoring Service:Laporkan data jejak dari aplikasi PHP melalui OpenTelemetry

Langkah 1: Buat aplikasi

1. Inisialisasi proyek:

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

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

2. Buat file index.php di direktori proyek:

      <?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. Verifikasi aplikasi berjalan: Buka http://localhost:8080/rolldice di browser. Anda seharusnya melihat bilangan acak antara 1 dan 6.

      php -S localhost:8080

Langkah 2: Bangun ekstensi OpenTelemetry PHP

1. Instal dependensi build:

   • macOS:

     brew install gcc make autoconf

   • Linux (apt):

     sudo apt-get install gcc make autoconf

2. Bangun dan instal ekstensi dengan PECL. Build yang berhasil akan menghasilkan output seperti berikut:

      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. (Opsional) Jika output tidak menyertakan Extension opentelemetry enabled in php.ini, tambahkan ekstensi tersebut secara manual ke file php.ini Anda:

      opentelemetry
      dukungan opentelemetry => diaktifkan
      versi ekstensi => 1.0.0beta6

4. Verifikasi bahwa ekstensi telah dimuat. Output yang diharapkan adalah sebagai berikut. Atau, jalankan php --ri opentelemetry untuk informasi detail mengenai ekstensi:

      php -m | grep opentelemetry

      opentelemetry

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

Langkah 3: Instal dependensi instrumentasi

# Instal ekstensi gRPC (mungkin memakan waktu beberapa menit)
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

Langkah 4: Jalankan aplikasi yang telah di-instrumentasi

Jalankan aplikasi dengan variabel lingkungan yang mengonfigurasi 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

Ganti placeholder berikut dengan nilai Anda:

Verifikasi

1. Buka http://localhost:8080/rolldice di browser. Setiap permintaan akan menghasilkan jejak secara otomatis.

2. Masuk ke atau Konsol Managed Service for OpenTelemetry.

3. Di halaman Applications, temukan aplikasi Anda dan klik namanya untuk melihat jejak.

Mungkin diperlukan beberapa menit hingga jejak muncul di konsol. Jika jejak masih belum muncul, verifikasi bahwa ekstensi OpenTelemetry telah dimuat (php -m | grep opentelemetry) serta titik akhir dan token Anda benar.

Langkah 1: Buat aplikasi

Ikuti langkah-langkah yang sama seperti pada bagian Instrumentasi otomatis > Langkah 1 untuk membuat aplikasi pelempar dadu berbasis Slim.

Langkah 2: Instal dependensi SDK OpenTelemetry

Instal library client HTTP dan paket SDK OpenTelemetry. Pilih tab yang sesuai dengan protokol ekspor Anda.

composer require guzzlehttp/guzzle

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

# Instal ekstensi gRPC jika belum terinstal
pecl install grpc
composer require open-telemetry/transport-grpc

composer require guzzlehttp/guzzle

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

Langkah 3: Tulis kode inisialisasi

Buat file opentelemetry_util.php di direktori yang sama dengan index.php. File ini mengatur TracerProvider, exporter, dan sampler.

<?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. Tentukan Sumber daya layanan
    $resource = ResourceInfoFactory::emptyResource()->merge(ResourceInfo::create(Attributes::create([
        ResourceAttributes::SERVICE_NAME => '<your-service-name>',  // Wajib
        ResourceAttributes::HOST_NAME => '<your-host-name>'         // Opsional
    ])));

    // 2. Buat SpanExporter yang mengirim data melalui HTTP
    $transport = (new OtlpHttpTransportFactory())->create(
        '<http-endpoint>',
        'application/x-protobuf'
    );
    $spanExporter = new SpanExporter($transport);

    // 3. Bangun dan daftarkan TracerProvider global
    $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)   // Mengosongkan rentang yang tertunda saat mematikan
        ->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();
}
?>

Langkah 4: Tambahkan instrumentasi ke aplikasi

Perbarui index.php untuk menginisialisasi OpenTelemetry dan membuat rentang.

1. Impor paket yang diperlukan dan inisialisasi OpenTelemetry di bagian atas 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. Buat rentang di rute /rolldice untuk menangkap pelacakan tingkat permintaan:

      $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. Buat rentang bersarang untuk melacak operasi multi-langkah. Rute /rolltwodices berikut menunjukkan hubungan rentang induk-anak:

      $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. Catat exception pada rentang. Rute /error berikut menunjukkan penanganan error:

      $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;
          }
      });

Langkah 5: Jalankan dan verifikasi

1. Jalankan aplikasi:

      php -S localhost:8080

2. Kirim permintaan untuk menghasilkan data jejak:

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

3. Masuk ke atau Konsol Managed Service for OpenTelemetry. Di halaman Applications, temukan aplikasi Anda dan klik namanya untuk melihat jejak.

Mungkin diperlukan beberapa menit hingga jejak muncul di konsol. Jika jejak masih belum muncul, verifikasi bahwa titik akhir dan token Anda benar serta server Anda dapat menjangkau titik akhir melalui jaringan.