Star
Get started

Monitor Laravel with OpenTelemetry Instrumentation

OpenTelemetry Laravel is a package that integrates OpenTelemetry, an open source observability framework, with Laravel, a popular PHP web application framework. It allows developers to instrument their Laravel applications for distributed tracing, metrics, and logging.

What is OpenTelemetry?

OpenTelemetry is an open source observability toolopen in new window for cloud-native software. It provides a standardized way to collect and export telemetry data from applications and infrastructure.

Auto-instrumentation

OpenTelemetry PHP auto-instrumentation is a powerful feature that allows you to collect telemetry data from your PHP applications with minimal manual configuration.

It automatically adds instrumentation to your application, capturing telemetry data without requiring you to modify code manually.

To use auto-instrumentation, you need to install OpenTelemetry extension.

  1. Setup development environment. Installing from source requires proper development environment and some dependencies:

    sudo apt-get install gcc make autoconf php-dev

    brew install gcc make autoconf

  2. Build/install the extension. With your environment set up you can install the extension:

    pecl install opentelemetry

    php pickle.phar install opentelemetry

    install-php-extensions opentelemetry

  3. Add the extension to your php.ini file (run php --ini to find out file location):

    [opentelemetry]
extension=opentelemetry.so

  4. Verify that the extension is installed and enabled:

    php -m | grep opentelemetry

OpenTelemetry Laravel

Once you have OpenTelemetry extension, you can install Laravel auto-instrumentation:

composer require open-telemetry/opentelemetry-auto-laravel

To export data to Uptrace, you need to install uptrace-php which comes with OpenTelemetry SDK:

composer require uptrace/uptrace

In the public/index.php, add the following code right after the auto-loader registration:

// Find this line in public/index.php
require __DIR__.'/../vendor/autoload.php';

/*
|--------------------------------------------------------------------------
| Configure OpenTelemetry
|--------------------------------------------------------------------------
*/

$uptrace = Uptrace\Distro::builder()
    // copy your project DSN here or use UPTRACE_DSN env var
    ->setDsn('https://<token>@api.uptrace.dev?grpc=4317')
    ->setServiceName('myservice')
    ->setServiceVersion('1.0.0')
    ->buildAndRegisterGlobal();

Then you can run your Laravel application as usually:

php artisan serve

You can also find a working example on GitHubopen in new window.

Manual instrumentation

While auto-instrumentation provides a lot out of the box, you can still add custom instrumentation where needed:

$tracer = \OpenTelemetry\API\GlobalTracerProvider::get()->getTracer('my-tracer');
$span = $tracer->spanBuilder('my-custom-operation')->startSpan();
// Your code here
$span->end();

Conclusion

This integration makes it easier for Laravel developers to implement robust observability practices in their applications, helping with debugging, performance optimization, and overall system understanding.

Last Updated: