Forge

This guide walks you through instrumenting Laravel applications that are hosted via Forge.

Introduction

Forge supports 2 kinds of Project Types : "PHP / Laravel / Symphony" and "Static HTML / Nuxt.js / Next.js".

In this guide, We will get to know how to use Middleware Laravel APM if the project is deployed via Project Type "PHP / Laravel / Symphony".

Features Supported

Instrumentation

Step 1: Install Middleware Agent on your server

To deploy a laravel application on Forge, users connect their cloud based virtual machines i.e. AWS EC2, DigitalOcean Droplet, etc.

You may need to install Middleware Agent on this connected server. Middleware Agent will receive instrumentation data i.e. Metrics / Traces / Logs, from your laravel application and it will forward that data to Middleware servers.

You can use the bash script mentioned below to install Middleware Agent

MW_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)"

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

Step 2: Run Laravel Instrumentation Script

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

The command mentioned above simply downloads PHP instrumentation script and runs the install command.

You can run this from your server OR simply add these 2 lines in the Forge's "Deployment Script"

Step 3: Additional Configuration

For enabling metrics and further customization, refer to the Laravel instrumentation documentation.

Troubleshooting Steps

In case application traces do not show up in Middleware after following the process mentioned above, you can follow the steps mentioned below:

Check if OpenTelemetry Extension is installed

As our APM uses OpenTelemetry extension for instrumenting the laravel app, we need to make sure that extension is installed properly

How to check ?

php -m | grep opentelemetry

If opentelemetry exists in the php -m list it should show up, blank output shows failure.

How to solve ?

Try re-running the Laravel Instrumentation Script, and look for any permission related errors

Check if OpenTelemetry Extension is registered

If the Opentelemetry extension is present as mentioned above, also check if the extension is registered.

How to check ?

$(php-config --ini-dir) | grep opentelemetry.ini

If opentelemetry.ini exists in the list then you can consider that extension is properly registered, blank output shows failure

How to solve ?

Create a file named opentelemetry.ini at your php config directory ( php-config --ini-dir ) The content should be as mentioned below:

extension=opentelemetry.so

Check the existence of Environment variables

We need to Make sure that the below mentioned Environment variables are set properly

OTEL_PHP_AUTOLOAD_ENABLED = "true"
OTEL_SERVICE_NAME = <YOUR_SERVICE_NAME>
OTEL_EXPORTER_OTLP_ENDPOINT = "http://localhost:9320"
OTEL_PROPAGATORS = "baggage,tracecontext,b3multi"

How to confirm ?

You can confirm by creating a file called info.php under public/ directory with the content given below

<?php
phpinfo();

Visit this page via your browser at <YOUR_DOMAIN>/info.php

How to solve ?

If this Environment variables are not set, You can add the lines mentioned below in this file: /etc/php/x.x/fpm/pool.d/www.conf,

env[OTEL_PHP_AUTOLOAD_ENABLED] = "true"
env[OTEL_SERVICE_NAME] = "pingcrm-forge"
env[OTEL_EXPORTER_OTLP_ENDPOINT] = "http://localhost:9320"
env[OTEL_PROPAGATORS] = "baggage,tracecontext,b3multi"

Filepath for www.conf can be a little different based on php version you are currently using.

Confirm connection between frontend - backend traces

If you are using Middleware's RUM solution and Middleware APM both, You can also get a co-relation between your frontend and backend traces.

How does it look like ?

If your frontend-backend traces are connected as expected, You should be able to see flamegraphs in Middleware UI where both the services co-exist.

In this image, you can see that frontend service pingcrm is calling backend service pingcrm-forge, both services are annotated with different colors in flamegraph.

What if frontend - backend traces are not connected ?

Middleware RUM solution adds some request headers for context propagation. You need to make sure that these headers exist in your request : X-B3-Sampled, X-B3-Spanid, B3

If existing headers do not exist, the issue can be related to Middleware RUM configurations.

If the header exists, but the issue can be with the OTEL_PROPAGATORS Environment variable value.