---
title: "AWS Elastic Beanstalk"
description: "Step-by-step guide to configure Middleware APM for AWS Elastic Beanstalk to monitor application performance and detect issues."
section: "Cloud Platform"
breadcrumb: "Cloud Platform > AWS Elastic Beanstalk"
canonical: "https://docs.middleware.io/get-started/agent/aws-elastic-beanstalk"
---
# 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

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

## 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

#### 1 Create the Elastic Beanstalk configuration file

In your Laravel project root, create a directory named `.ebextensions` if it does not already exist.

Inside it, create a file named `99-mwinstrumentation.config`.

Your project structure should look like this:

```text
your-laravel-project/
├── .ebextensions/
│   └── 99-mwinstrumentation.config
├── app/
├── config/
├── public/
└── ...
```

Add the following configuration:

```yml
container_commands:
  01_install_agent:
    command: |
      MW_API_KEY="your-initial-token" MW_TARGET=your-initial-uid 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
```

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

This configuration performs two actions during deployment:

- `01_install_agent`: Installs the Middleware Agent on the Elastic Beanstalk EC2 instance.
- `02_run_instrumentation`: Downloads and runs the Laravel instrumentation installer.

**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.

The numeric prefix in `99-mwinstrumentation.config` helps control the order in which Elastic Beanstalk processes configuration files.

**Note**: Avoid storing the Middleware API key directly in source control. For production deployments, supply credentials through Elastic Beanstalk environment properties or a supported secret manager and reference them from your deployment configuration.

#### 2 Configure environment variables

Open the AWS Management Console and navigate to:

**Elastic Beanstalk → Environments → Your Environment → Configuration**

In the **Updates, monitoring, and logging** section, choose **Edit**. Under **Platform software → Environment properties**, add the following variables:

| Variable | Value |
| --- | --- |
| `OTEL_PHP_AUTOLOAD_ENABLED` | `true` |
| `OTEL_SERVICE_NAME` | `<your-service-name>` |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:9320` |

These variables configure OpenTelemetry instrumentation for your Laravel application.

- `OTEL_PHP_AUTOLOAD_ENABLED` enables the OpenTelemetry PHP auto-loader.
- `OTEL_SERVICE_NAME` identifies the application in Middleware.
- `OTEL_EXPORTER_OTLP_ENDPOINT` sends telemetry to the Middleware Agent running locally.

Save the environment properties.

#### 3 Enable frontend and backend trace correlation (optional)

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

Add the following environment variable in Elastic Beanstalk:

```bash
OTEL_PROPAGATORS=baggage,tracecontext,b3multi
```

This enables W3C and B3 multi-header propagation for distributed tracing.

Make sure your frontend application is also configured to propagate compatible trace headers.

#### 4 Enable Laravel trace-related metrics (optional)

Laravel tracing is enabled automatically when the instrumentation installer runs.

To collect additional trace-related metrics, update your Laravel application configuration.

#### Laravel 10 or earlier

**1. Register the service provider**

Open `config/app.php` and add the Middleware service provider to the `providers` array:

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

**2. Add the metrics middleware**

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

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

#### Laravel 11 or later

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

**1. Register the service provider**

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

```php
return [
    App\Providers\AppServiceProvider::class,
    Middleware\LaravelApm\LaravelApmServiceProvider::class,
];
```

**2. Add the metrics middleware**

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

```php
->withMiddleware(function (Middleware $middleware) {
    $middleware->append(\Middleware\LaravelApm\Middleware\MetricsMiddleware::class);
})
```

#### 5 Deploy the application

Deploy your updated Laravel application to AWS Elastic Beanstalk using your existing deployment method.

During deployment, Elastic Beanstalk executes the commands in `99-mwinstrumentation.config` to:

1. Install the Middleware Agent.
2. Configure Laravel instrumentation.
3. Start the application with the configured OpenTelemetry environment variables.

After deployment, verify that your Elastic Beanstalk environment is healthy.

#### 6 Verify data collection

1. Open your deployed Laravel application.
2. Generate a few requests to application endpoints.
3. Log in to Middleware.
4. Go to [APM → Services](https://app.middleware.io/apm/services).
5. Find the service configured using `OTEL_SERVICE_NAME`.
6. Open the service to view traces, latency, and errors.

You can also verify collected telemetry in:

- **[APM → Traces](https://app.middleware.io/apm/traces)**: View individual application requests.
- **[Log Monitoring](https://app.middleware.io/logs)**: View collected application logs.
- **[Infrastructure Monitoring → Hosts](https://app.middleware.io/infrastructure/host)**: View host metrics from the Elastic Beanstalk EC2 instances.

Allow a few minutes for telemetry to appear after deployment.

## Environment variables reference

| Variable | Required | Description |
| --- | --- | --- |
| `MW_API_KEY` | Yes | Middleware API key used during Agent installation |
| `MW_TARGET` | Yes | Middleware ingestion endpoint |
| `OTEL_PHP_AUTOLOAD_ENABLED` | Yes | Enables OpenTelemetry PHP automatic instrumentation |
| `OTEL_SERVICE_NAME` | Yes | Service name displayed in Middleware |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Yes | Local Middleware Agent OTLP endpoint |
| `OTEL_PROPAGATORS` | No | Configures distributed trace context propagation |

### Example configuration

```bash
MW_TARGET=https://<MW_UID>.middleware.io:443
OTEL_PHP_AUTOLOAD_ENABLED=true
OTEL_SERVICE_NAME=laravel-production
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:9320
OTEL_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:

```bash
php -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 support@middleware.io.

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