Forge

Traces	Metrics	App Logs	Custom Logs	Profiling
✅	✅	✅	✅	✖

Instrumentation#

1 Install the Middleware Agent on your server#

Forge connects to your cloud VM (e.g. AWS EC2, DigitalOcean Droplet). Install the Middleware Infra Agent on that server so Metrics / Traces / Logs from your Laravel app can be forwarded to Middleware. Choose the command for your Linux family:

1MW_API_KEY="<MW_API_KEY>" MW_TARGET=https://<MW_UID>.middleware.io:443 bash -c "$(curl -L https://install.middleware.io/scripts/deb-install.sh)"

1MW_API_KEY="<MW_API_KEY>" MW_TARGET=https://<MW_UID>.middleware.io:443 bash -c "$(curl https://install.middleware.io/scripts/rpm-install.sh)"

Replace placeholders and run directly on the server over SSH. You can also add these lines to a Forge Provisioning or Quick Deploy script as appropriate for your workflow.

2 Instrument Laravel (inline, no external hop)#

This script installs the PHP OpenTelemetry extension and wires Middleware’s Laravel APM into your app.

1curl -O https://install.middleware.io/apm/php/laravel-instrument.php
2COMPOSER_ALLOW_SUPERUSER=1 php laravel-instrument.php install

You may run this on the server or paste both lines into the Forge Deployment Script so each deploy ensures instrumentation is present.
The installer verifies prerequisites and configures required extensions and packages for tracing/logging.

Metrics (optional but recommended):#

Add the service provider and middleware so trace‑related metrics (latency, error rate) are emitted.

config/app.php

1'providers' => [
2    // ...
3    Middleware\LaravelApm\LaravelApmServiceProvider::class,
4],

app/Http/Kernel.php

1protected $middleware = [
2    // ... (ensure tracing is enabled first)
3    \Middleware\LaravelApm\Middleware\MetricsMiddleware::class,
4];

Logging:#

The package integrates with Laravel’s logging; your application logs will be shipped to Middleware automatically once the agent and APM are configured.

Troubleshooting#

Check if the OpenTelemetry extension is installed
```
1php -m | grep opentelemetry
```
If no output, re‑run the Laravel instrumentation script and inspect for permission/errors.
Check if the OpenTelemetry extension is registered
```
1$(php-config --ini-dir) | grep opentelemetry.ini
```
If missing, create opentelemetry.ini in the PHP ini directory (php-config --ini-dir) with:
```
1extension=opentelemetry.so
```
Frontend ↔ Backend trace correlation
- If you’re also using Middleware RUM (Browser), ensure the request carries the propagation headers: X-B3-Sampled, X-B3-Spanid, B3.
- If headers exist but traces aren’t correlating, re-check your PHP propagators setting (see Env Vars below).

Environment Variables Used in This Guide#

Keep sensitive values (like <MW_API_KEY>) in your cloud provider’s secret manager and reference them from Forge where possible.

Scope	Key	Example/Value	Purpose
Agent install	`MW_API_KEY`	`<MW_API_KEY>`	Authenticates your agent with Middleware.
Agent install	`MW_TARGET`	`https://<MW_UID>.middleware.io:443`	Middleware ingestion endpoint (tenant/region specific).
Laravel APM	`OTEL_PHP_AUTOLOAD_ENABLED`	`true`	Enables OpenTelemetry auto‑loader for PHP.
Laravel APM	`OTEL_SERVICE_NAME`	`<your-service-name>`	Logical service label shown in Middleware.
Laravel APM	`OTEL_EXPORTER_OTLP_ENDPOINT`	`http://localhost:9320`	Local agent endpoint that ships traces/logs to Middleware.
Laravel APM	`OTEL_PROPAGATORS`	`baggage,tracecontext,b3multi`	Enables cross‑service trace context propagation.