Menu

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.

The AppSignal PHP integration requires PHP 8 or newer.

Install the OpenTelemetry PHP extension

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

Ubuntu / Debian
sudo apt-get install gcc make autoconf

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

PECL
pecl 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:

ini
[opentelemetry]
extension=opentelemetry.so

Install the OpenTelemetry packages

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

Shell
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:

Shell
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:

Shell
composer require open-telemetry/opentelemetry-auto-laravel

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

Configure OpenTelemetry in your application

Add this appsignal.php file at the root of your application with the OpenTelemetry exporter and AppSignal configuration. Then, require() that file before your application starts.

Make sure to update the values below with your AppSignal application name, environment and push API key, and to replace the exporter endpoint with the address of your AppSignal collector if needed.

appsignal.php
<?php
 
use OpenTelemetry\API\Globals;
use OpenTelemetry\API\Logs\EventLogger;
use OpenTelemetry\API\Logs\LogRecord;
use OpenTelemetry\API\Trace\Propagation\TraceContextPropagator;
use OpenTelemetry\Contrib\Otlp\LogsExporter;
use OpenTelemetry\Contrib\Otlp\MetricExporter;
use OpenTelemetry\Contrib\Otlp\SpanExporter;
use OpenTelemetry\SDK\Common\Attribute\Attributes;
use OpenTelemetry\SDK\Common\Export\Stream\StreamTransportFactory;
use OpenTelemetry\SDK\Logs\LoggerProvider;
use OpenTelemetry\SDK\Logs\Processor\SimpleLogRecordProcessor;
use OpenTelemetry\SDK\Metrics\MeterProvider;
use OpenTelemetry\SDK\Metrics\MetricReader\ExportingReader;
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\TracerProvider;
use OpenTelemetry\SemConv\ResourceAttributes;
use OpenTelemetry\Contrib\Otlp\OtlpHttpTransportFactory;
 
// Replace with your application name
$name = "My application";
// Replace with your application environment
$environment = "production";
// Replace with your AppSignal push API key
$pushApiKey = "0000-0000-0000-0000";
 
// Optionally replace with your service name
$serviceName = "Laravel";
// Replace with the address of your AppSignal collector if it's running on another host
$collector = 'http://appsignal-collector:8099';
 
 
$revision = trim(shell_exec('git rev-parse HEAD 2>/dev/null')) ?: 'unknown';
 
$resource = ResourceInfoFactory::emptyResource()->merge(ResourceInfo::create(Attributes::create([
  'service.name' => $serviceName,
  'appsignal.config.name' => $name,
  'appsignal.config.environment' => $environment,
  'appsignal.config.push_api_key' => $pushApiKey,
  'appsignal.config.revision' => $revision,
  'appsignal.config.language_integration' => 'php',
  'appsignal.config.app_path' => __DIR__,
  'host.name' => gethostname(),
])));
 
$spanExporter = new SpanExporter(
    (new OtlpHttpTransportFactory())->create("$collector/v1/traces", 'application/x-protobuf')
);
 
$logExporter = new LogsExporter(
    (new OtlpHttpTransportFactory())->create("$collector/v1/logs", 'application/x-protobuf')
);
 
$reader = new ExportingReader(
    new MetricExporter(
        (new OtlpHttpTransportFactory())->create("$collector/v1/metrics", 'application/x-protobuf')
    )
);
 
$meterProvider = MeterProvider::builder()
    ->setResource($resource)
    ->addReader($reader)
    ->build();
 
$tracerProvider = TracerProvider::builder()
    ->addSpanProcessor(
        new SimpleSpanProcessor($spanExporter)
    )
    ->setResource($resource)
    ->setSampler(new ParentBased(new AlwaysOnSampler()))
    ->build();
 
$loggerProvider = LoggerProvider::builder()
    ->setResource($resource)
    ->addLogRecordProcessor(
        new SimpleLogRecordProcessor($logExporter)
    )
    ->build();
 
Sdk::builder()
    ->setTracerProvider($tracerProvider)
    ->setMeterProvider($meterProvider)
    ->setLoggerProvider($loggerProvider)
    ->setPropagator(TraceContextPropagator::getInstance())
    ->setAutoShutdown(true)
    ->buildAndRegisterGlobal();

Usage with Laravel

If you are using Laravel, you can require the appsignal.php file from the bootstrap/app.php file, before the Laravel application is created. This ensures that the OpenTelemetry SDK is initialized before Laravel starts handling requests.

bootstrap/app.php
<?php
 
// ...
 
// Add this before the application initialization
require(base_path('appsignal.php'));
 
// return Application::configure(...)

To be able to configure AppSignal using the .env file loaded by your Laravel application, load the environment variables for your app, then load the appsignal.php file, and then return the application instance:

bootstrap/app.php
<?php
 
// Add this import
use Illuminate\Foundation\Bootstrap\LoadEnvironmentVariables;
 
// Assign the previously returned app to a variable
$app = Application::configure(basePath: dirname(__DIR__))
    // ...
    ->create();
 
// Load the environment variables from the .env file
(new LoadEnvironmentVariables())->bootstrap($app);
 
// Load the AppSignal configuration
require(base_path('appsignal.php'));
 
// Return the app
return $app;

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!