Forge

Middleware monitoring for Laravel Forge combines infrastructure metrics with application traces and logs from your Laravel applications.

Use server metrics to investigate resource usage and application traces to identify slow or failing requests. The two sources provide context for distinguishing a host resource problem from an application operation.

How it works#

Laravel Forge provisions and manages servers on cloud providers such as AWS, DigitalOcean, and other supported platforms.

Middleware monitoring uses two components:

Middleware Infrastructure Agent: Runs on the Forge-managed server to collect host metrics and forward application telemetry.
Laravel APM instrumentation: Uses OpenTelemetry to collect application traces, logs, and request-related metrics.

Your Laravel application sends telemetry to the local Middleware Agent, which forwards it to your Middleware account.

You can install Middleware manually over SSH or include the installation commands in your Forge provisioning and deployment scripts.

Supported telemetry#

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

Prerequisites#

Before installing Middleware, make sure you have:

An existing Laravel application deployed using Laravel Forge.
SSH access to the Forge-managed server.
Permissions to install packages and modify PHP configuration.
Access to your Laravel application's source code and Forge deployment settings.
A Middleware account with an API key and target URL.
Outbound HTTPS connectivity from the server to Middleware on port 443.
PHP and Composer installed on the server.
PHP 8.0 or later.
PHP development tools (phpize) and build tools. The installer compiles the OpenTelemetry PHP extension and stops if these are missing. Install them with sudo apt-get install php8.3-dev build-essential, replacing 8.3 with your PHP version.
PHP extensions enabled: zlib, mbstring, simplexml, json, dom, openssl, phar, fileinfo, pcre, xmlwriter, gd.

Installation#

1 Install the Middleware Agent#

Connect to your Forge-managed server using SSH.

Install the Middleware Infrastructure Agent with this command:

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

Replace <MW_API_KEY> and <MW_UID> with your Middleware account details.

The installation script installs and configures the Middleware Agent on your server.

Optional: Add the installation command to your Forge provisioning script if you want the Agent installed automatically when provisioning new servers.

Note: Install the Infrastructure Agent once per server. You do not need to reinstall it during every application deployment.

2 Instrument your Laravel application#

Navigate to your Laravel application directory on the server.

Run the following commands:

1curl -O https://install.middleware.io/apm/php/laravel-instrument.php
2
3sudo COMPOSER_ALLOW_SUPERUSER=1 php laravel-instrument.php install
4sudo chown -R forge:forge .

The installation script:

Installs the PHP OpenTelemetry extension.
Configures the required instrumentation packages.
Enables Middleware APM integration for Laravel.

Note: The installer updates composer.json and composer.lock. It adds the OpenTelemetry and Middleware packages, sets minimum-stability to dev, and turns off the php-http/discovery Composer plugin.

Run these commands once per server over SSH. Do not add them to the Forge Deployment Script: Forge runs it as the forge user, which cannot install PHP extensions. The last command returns file ownership to forge so later deployments work.

Note: Run the instrumentation script from your Laravel application's root directory. After the installer finishes, commit the updated composer.json and composer.lock to your Git repository. Otherwise a later deployment can fail or remove the Middleware packages.

3 Configure environment variables#

Open Laravel Forge → Sites → Your Site → Environment.

Add the following environment variables to your Laravel application's .env file:

1OTEL_PHP_AUTOLOAD_ENABLED=true
2OTEL_SERVICE_NAME=laravel-production
3OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:9320

Replace laravel-production with the service name you want to display in Middleware.

These variables configure the application to initialize OpenTelemetry and export telemetry to the local Middleware Agent.

Variable	Description
`OTEL_PHP_AUTOLOAD_ENABLED`	Enables OpenTelemetry PHP auto-instrumentation
`OTEL_SERVICE_NAME`	Service name displayed in Middleware
`OTEL_EXPORTER_OTLP_ENDPOINT`	Local Middleware Agent endpoint for telemetry export

Save the environment configuration.

Note: If your deployment runs php artisan config:cache or php artisan optimize, Laravel stops reading .env and these variables are ignored. In that case, set them in the PHP-FPM pool config (/etc/php/8.x/fpm/pool.d/www.conf, or your site's pool file if you use site isolation), one line per variable, then restart PHP-FPM:

1env[OTEL_PHP_AUTOLOAD_ENABLED] = true
2env[OTEL_SERVICE_NAME] = laravel-production
3env[OTEL_EXPORTER_OTLP_ENDPOINT] = http://localhost:9320

4 Enable frontend and backend trace correlation (optional)#

If you use Middleware RUM to monitor your frontend application, enable trace context propagation to connect frontend requests with Laravel backend traces.

Add the following environment variable:

1OTEL_PROPAGATORS=baggage,tracecontext,b3multi

This enables W3C and B3 multi-header trace propagation.

Make sure your frontend application forwards compatible trace headers, including those required by your configured propagation format.

5 Enable Laravel request metrics (optional)#

To collect additional request-related metrics, such as latency and error rate, register the Middleware Laravel service provider and metrics middleware.

1. Register the service provider

Open config/app.php and add the Middleware service provider:

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

2. Add the metrics middleware

Open app/Http/Kernel.php and add the following line at the end of the $middleware array:

1protected $middleware = [
2    // ...
3    \Middleware\LaravelApm\Middleware\MetricsMiddleware::class,
4];

Laravel 11+ applications do not have app/Http/Kernel.php.

1. Register the service provider

In bootstrap/providers.php, add the service provider:

1return [
2    App\Providers\AppServiceProvider::class,
3    Middleware\LaravelApm\LaravelApmServiceProvider::class,
4];

2. Add the metrics middleware

In bootstrap/app.php, add the metrics middleware:

1->withMiddleware(function (Middleware $middleware) {
2    $middleware->append(\Middleware\LaravelApm\Middleware\MetricsMiddleware::class);
3})

This enables additional Laravel request metrics.

6 Configure application logs#

Middleware integrates with Laravel's logging system to collect application logs.

Once the Middleware Agent and Laravel instrumentation are configured, application logs are forwarded to Middleware.

You can continue using Laravel's existing logging methods:

1use Illuminate\Support\Facades\Log;
2
3Log::info('Order created successfully');
4
5Log::warning('Payment retry triggered');
6
7Log::error('Payment processing failed', [
8    'order_id' => 12345,
9]);

Logs can be viewed under Log Monitoring → Log Explorer in Middleware.

7 Deploy the application#

After configuring instrumentation and environment variables:

Open Laravel Forge → Sites → Your Site.
Review the application deployment script.
Deploy the updated application.
Confirm that the deployment completes successfully.
Generate requests to your Laravel application.

If PHP configuration or extension changes were made, restart the relevant PHP-FPM service to ensure the application loads the updated configuration.

8 Verify data collection#

After deployment, allow a few minutes for telemetry to appear.

Verify infrastructure metrics

Go to Infrastructure Monitoring → Hosts.

Find your Forge-managed server and verify that CPU, memory, disk, and other available host metrics are being collected.

Verify application traces

Go to APM → Services.

Find the service configured using OTEL_SERVICE_NAME.

Open the service to view request traces, latency, and errors.

Verify logs

Go to Log Monitoring and filter by your Laravel service name.

Environment variables reference#

Scope	Variable	Required	Description
Agent installation	`MW_API_KEY`	Yes	Middleware API key
Agent installation	`MW_TARGET`	Yes	Middleware ingestion endpoint
Laravel APM	`OTEL_PHP_AUTOLOAD_ENABLED`	Yes	Enables OpenTelemetry PHP auto-instrumentation
Laravel APM	`OTEL_SERVICE_NAME`	Yes	Name displayed in Middleware APM
Laravel APM	`OTEL_EXPORTER_OTLP_ENDPOINT`	Yes	Local Middleware Agent endpoint
Trace correlation	`OTEL_PROPAGATORS`	No	Configures distributed trace propagation

Example Laravel configuration#

1OTEL_PHP_AUTOLOAD_ENABLED=true
2OTEL_SERVICE_NAME=laravel-production
3OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:9320
4OTEL_PROPAGATORS=baggage,tracecontext,b3multi

Security note: Keep your Middleware API key out of source control. Store it securely and reference it from Forge or your cloud provider's secret-management service when installing the Agent.

Troubleshooting#

Middleware Agent is not running#

If infrastructure metrics or application telemetry do not appear:

Verify that the Agent installation script completed successfully.
Confirm that MW_API_KEY and MW_TARGET were configured correctly during installation.
Check that the server can connect to Middleware over HTTPS on port 443.
Review the Middleware Agent service logs for startup or export errors.

OpenTelemetry PHP extension is missing#

Check whether the OpenTelemetry PHP extension is installed:

1php -m | grep opentelemetry

If no output is returned:

Rerun the Laravel instrumentation installer.
Check the installer output for dependency or permission errors.
Verify that the extension is enabled in the PHP configuration.

OpenTelemetry extension is not registered#

Check the PHP extension configuration directory:

1php-config --ini-dir

Look for an opentelemetry.ini file in the returned directory.

If it is missing, create the file with:

1extension=opentelemetry.so

Restart PHP-FPM after updating the extension configuration.

Note: The PHP CLI and PHP-FPM may use different configuration directories. Verify that the extension is enabled for the PHP runtime serving your Laravel application.

No application traces in Middleware#

If your Laravel application is running but traces are missing:

Verify that OTEL_PHP_AUTOLOAD_ENABLED=true.
Confirm that OTEL_SERVICE_NAME is configured.
Check that OTEL_EXPORTER_OTLP_ENDPOINT is set to http://localhost:9320.
Verify that the Middleware Agent is running on the same server.
Generate application traffic and check APM → Services.

Application logs are missing#

If traces appear but application logs do not:

Verify that Laravel instrumentation completed successfully.
Confirm that the Middleware Agent is running.
Check the Laravel logging configuration and application log output.
Generate a test log and verify it in Log Explorer.

Frontend and backend traces are not connected#

If you use Middleware RUM and frontend requests are not correlated with backend traces:

Verify that OTEL_PROPAGATORS includes baggage,tracecontext,b3multi.
Confirm that the frontend sends the required propagation headers.
Check that proxies and web server configuration do not remove tracing headers.

Instrumentation stops working after deployment#

If telemetry collection stops after a Forge deployment:

Verify that the instrumentation packages and configuration remain installed.
Check that the required environment variables are still present.
Confirm that the deployment script does not overwrite instrumentation changes.
Restart PHP-FPM if PHP extensions or configuration were updated.

If the issue persists, contact Middleware Support at [email protected].

Need assistance or want to learn more about Middleware? Get in touch with us via our Contact Us or join our Slack channel.