PHP

---
title     : 'OpenTelemetry PHP'
summary   : 'OpenTelemetry PHP の自動インスツルメンテーションにより、コードを変更せずに Guance で可観測性データを収集します'
tags      :
  - 'PHP'
  - 'OpenTelemetry'
  - '分散型トレーシング'
  - 'APM'
__int_icon: 'icon/opentelemetry'
---

# OpenTelemetry PHP

OpenTelemetry PHP は、PHP 拡張機能による実行時フックと、Composer でインストールしたフレームワーク用インスツルメンテーションライブラリを組み合わせてテレメトリデータを生成します。ビジネスロジックを変更することなく、サポート対象の Web フレームワーク、HTTP クライアント、データベースなどの呼び出しを収集できます。

このドキュメントでは、DataKit の OpenTelemetry コレクターを使用して OTLP データを受信し、Guance に転送する手順を説明します。

```text
PHP アプリケーション + OpenTelemetry 拡張機能/インスツルメンテーションライブラリ -> OTLP -> DataKit -> Guance

前提条件¶

• PHP 8.0 以降
• Composer、および PHP 拡張機能をインストール可能な PECL またはシステムパッケージマネージャー
• アプリケーションが Composer により vendor/autoload.php を読み込んでいること
• DataKit がインストール済みで、対象の Guance ワークスペースに接続されていること
• PHP アプリケーションから DataKit へのネットワーク到達性があること：OTLP/HTTP は DataKit HTTP ポート 9529、OTLP/gRPC はデフォルトで 4317 を使用します。

一、OpenTelemetry コレクターを有効にする¶

DataKit インストールディレクトリの conf.d/opentelemetry に移動します。コレクターの設定ファイルがまだ存在しない場合は、サンプルファイルをコピーします。

cd /usr/local/datakit/conf.d/opentelemetry
sudo cp opentelemetry.conf.sample opentelemetry.conf

opentelemetry.conf に、少なくとも以下の受信設定が含まれていることを確認します。

[[inputs.opentelemetry]]
  # Guance でタグとして保持するカスタム属性をホワイトリストに追加します。
  customer_tags = ["team", "project"]

  [inputs.opentelemetry.http]
    http_status_ok = 200
    trace_api = "/otel/v1/traces"
    metric_api = "/otel/v1/metrics"
    logs_api = "/otel/v1/logs"

  [inputs.opentelemetry.grpc]
    addr = "127.0.0.1:4317"
    max_payload = 16777216

受信アドレスは次のとおりです。

PHP アプリケーションと DataKit が同一ホスト上にない場合は、実際のデプロイメントに合わせて DataKit のリッスンアドレス、ファイアウォール、その他のネットワークアクセス制御を調整する必要があります。gRPC の場合は addr をアプリケーションからアクセス可能なアドレス（例：0.0.0.0:4317）に変更します。OTLP 受信ポートをインターネットに直接公開しないでください。

DataKit を再起動し、サービスを確認します。

sudo datakit service restart
curl http://127.0.0.1:9529/v1/ping

二、アプリケーションに OpenTelemetry を導入する¶

OpenTelemetry PHP 拡張機能をインストールする¶

まず、PHP CLI のバージョンと設定ファイルの場所を確認します。

php --version
php --ini

PHP 開発環境、PECL、コンパイラ、make、autoconf を準備したら、PECL 公式リポジトリから拡張機能をインストールします。

sudo pecl install opentelemetry

PHP がスキャンする追加設定ディレクトリに 99-opentelemetry.ini を作成するか、次の設定を現在の php.ini に追加します。

[opentelemetry]
extension=opentelemetry.so

PHP-FPM、Apache、またはその他の PHP アプリケーションプロセスを再起動し、拡張機能が読み込まれたことを確認します。

php --ri opentelemetry

拡張機能だけをインストールしても Trace は自動生成されません。SDK、OTLP エクスポーター、およびアプリケーションフレームワークに対応するインスツルメンテーションパッケージもインストールする必要があります。

SDK と自動インスツルメンテーションパッケージをインストールする¶

以下は、Slim と PSR-18 HTTP クライアントを例にしています。アプリケーションの Composer プロジェクトディレクトリで次のコマンドを実行します。

composer require \
  open-telemetry/sdk \
  open-telemetry/exporter-otlp \
  open-telemetry/opentelemetry-auto-slim \
  open-telemetry/opentelemetry-auto-psr18

アプリケーションに OTLP HTTP エクスポーターで使用可能な PSR-17 Factory と非同期 HTTP Client の実装がまだない場合は、次のパッケージも追加します。

composer require php-http/guzzle7-adapter nyholm/psr7

フレームワークごとに、異なる open-telemetry/opentelemetry-auto-* パッケージをインストールする必要があります。使用しているフレームワーク、データベース、またはクライアントに一致するパッケージは、OpenTelemetry PHP インスツルメンテーションパッケージ一覧 から選択できます。対応するインスツルメンテーションパッケージがインストールされていないコンポーネントでは、Span は自動生成されません。

環境変数による起動¶

以下は、OTLP/HTTP + Protobuf を使用し、Trace のみをデフォルトで有効にし、Metric と Log は一時的に無効にする例です。

export OTEL_PHP_AUTOLOAD_ENABLED="true"
export OTEL_SERVICE_NAME="order-service"
export OTEL_RESOURCE_ATTRIBUTES="env=prod,version=1.0.0,team=backend"

export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="none"
export OTEL_LOGS_EXPORTER="none"

export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:9529/otel"
export OTEL_PROPAGATORS="tracecontext,baggage"

php -S 0.0.0.0:8080 -t public

OTEL_EXPORTER_OTLP_ENDPOINT はベースアドレスです。OTLP/HTTP エクスポーターはデータ種別に応じて自動的に /v1/traces、/v1/metrics、または /v1/logs を追加し、最終的に DataKit の /otel/v1/* ルートに対応します。

PHP-FPM、Apache、Supervisor、または systemd は、現在のターミナルの環境変数を継承しない場合があります。変数は実際のサービスプロセスの起動環境に書き込むか、次のセクションで説明する PHP 設定方法を使用し、サービスを再起動してください。

PHP 設定による有効化¶

次の内容を、PHP-FPM または Apache が実際に読み込む php.ini または追加の INI ファイルに追加することもできます。

OTEL_PHP_AUTOLOAD_ENABLED="true"
OTEL_SERVICE_NAME="order-service"
OTEL_RESOURCE_ATTRIBUTES="env=prod,version=1.0.0,team=backend"
OTEL_TRACES_EXPORTER="otlp"
OTEL_METRICS_EXPORTER="none"
OTEL_LOGS_EXPORTER="none"
OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:9529/otel"
OTEL_PROPAGATORS="tracecontext,baggage"

PHP CLI と PHP-FPM は異なる設定ファイルを読み込む可能性があります。php --ini で確認できるのは CLI の設定のみです。Web アプリケーションに導入する場合は、PHP-FPM または Apache の対応する SAPI が拡張機能と上記の設定を読み込んでいることを確認してください。

OTLP/gRPC を使用する¶

PHP で OTLP/gRPC を使用するには、追加で grpc PHP 拡張機能と Composer トランスポートパッケージが必要です。

sudo pecl install grpc
composer require open-telemetry/transport-grpc

export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:4317"

gRPC エンドポイントには /v1/traces などの HTTP パスを追加しないでください。

三、データ送信パラメータ¶

基本パラメータ¶

service.name は Guance 内でのサービス帰属に使用されます。env と version も設定することを推奨します。これにより、環境やバージョンによるフィルタリングが可能になります。その他のカスタムリソース属性をタグとして保持するには、DataKit の customer_tags ホワイトリストに追加する必要があります。属性名の . は _ に変換されます。

PHP 自動インスツルメンテーションパラメータ¶

OTLP パラメータ¶

DataKit の OTLP/HTTP コレクションは Protobuf のみをサポートしています。http/protobuf を使用し、http/json は使用しないでください。共通エンドポイントと特定のデータ種別のエンドポイントが両方存在する場合、特定のデータ種別の設定が優先されます。

サンプリングパラメータ¶

本番環境では、トラフィックとデータ予算に応じてサンプリングレートを設定してください。アプリケーション側のヘッダーサンプリングと DataKit 側のサンプリングを同時に有効にすると、最終的な保持率は乗算で低下するため、サンプリングの場所を統一して計画する必要があります。

導入の確認¶

自動インスツルメンテーションパッケージがインストールされたアプリケーションのルートにリクエストを送信し、DataKit ホストで受信ログを確認します。

curl http://127.0.0.1:8080/
sudo tail -f /usr/local/datakit/log/gin.log | grep '/otel/v1/'

/otel/v1/traces への POST リクエストが表示され、ステータスコードが 200 であれば、DataKit が Trace を受信したことを意味します。その後、Guance の「APM > トレース」に移動し、service:order-service で検索します。

データが表示されない場合は、以下の項目を順に確認してください：PHP Web SAPI が opentelemetry 拡張機能を読み込んでいるか、アプリケーションが Composer オートローダーを読み込んでいるか、OTEL_PHP_AUTOLOAD_ENABLED が true に設定されているか、実際のコードパスに一致する自動インスツルメンテーションパッケージがインストールされているか、OTLP エンドポイントに到達可能かどうか。

参考¶

• OpenTelemetry コレクター設定
• OpenTelemetry PHP ゼロコードインスツルメンテーション
• OpenTelemetry PHP SDK 設定
• OpenTelemetry PHP インスツルメンテーションライブラリ
• OpenTelemetry OTLP Exporter 設定 ```