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.

container_commands:
  01_install_agent:
    command: |
      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)"
  02_run_instrumentation:
    command: |
      cd /var/app/staging
      curl -O https://install.middleware.io/apm/php/laravel-instrument.php
      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:

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

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

OTEL_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:

'providers' => [
// ...
Middleware\LaravelApm\LaravelApmServiceProvider::class,
],

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

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

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.