2026年8月20日

OpenTelemetryの導入と設定方法（WordPress/PHPの自動計装とCollectorの構成）

バックアップ・監視

OpenTelemetry（OTel）は、トレース・メトリクス・ログを特定の監視サービスに縛られない共通の形式で集めるための仕様とツール群です。WordPress では、PHP 拡張と自動計装パッケージを入れてトレースを作り、サーバー上の OpenTelemetry Collector で受けてから好きなバックエンドへ送る構成が基本になります。この記事では、PHP 拡張のインストール、WordPress への読み込み方、Collector の設定、サンプリングと個人情報の扱い、うまく動かないときの戻し方までを説明します。

送り先のバックエンド（Grafana Tempo など）の構築は別記事で扱っています。本記事は「アプリ側で計装し、Collector まで届ける」部分に絞ります。

OpenTelemetry の構成要素

最初に用語を整理しておくと、設定項目の意味が分かりやすくなります。

シグナル：トレース（リクエストごとの処理の流れ）、メトリクス（数値の推移）、ログの3種類
API / SDK：アプリの中でスパン（処理の区間）を作り、送信するためのライブラリ
自動計装：アプリのコードを書き換えずに、フレームワークやライブラリの関数呼び出しを横取りしてスパンを作る仕組み
OTLP：OpenTelemetry の標準の送信プロトコル。gRPC（4317 番）と HTTP（4318 番）が慣例のポート
Collector：OTLP などで受け取ったデータを加工・間引きして、1つまたは複数のバックエンドに送る中継プログラム

アプリから監視サービスへ直接送ることもできますが、Collector を同じサーバーに置くと、送り先の変更や個人情報の削除をアプリに触らず Collector 側で行えます。PHP はリクエストごとに処理が終わる実行モデルなので、送信先が遠いと応答が遅くなるおそれもあり、手元の Collector に短時間で渡す構成が向いています。

前提条件を確認する

PHP の自動計装には PHP 拡張のインストールと PHP-FPM の設定変更が必要です。root 権限のある VPS や専用サーバーが前提で、共有レンタルサーバーでは多くの場合導入できません。また、本番サイトにいきなり入れず、同じ PHP バージョンのステージング環境で試してから反映してください。

PHP 拡張と SDK の対応 PHP バージョンは更新されるため、導入前に OpenTelemetry PHP の公式ドキュメントで確認します。対象は PHP 8 系です（2026年10月現在）。

php -v
php-fpm8.3 -v        # FPM のバージョン。ディストリビューションでコマンド名は異なる
composer --version

PHP 拡張をインストールする

自動計装は、関数の呼び出し前後に処理を差し込む opentelemetry 拡張を使います。PECL でビルドするのが一般的な方法です。

# ビルドに必要なパッケージ（Debian/Ubuntu の例。PHP のバージョンに合わせる）
sudo apt install php8.3-dev php-pear build-essential

sudo pecl install opentelemetry
echo "extension=opentelemetry.so" | sudo tee /etc/php/8.3/mods-available/opentelemetry.ini
sudo phpenmod -v 8.3 opentelemetry

php --ri opentelemetry          # CLI で読み込まれているか
sudo systemctl restart php8.3-fpm

CLI と FPM は別々の設定ディレクトリを読むため、php --ri で表示されても FPM 側では無効、ということがあります。phpenmod は両方に有効化の設定を作るので、ディストリビューションのパッケージを使っている場合はこの方法がまぎれにくいです。OTLP を protobuf 形式で送る場合、protobuf 拡張を追加すると処理が軽くなると案内されていますが、なくても動作します。

SDK と WordPress 用の自動計装パッケージを入れる

WordPress 本体は Composer を使っていないため、計装用のパッケージは WordPress とは別のディレクトリにまとめてインストールし、PHP の起動時に読み込ませます。公開ディレクトリの外に置くことで、ベンダーファイルに URL から直接アクセスされることを防ぎます。

sudo mkdir -p /opt/otel-wordpress
sudo chown "$USER" /opt/otel-wordpress
cd /opt/otel-wordpress

composer require \
  open-telemetry/sdk \
  open-telemetry/exporter-otlp \
  open-telemetry/opentelemetry-auto-wordpress \
  guzzlehttp/guzzle

open-telemetry/opentelemetry-auto-wordpress は、OpenTelemetry PHP の contrib リポジトリで管理されている WordPress 用の自動計装です。WordPress の主要な処理（リクエスト全体やデータベースへの問い合わせなど）にスパンを作りますが、どこまで計装されるかはパッケージの版で変わり、contrib パッケージは仕様が安定していないこともあります。導入した版の README を読み、ステージングで実際にどんなスパンが出るかを確認してください。Composer がプラグイン（php-http/discovery）の実行許可を尋ねてきた場合は、内容を確認したうえで許可します。

PHP-FPM から読み込ませる

自動計装は、WordPress のコードより先に Composer の autoload を読み込む必要があります。PHP の auto_prepend_file を使い、PHP-FPM のプール設定に環境変数と一緒に書きます。

; /etc/php/8.3/fpm/pool.d/www.conf に追記（プール名・パスは環境に合わせる）
php_admin_value[auto_prepend_file] = /opt/otel-wordpress/vendor/autoload.php

env[OTEL_PHP_AUTOLOAD_ENABLED] = true
env[OTEL_SERVICE_NAME] = wordpress-example
env[OTEL_TRACES_EXPORTER] = otlp
env[OTEL_METRICS_EXPORTER] = none
env[OTEL_LOGS_EXPORTER] = none
env[OTEL_EXPORTER_OTLP_PROTOCOL] = http/protobuf
env[OTEL_EXPORTER_OTLP_ENDPOINT] = http://127.0.0.1:4318
env[OTEL_PROPAGATORS] = baggage,tracecontext
env[OTEL_TRACES_SAMPLER] = parentbased_traceidratio
env[OTEL_TRACES_SAMPLER_ARG] = 0.2

sudo php-fpm8.3 -t               # 設定の構文確認
sudo systemctl reload php8.3-fpm

設定の意図は次のとおりです。

OTEL_SERVICE_NAME：バックエンドで検索するときのサービス名です。複数サイトを同じサーバーで動かしているなら、プールごとに別の名前を付けます。
メトリクスとログは none：まずトレースだけに絞ると、問題が起きたときに原因を切り分けやすくなります。
サンプラー：0.2 は、親のないリクエストのうち約2割を記録するという意味です。全件を記録すると、アクセスの多いサイトでは負荷と保存量が増えます。

つまずきやすいのが、すでに auto_prepend_file を使っているサイトです。たとえば Wordfence のファイアウォールで拡張保護（Extended Protection）を有効にしていると、.user.ini などで同じ設定を使っています。auto_prepend_file は1つしか指定できず、プール設定の php_admin_value は .user.ini より優先されるため、そのまま追記するとそちらの保護が外れてしまいます。この場合は、両方のファイルを順に require_once する小さなファイルを公開ディレクトリの外に作り、それを指定します。

<?php
// /opt/otel-wordpress/prepend.php
require_once '/opt/otel-wordpress/vendor/autoload.php';
require_once '/var/www/example.com/wordfence-waf.php'; // 既存の設定値をそのまま移す

Collector を用意する

Collector には、主要な部品だけを含む本体版と、追加の受信・加工・送信部品を多数含む contrib 版があります。属性の削除などの加工部品を使いたい場合は contrib 版（otelcol-contrib）を選びます。GitHub のリリースページで各ディストリビューション向けのパッケージが配布されています。

最初は、受け取ったデータをログに出すだけの debug 出力で動作を確かめます。以前の記事でよく見る logging 出力は廃止され、debug に置き換わっています。

# /etc/otelcol-contrib/config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 127.0.0.1:4317
      http:
        endpoint: 127.0.0.1:4318

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 256
    spike_limit_mib: 64
  attributes/strip:
    actions:
      - key: url.query
        action: delete
      - key: enduser.id
        action: delete
  batch: {}

exporters:
  debug:
    verbosity: basic
  otlp/tempo:
    endpoint: tempo.internal.example:4317
    tls:
      insecure: true    # 同じプライベートネットワーク内に限る

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, attributes/strip, batch]
      exporters: [debug, otlp/tempo]

otelcol-contrib validate --config=/etc/otelcol-contrib/config.yaml
sudo systemctl restart otelcol-contrib
journalctl -u otelcol-contrib -f

memory_limiter は Collector がメモリを使い切るのを防ぐ部品で、処理の先頭に置くのが推奨です。batch はまとめて送ることで通信回数を減らします。受信アドレスを 127.0.0.1 にしているのは、外部から任意のデータを送り込まれないようにするためです。

監視サービス（SaaS）へ送る場合は otlphttp 出力を使い、API キーは ${env:YOUR_API_KEY} のように環境変数から読み込みます。設定ファイルにキーを直接書いてリポジトリに入れることは避けてください。

動作確認とトラブルシューティング

設定後、サイトのページをいくつか開き、Collector のログ（journalctl）にスパンの件数が出るかを見ます。サンプリング率を下げていると記録されないリクエストもあるので、確認の間だけ OTEL_TRACES_SAMPLER_ARG を 1.0 にすると分かりやすくなります。

届かないときは、次の順で確認します。

拡張が FPM で読み込まれているか：phpinfo() を一時的に出すか、FPM のログに拡張の読み込みエラーが出ていないかを見ます。確認用ファイルは終わったらすぐ削除します。
autoload が読まれているか：auto_prepend_file のパスの誤りは、PHP の Fatal error として FPM のエラーログに出ます。
環境変数が渡っているか：プール設定の env[] は、書いたプールにしか効きません。サイトが別のプールで動いていないか確認します。
Collector の受信ポート：ss -lntp | grep 431 で 4317・4318 番が待ち受けているかを見ます。

属性名は、セマンティック規約の改訂で http.url から url.full のように変わったものがあります。Collector で削除したい属性が消えていない場合は、debug 出力の verbosity: detailed で実際の属性名を確認してから設定を直します。

導入後にサイトが重くなった、エラーが出るなどの問題があれば、まずプール設定に env[OTEL_SDK_DISABLED] = true を追加して FPM を再読み込みすると、パッケージを残したまま計装を止められます。それでも直らなければ auto_prepend_file の行を削除し、拡張を phpdismod で無効にすれば、導入前の状態に戻ります。

まとめ

OpenTelemetry は計装・送信・中継を共通仕様で行う仕組みで、WordPress では PHP 拡張と自動計装パッケージでトレースを作ります。
パッケージは公開ディレクトリの外に入れ、auto_prepend_file と PHP-FPM の env[] で読み込みと設定を行います。既存の auto_prepend_file を上書きしないよう注意します。
Collector は 127.0.0.1 で受け、memory_limiter・属性の削除・batch を通してからバックエンドへ送ります。
サンプリングで負荷と保存量を調整し、問題が出たら OTEL_SDK_DISABLED ですぐに止められるようにしておきます。