Skip to content

PHP zero-code instrumentation

Beacon PHP requires PHP 8.2 or later, the Beacon Composer package installed in the application, and the Beacon native extension matching the runtime.

Before starting, enable the DataKit OpenTelemetry input as described in Common configuration. The commands use a Linux/macOS shell and assume that the application and DataKit run on the same host. Replace 127.0.0.1 and adjust the listening address for remote or container deployments.

Install

  1. Download and enable the extension build matching the PHP version, thread-safety mode, operating system, and architecture from the extension releases.
  2. Create a .beacon directory in the application root, download the Composer ZIP artifact from the Beacon PHP releases page into it, then install the framework integrations you use:
composer config repositories.beacon artifact "$PWD/.beacon"
composer require beacon-observability/beacon-php
vendor/bin/beacon-php install pdo guzzle

Use vendor/bin/beacon-php components to list other integration aliases.

Run

export OTEL_PHP_AUTOLOAD_ENABLED=true
export OTEL_SERVICE_NAME=my-php-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:9529/otel
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
vendor/bin/beacon-php doctor
php public/index.php

For PHP-FPM, configure the same environment variables in the service environment and restart the workers. Beacon PHP does not currently ship a profiling component.

Debugging and diagnostics

Capture a runtime diagnostic report, then enable SDK internal logging. Keep the autoload and OTLP settings above:

vendor/bin/beacon-php doctor --json > beacon-php-doctor.json
OTEL_LOG_LEVEL=debug OTEL_PHP_LOG_DESTINATION=stderr \
  php public/index.php > beacon-php-debug.log 2>&1

doctor checks PHP, the native extension, SDK, exporter, components, and zero-code configuration. It does not test an actual OTLP delivery. OTEL_PHP_LOG_DESTINATION=stderr sends SDK internal logs to standard error, which this command captures in a file.

For PHP-FPM, inject both variables into the actual worker environment, restart workers, and collect standard error using the FPM logging configuration. CLI and FPM can use different php.ini files, extensions, and environment variables; a CLI doctor report does not validate the FPM runtime.

Return to the normal launch command, or remove the debug variables from FPM/service configuration and restart after troubleshooting.

Verify

Send a request through a supported framework or library, then open APM > Traces in Guance and filter by the configured service name. See Common configuration for verification steps and Troubleshooting if no data appears.

Feedback

Is this page helpful?