AWS Elastic Beanstalk

Middleware monitoring for AWS Elastic Beanstalk combines infrastructure collection with Laravel application instrumentation. Host metrics and application telemetry help you investigate resource usage, slow requests, and application errors.

This installation uses Elastic Beanstalk deployment configuration to automatically install the Middleware Agent and configure application instrumentation whenever your environment is deployed or updated.

How it works#

AWS Elastic Beanstalk manages EC2 instances and may replace them during deployments, scaling, or health-related events. Changes made manually to an instance can be lost when it is replaced.

Middleware uses .ebextensions configuration files to automate installation during deployment:

• Middleware Agent: Runs on the EC2 instance and collects telemetry.
• Laravel instrumentation: Enables OpenTelemetry tracing for your application.
• OTLP exporter: Sends application telemetry to the local Middleware Agent, which forwards it to Middleware.

This ensures instrumentation is reapplied during Elastic Beanstalk deployments.

Supported telemetry#

Prerequisites#

Before installing Middleware, make sure you have:

• An existing AWS Elastic Beanstalk environment running a PHP Laravel application.
• Laravel version 8.x or later.
• Access to the application source code and deployment configuration.
• Permissions to update Elastic Beanstalk environment properties and deploy application versions.
• A Middleware account with an API key and target URL.
• Outbound HTTPS connectivity from your Elastic Beanstalk EC2 instances to Middleware on port 443.
• 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.
• PHP extensions enabled: zlib, mbstring, simplexml, json, dom, openssl, phar, fileinfo, pcre, xmlwriter, gd.

Note: This installation method is intended for Elastic Beanstalk environments using RPM-based EC2 instances.

Installation#

1your-laravel-project/
2├── .ebextensions/
3│   └── 99-mwinstrumentation.config
4├── app/
5├── config/
6├── public/
7└── ...

1container_commands:
2  01_install_agent:
3    command: |
4      MW_API_KEY="<MW_API_KEY>" MW_TARGET=https://<MW_UID>.middleware.io:443 bash -c "$(curl -L https://install.middleware.io/scripts/rpm-install.sh)"
5
6  02_run_instrumentation:
7    command: |
8      cd /var/app/staging
9      curl -O https://install.middleware.io/apm/php/laravel-instrument.php
10      COMPOSER_ALLOW_SUPERUSER=1 php laravel-instrument.php install

1OTEL_PROPAGATORS=baggage,tracecontext,b3multi

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

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

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

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

Environment variables reference#

Example configuration#

1MW_TARGET=https://<MW_UID>.middleware.io:443
2OTEL_PHP_AUTOLOAD_ENABLED=true
3OTEL_SERVICE_NAME=laravel-production
4OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:9320
5OTEL_PROPAGATORS=baggage,tracecontext,b3multi

The Middleware API key should be supplied securely during Agent installation.

Troubleshooting#

Middleware Agent is not installed#

If the Agent is missing after deployment:

• Check /var/log/cfn-init-cmd.log for the output of the 01_install_agent command, and /var/log/eb-engine.log for deployment errors. You can also download them from the console: Logs → Request logs → Full logs.
• Verify that the Elastic Beanstalk instances can download the installation script.
• Confirm that the Middleware API key and target URL are correct.
• Check outbound HTTPS connectivity to your Middleware endpoint.

OpenTelemetry PHP extension is missing#

If Laravel instrumentation does not initialize, verify that the OpenTelemetry PHP extension is installed:

1php -m | grep opentelemetry

If no output is returned:

• Check the output of 02_run_instrumentation in the Elastic Beanstalk deployment logs.
• Verify that the instrumentation installer completed successfully.
• Confirm that the extension is enabled in the PHP configuration used by your application.

No traces in Middleware#

If your Laravel application is running but traces do not appear:

• Verify that OTEL_PHP_AUTOLOAD_ENABLED is set to true.
• Confirm that OTEL_SERVICE_NAME is configured.
• Check that OTEL_EXPORTER_OTLP_ENDPOINT points to http://localhost:9320.
• Verify that the Middleware Agent is running.
• Generate requests to actual application routes, since health check endpoints may be excluded.
• Restart or redeploy the application after updating environment variables.

Frontend and backend traces are not connected#

If Middleware RUM and Laravel traces appear separately:

• Verify that OTEL_PROPAGATORS includes baggage,tracecontext,b3multi.
• Confirm that the frontend SDK propagates the required trace headers.
• Check that proxies and load balancers forward the tracing headers.

Instrumentation stops working after deployment#

If telemetry collection stops after an Elastic Beanstalk update or instance replacement:

• Verify that .ebextensions/99-mwinstrumentation.config is included in the application deployment package.
• Check the Elastic Beanstalk deployment logs for installation errors.
• Avoid installing or modifying Middleware manually over SSH, as these changes may be lost when instances are replaced.

Application cannot connect to Middleware#

If the Agent reports connection or export errors:

• Verify that the Middleware target URL is correct.
• Confirm that the EC2 instances have outbound HTTPS access on port 443.
• Check VPC routing, NAT Gateway configuration, and security group rules.
• Verify that the local OTLP endpoint is accessible on port 9320.

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