OpenTelemetry PHP Installation

Please follow the installation guide first, when adding a new application to AppSignal.

Then make sure to install the AppSignal collector before proceeding.

Install the OpenTelemetry PHP extension

First, make sure the build dependencies required to install the OpenTelemetry PHP extension are installed.

sudo apt-get install gcc make autoconf

brew install gcc make autoconf

Then, install the OpenTelemetry PHP extension using either PECL, pie or pickle:

pecl install opentelemetry

# Install pie (skip this step if pie is already installed)
curl -L https://github.com/php/pie/releases/latest/download/pie.phar -o /usr/local/bin/pie && chmod +x /usr/local/bin/pie
 
# Install the extension
pie install open-telemetry/ext-opentelemetry

# Install pickle (skip this step if pickle is already installed)
curl -L https://github.com/FriendsOfPHP/pickle/releases/latest/download/pickle.phar -o /usr/local/bin/pickle && chmod +x /usr/local/bin/pickle
 
# Install the extension
pickle install opentelemetry

Finally, enable the extension in your PHP installation's configuration file. The configuration file is usually named php.ini, and its location can be found by running php --ini. Add the following lines to it:

[opentelemetry]
extension=opentelemetry.so

Install the OpenTelemetry packages

First, configure Composer to disallow certain plugins that may conflict with the OpenTelemetry packages:

composer config allow-plugins.tbachert/spi false
composer config allow-plugins.php-http/discovery false

Then, use Composer to install the OpenTelemetry SDK and OTLP exporter package:

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

Install OpenTelemetry instrumentations

By itself, the OpenTelemetry for PHP SDK does not instrument your application, meaning that no data is exported to the AppSignal collector.

To instrument your application, you will need to install the relevant OpenTelemetry instrumentations for the frameworks and libraries that your application uses. For example, to automatically instrument a Laravel application, you can install the OpenTelemetry Laravel instrumentation:

composer require open-telemetry/opentelemetry-auto-laravel

For other frameworks and libraries, check the list of available OpenTelemetry instrumentations on Packagist.

Configure the OpenTelemetry extension

The extension may be configured using PHP configuration options or environment variables. We recommend using environment variables for configuration. First, configure the agent to export traces and logs to the AppSignal collector:

# Enable auto-instrumentation for the OpenTelemetry PHP extension.
export OTEL_PHP_AUTOLOAD_ENABLED=true
 
# Export traces and metrics to the AppSignal collector using the OTLP protocol.
# Replace `http://localhost:8099` with the address of your AppSignal collector
# if it's running on another host.
export OTEL_TRACES_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:8099

Then, configure the OpenTelemetry resource attributes required by AppSignal:

# Replace these values with your AppSignal application name, environment
# and push API key. These are used by the resource attributes configuration below.
APPSIGNAL_APP_NAME="your-app-name"
APPSIGNAL_APP_ENV="production"
APPSIGNAL_PUSH_API_KEY=your-push-api-key
 
# Optionally, set a custom revision and hostname. If not set, the resource attributes
# configuration below will use the current Git revision and system hostname.
# REVISION="your-custom-revision"
# HOSTNAME="your-custom-hostname"
 
# Set the name of the service that is being monitored. A common choice is the
# name of the framework used. This is used to group traces and metrics in AppSignal.
export OTEL_SERVICE_NAME="my-service-name"
 
export OTEL_RESOURCE_ATTRIBUTES="\
appsignal.config.name=$APPSIGNAL_APP_NAME,\
appsignal.config.environment=$APPSIGNAL_APP_ENV,\
appsignal.config.push_api_key=$APPSIGNAL_PUSH_API_KEY,\
appsignal.config.revision=${REVISION:-$(git rev-parse --short HEAD)},\
appsignal.config.language_integration=php,\
appsignal.config.app_path=$PWD,\
host.name=${HOSTNAME:-$(hostname)}"

Test the app!

Now that all the components are connected, start your app with the required environment variables and test if you see data arrive in AppSignal. Check the "Errors > Issue list" and "Performance > Traces" page specifically.

If after following our installation instructions you still don't see data in AppSignal, let us know and we'll help you finalize your OpenTelemetry installation!