Laravel

The keepsuit/laravel-opentelemetry (opens in a new tab) package automatically instruments your Laravel application and exports traces, metrics, and logs to Traceway's OTLP endpoints — no manual instrumentation needed.

Prerequisites

PHP 8.2+
Laravel 10, 11, or 12
Composer
A Traceway project (create one in the dashboard)

Step 1: Install Packages

composer require keepsuit/laravel-opentelemetry open-telemetry/exporter-otlp php-http/guzzle7-adapter

The open-telemetry/exporter-otlp and php-http/guzzle7-adapter packages provide the OTLP/HTTP exporter and its HTTP client. They are required at runtime to actually ship spans to Traceway.

Step 2: Publish the Config

php artisan vendor:publish \
    --provider="Keepsuit\LaravelOpenTelemetry\LaravelOpenTelemetryServiceProvider" \
    --tag="opentelemetry-config"

This creates config/opentelemetry.php where you can disable individual instrumentations, configure sampling, set propagators, and tune exporter settings.

Step 3: Configure Environment Variables

Add the following to your .env file, replacing the endpoint and token with your project values:

OTEL_SERVICE_NAME=my-laravel-app
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=http/json
OTEL_EXPORTER_OTLP_ENDPOINT=https://your-traceway-instance.com/api/otel
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-project-token"

Your Traceway dashboard includes a Connection page with a ready-made config snippet and your project token. Go to Connection in the sidebar to grab it.

Note: Use http/json instead of http/protobuf. The protobuf encoder has known deprecation warnings on PHP 8.4+ that can cause noisy logs. The package defaults to http/protobuf — explicitly set http/json if you see deprecation noise.

That's it. The package's service provider auto-registers Keepsuit\LaravelOpenTelemetry\Support\HttpServer\TraceRequestMiddleware as a global middleware, so every inbound HTTP request is now traced — no manual middleware registration needed.

Tune Which Instrumentations Are Enabled

The package's instrumentation list lives in the instrumentation array of config/opentelemetry.php. Each entry can be removed (to disable it) or toggled per-environment via the matching env var. A reasonable default — what ships out of the box — is:

// config/opentelemetry.php
use Keepsuit\LaravelOpenTelemetry\Instrumentation;
 
return [
    // ...
    'instrumentation' => [
        Instrumentation\HttpServerInstrumentation::class => [
            'enabled' => env('OTEL_INSTRUMENTATION_HTTP_SERVER', true),
            'excluded_paths' => ['/health', '/up'],
            'excluded_methods' => [],
            'allowed_headers' => [],
            'sensitive_headers' => [],
        ],
 
        Instrumentation\HttpClientInstrumentation::class => [
            'enabled' => env('OTEL_INSTRUMENTATION_HTTP_CLIENT', true),
            'manual' => false,
        ],
 
        Instrumentation\QueryInstrumentation::class => env('OTEL_INSTRUMENTATION_QUERY', true),
        Instrumentation\RedisInstrumentation::class => env('OTEL_INSTRUMENTATION_REDIS', true),
        Instrumentation\QueueInstrumentation::class => env('OTEL_INSTRUMENTATION_QUEUE', true),
        Instrumentation\CacheInstrumentation::class => env('OTEL_INSTRUMENTATION_CACHE', true),
        Instrumentation\ViewInstrumentation::class => env('OTEL_INSTRUMENTATION_VIEW', true),
        Instrumentation\LivewireInstrumentation::class => env('OTEL_INSTRUMENTATION_LIVEWIRE', true),
 
        Instrumentation\ConsoleInstrumentation::class => [
            'enabled' =>