AWS Elastic Beanstalk

Elastic Beanstalk rotates EC2 instances during updates/restarts, so anything installed by hand over SSH disappears. To keep APM stable across replacements, we install and configure Middleware during deployment via .ebextensions.

Key Challenges

Ephemeral instances: in‑instance changes are lost after environment updates or health‑driven replacements.
Repeatable install: use EB config files so the agent and Laravel tracing are re‑applied on each deploy.

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

Installation

1 Create .ebextensions/99-mwinstrumentation.config

In your Laravel project root, create a folder .ebextensions and add 99-mwinstrumentation.config with the following content: Tip: The numeric prefix ensures this runs late in the EB config phase.

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  02_run_instrumentation:
6    command: |
7      cd /var/app/staging
8      curl -O https://install.middleware.io/apm/php/laravel-instrument.php
9      COMPOSER_ALLOW_SUPERUSER=1 php laravel-instrument.php install

2 Configure environment variables in Elastic Beanstalk

In the EB console, open Configuration → Software → Environment properties and add:

1OTEL_PHP_AUTOLOAD_ENABLED=true
2OTEL_SERVICE_NAME=<your-service-name>
3OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:9320

For frontend↔backend correlation (if you use Middleware RUM/Browser), add:

1OTEL_PROPAGATORS=baggage,tracecontext,b3multi

3 Additional configuration

Requirement: Laravel version: 8.x or higher.

Tracing is enabled automatically after running the installer script in step 1 (laravel-instrument.php install). Enable trace‑related metrics (optional but recommended): Add the service provider to config/app.php:

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

Add the metrics middleware to app/Http/Kernel.php (place after tracing middleware):

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

Runtime env vars: Set the variables in Step 2 (EB → Configuration → Environment properties) to complete instrumentation: OTEL_PHP_AUTOLOAD_ENABLED, OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT and, for frontend↔backend correlation, OTEL_PROPAGATORS.

Troubleshooting

Agent not installing: check /var/log/eb-activity.log for the 01_install_agent step output. Ensure outbound egress to <MW_UID>.middleware.io is permitted.
OpenTelemetry extension missing: php -m | grep opentelemetry. If empty, re‑run the installer or confirm PHP ini paths.
No traces after deploy:
- Confirm env vars in EB Environment properties are present and redeploy/restart.
- Verify OTEL_EXPORTER_OTLP_ENDPOINT points to the local agent (http://localhost:9320).
- Hit real app routes to generate data (health checks may be excluded).
Headers present but no correlation: ensure OTEL_PROPAGATORS includes b3multi along with baggage,tracecontext.
Lost changes after restart: only EB‑driven files (like .ebextensions) persist; avoid manual SSH edits for instrumentation.

Environment Variables

Keep secrets out of source control. Store them in EB environment properties or your secret manager and reference them in the config.

Scope	Key	Example/Value	Purpose
Installer	`MW_API_KEY`	`<MW_API_KEY>`	Authenticates agent with Middleware.
Installer	`MW_TARGET`	`https://<MW_UID>.middleware.io:443`	Middleware ingestion endpoint (tenant/region).
Runtime	`OTEL_PHP_AUTOLOAD_ENABLED`	`true`	Enables OpenTelemetry PHP auto‑loader.
Runtime	`OTEL_SERVICE_NAME`	`<your-service-name>`	Logical service label in Middleware.
Runtime	`OTEL_EXPORTER_OTLP_ENDPOINT`	`http://localhost:9320`	Local agent endpoint for OTLP export.
Runtime	`OTEL_PROPAGATORS`	`baggage,tracecontext,b3multi`	Adds B3 multi‑header for cross‑service correlation (optional).

Need assistance or want to learn more about Middleware? Contact our support team at [email protected] or join our Slack channel.