Skip to main content

Laravel OpenTelemetry traces on your machine

Install the OpenTelemetry PHP extension and the Laravel auto-instrumentation package, then set OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:8000. Each Laravel request then shows up in Buggregator as a trace: the request, its database queries and its HTTP client calls as spans on one timeline. No Jaeger, no Grafana, no account.

Steps

1. Start Buggregator

It takes OTLP over HTTP on the same port as its UI, 8000.

bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  ghcr.io/buggregator/server:latest

2. Install the OpenTelemetry extension

Auto-instrumentation needs the opentelemetry PHP extension. Install it with PECL, or with install-php-extensions opentelemetry in a Docker image, then enable it.

bash
pecl install opentelemetry
ini
[opentelemetry]
extension=opentelemetry.so

Check it with php -m | grep opentelemetry.

3. Add the packages

The SDK, the OTLP exporter and the Laravel instrumentation.

bash
composer require open-telemetry/sdk open-telemetry/exporter-otlp open-telemetry/opentelemetry-auto-laravel

4. Point the SDK at Buggregator

Put these lines in php.ini (or another ini file PHP reads), or set them as environment variables of the PHP process. Laravel's .env is not enough: the SDK starts when Composer's autoloader runs, before Laravel reads .env.

ini
OTEL_PHP_AUTOLOAD_ENABLED="true"
OTEL_SERVICE_NAME="laravel"
OTEL_TRACES_EXPORTER="otlp"
OTEL_LOGS_EXPORTER="otlp"
OTEL_METRICS_EXPORTER="none"
OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:8000"

In Docker Compose, use the service name: http://buggregator:8000. Buggregator takes http/protobuf or http/json, not grpc. It does not take metrics, so metrics export is off here.

5. Open Sentry, then Traces

Load a page of your app. In Buggregator, open the Sentry page and pick Traces. The row is labelled OTel and shows the service name. Open it to see the spans as a waterfall, with a Service column. Laravel logs sent through OpenTelemetry show up under Logs and link to their trace.

Why it works

The Laravel package hooks into the HTTP kernel, the database and the HTTP client, and creates spans without code changes. The OTLP exporter sends them to /v1/traces on the endpoint you set. Buggregator accepts OTLP on port 8000 and shows OTel traces on the Sentry page, next to traces from Sentry SDKs. OTEL_SERVICE_NAME is what you see as the service.

Checked on with Buggregator v2.13.0

Setup in 60 seconds

No registration. No account. Start it and point your app at it.

1

Start Buggregator

One file, installed with one command. The web UI opens on port 8000. Prefer containers? Use the Docker tab.

$ curl -fsSL https://raw.githubusercontent.com/buggregator/server/master/scripts/install.sh | sh
$ HTTP_ADDR=127.0.0.1:8000 \
  SMTP_ADDR=127.0.0.1:1025 \
  VAR_DUMPER_ADDR=127.0.0.1:9912 \
  MONOLOG_ADDR=127.0.0.1:9913 \
  PROXY_ADDR=127.0.0.1:8080 \
  ~/.local/bin/buggregator

The script picks the file for your CPU: Intel/AMD or ARM.

One file for Linux, macOS and Windows, about 40 MB. Nothing else to install.

This run line keeps it on this computer. Without the *_ADDR settings it listens on all network interfaces

Rather not run a script? Download the file yourself

Runs on Windows, macOS and Linux, on Intel/AMD and ARM.

Prefer not to do it yourself? Your AI agent can set Buggregator up for you