---
title: "Heroku"
description: "Deploy Middleware Monitoring Agent on Heroku to monitor application performance and infrastructure health effortlessly."
section: "Agent Installation"
breadcrumb: "Heroku"
canonical: "https://docs.middleware.io/get-started/agent/heroku"
---
# Heroku

The Middleware Heroku buildpack installs the agent in application dynos to collect available dyno metrics and receive traces from instrumented applications.

Use dyno resource metrics and application traces to investigate resource usage and request performance. Application logs use the separate Log Drain configuration described below.

For application logs, configure the [Heroku Log Drain integration](/integrations/heroku-log-drains) separately.

## How it works

The Middleware Heroku buildpack installs and runs `mw-agent` inside each dyno when your application starts.

The Agent:

- Collects available infrastructure metrics from the dyno.
- Receives application traces through local OpenTelemetry endpoints.
- Forwards telemetry to your Middleware account.
- Starts automatically when Heroku starts or restarts the dyno.

Because Heroku dynos have an ephemeral filesystem, the buildpack includes the Agent in the application slug, ensuring it remains available across dyno restarts and deployments.

**Note**: The buildpack does not collect Heroku application logs. Use the Heroku Log Drain integration for log collection.

## Prerequisites

Before installing Middleware, make sure you have:

- An existing Heroku application.
- Heroku CLI installed and authenticated.
- Access to the application source code and deployment configuration.
- Permissions to manage Heroku buildpacks and configuration variables.
- A Middleware account with an API key (`MW_API_KEY`) and target URL (`MW_TARGET`).
- Outbound HTTPS connectivity from Heroku dynos to Middleware on port 443.

## Installation

#### 1 Set your Heroku application name

Open a terminal and set your Heroku application name:

```bash
export APPNAME=<YOUR_HEROKU_APPLICATION_NAME>
```

Replace the placeholder with your Heroku application name.

The following commands use `$APPNAME` to reference your application.

#### 2 Configure Middleware credentials

Navigate to your Heroku application directory:

```bash
cd <HEROKU_APPLICATION_DIRECTORY>
```

Enable Heroku runtime dyno metadata:

```bash
heroku labs:enable runtime-dyno-metadata -a $APPNAME
```

This provides dyno metadata used to maintain consistent host identification.

Next, configure your Middleware credentials:

```bash
heroku config:set MW_API_KEY=your-initial-token -a $APPNAME

heroku config:set MW_TARGET=your-initial-uid -a $APPNAME
```

Replace the placeholders with your Middleware API key and target URL.

Heroku stores these values as application configuration variables.

#### 3 Add the Middleware buildpack

Add the Middleware buildpack to your Heroku application:

```bash
heroku buildpacks:add https://github.com/middleware-labs/heroku-buildpack-middleware.git -a $APPNAME
```

The buildpack installs `mw-agent` during the application build and configures it to start with the dyno.

#### 4 Verify buildpack ordering

Buildpack ordering is important because the Middleware buildpack modifies the dyno startup process.

Run:

```bash
heroku buildpacks -a $APPNAME
```

Make sure:

- Buildpacks that modify or replace files under `/app` appear before the Middleware buildpack.
- Your application's primary buildpack appears after the Middleware buildpack.

For example, an application using the APT and Node.js buildpacks should have the following order:

```text
1. https://github.com/heroku/heroku-buildpack-apt.git
2. https://github.com/middleware-labs/heroku-buildpack-middleware.git
3. heroku/nodejs
```

For other runtimes, replace `heroku/nodejs` with the appropriate application buildpack.

**Important**: Incorrect buildpack ordering can override the dyno process configuration and prevent your application from starting.

#### 5 Rebuild and deploy the application

After adding the Middleware buildpack, rebuild your Heroku application slug.

For applications deployed through Git:

```bash
git commit --allow-empty -m "Add Middleware buildpack"

git push heroku main
```

This triggers a new Heroku build and includes the Middleware Agent in the application slug.

**Note**: If your application uses a different deployment branch or deployment method, use your existing workflow to trigger a new build.

#### 6 Verify the Agent installation

After deployment, verify that your Heroku dynos are running:

```bash
heroku ps -a $APPNAME
```

Connect to a running dyno:

```bash
heroku ps:exec -a $APPNAME
```

Inside the dyno, check the Middleware Agent process:

```bash
ps aux | grep mw-agent
```

The output should show a running `mw-agent` process.

You can also inspect the Agent log file:

```bash
cat /app/mw-agent/mw-agent.log
```

#### 7 Verify data collection in Middleware

After the Agent starts, allow a few minutes for telemetry to appear.

**Infrastructure metrics**

Go to [Infrastructure Monitoring → Hosts](https://app.middleware.io/infrastructure/host) and verify that your Heroku dynos are reporting available resource metrics.

**Application traces**

If your application is instrumented with OpenTelemetry, go to [APM → Services](https://app.middleware.io/apm/services) and verify that traces are being collected.

**Note**: Installing the buildpack alone does not automatically instrument application code. Configure an OpenTelemetry SDK or Middleware APM SDK to send traces to the local Agent.

## Configure application tracing

The Middleware Agent exposes local endpoints that applications can use to send telemetry.

| Protocol | Port |
| --- | --- |
| OTLP/gRPC | `9313` |
| OTLP/HTTP | `9320` |
| Fluent Forward | `8006` |

For applications using OTLP/HTTP, configure:

```bash
heroku config:set OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:9320 -a $APPNAME
```

For OTLP/gRPC:

```bash
heroku config:set OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:9313 -a $APPNAME
heroku config:set OTEL_EXPORTER_OTLP_PROTOCOL=grpc -a $APPNAME
```

Configure a service name to identify your application in Middleware:

```bash
heroku config:set OTEL_SERVICE_NAME=my-heroku-service -a $APPNAME
```

Replace `my-heroku-service` with your application service name.

Your application must have an OpenTelemetry SDK or supported auto-instrumentation configured to generate traces.

## Configure log collection

The Middleware Heroku buildpack does not collect application logs.

To forward Heroku application logs to Middleware, configure the [Heroku Log Drain integration](/integrations/heroku-log-drains).

Heroku Log Drains forward logs from your application to an external log ingestion endpoint.

Once configured, application logs can be viewed under **Log Monitoring → Log Explorer**.

**Note**: Do not use `MW_AGENT_FEATURES_LOG_COLLECTION` as a substitute for the Heroku Log Drain integration. Log collection through the buildpack is not supported.

## Optional configuration

### Configure consistent dyno hostnames

By default, Heroku dynos report their internal container IDs as hostnames.

Because these IDs change when dynos restart, you can enable consistent dyno hostnames:

```bash
heroku config:set MW_DYNO_HOSTNAME=true -a $APPNAME
```

With this setting enabled, the Agent uses the following hostname format:

```text
appname.type.num
```

For example:

```text
my-app.web.1
my-app.worker.1
```

This makes it easier to identify dynos across restarts.

**Prerequisite**: Heroku runtime dyno metadata must be enabled.

### Add custom host tags

You can attach custom tags to dynos for filtering and grouping in Middleware.

```bash
heroku config:set MW_HOST_TAGS=env:prod,role:web -a $APPNAME
```

Tags use comma-separated `key:value` pairs.

### Pin the Agent version

By default, the buildpack installs its configured Middleware Agent version.

To use a specific version:

```bash
heroku config:set MW_AGENT_VERSION=1.7.7 -a $APPNAME
```

Replace `1.7.7` with the version you want to deploy.

You can also pin the Middleware buildpack to a Git tag:

```bash
heroku buildpacks:add https://github.com/middleware-labs/heroku-buildpack-middleware.git#<TAG_NAME> -a $APPNAME
```

After updating the buildpack version, rebuild your application:

```bash
git commit --allow-empty -m "Rebuild slug"

git push heroku main
```

**Note**: The version above is an example from the existing configuration. Use a supported Agent version for your deployment.

### Configure a pre-execution script

Use `MW_DYNO_PREEXEC_SCRIPT` to run custom configuration before the Middleware Agent starts.

For example, you can disable the Agent for one-off dynos.

Create a script named `preexec.sh` in your application:

```bash
#!/bin/bash

DYNO_TYPE="${DYNO%%.*}"
if [ "$DYNO_TYPE" == "run" ]; then
  export MW_DYNO_DISABLE_AGENT=true
fi
```

Configure the script path:

```bash
heroku config:set MW_DYNO_PREEXEC_SCRIPT=/app/preexec.sh -a $APPNAME
```

Make sure the script is included in your application deployment.

This example disables the Middleware Agent for dynos with the `run` process type.

## Configuration variables reference

| Variable | Required | Description |
| --- | --- | --- |
| `MW_API_KEY` | Yes | Middleware API key |
| `MW_TARGET` | Yes | Middleware ingestion endpoint |
| `MW_AGENT_VERSION` | No | Overrides the default Agent version |
| `MW_DYNO_DISABLE_AGENT` | No | Disables the Agent when set to `true` |
| `MW_DYNO_HOSTNAME` | No | Uses a consistent dyno hostname |
| `MW_DYNO_PREEXEC_SCRIPT` | No | Runs a script before the Agent starts |
| `MW_HOST_TAGS` | No | Adds custom host tags |
| `MW_FLUENT_PORT` | No | Fluent receiver port; default `8006` |
| `MW_AGENT_FEATURES_METRIC_COLLECTION` | No | Enables infrastructure metric collection; enabled by default |
| `MW_AGENT_FEATURES_LOG_COLLECTION` | No | Log collection setting; not used by this buildpack |

## Managing the Middleware Agent

Use the Heroku CLI to inspect running dynos and troubleshoot the Agent.

| Action | Command |
| --- | --- |
| List running dynos | `heroku ps -a $APPNAME` |
| Connect to a dyno | `heroku ps:exec -a $APPNAME` |
| Check the Agent process | `ps aux \| grep mw-agent` |
| View Heroku logs | `heroku logs --tail -a $APPNAME` |
| View Agent log file | `cat /app/mw-agent/mw-agent.log` |
| View configuration variables | `heroku config -a $APPNAME` |

Run the Agent process and log file commands from inside the dyno.

## Troubleshooting

### Middleware Agent is not running

If the Agent does not start after deployment:

Check the dyno status:

```bash
heroku ps -a $APPNAME
```

Connect to a running dyno:

```bash
heroku ps:exec -a $APPNAME
```

Verify the Agent process:

```bash
ps aux | grep mw-agent
```

Inspect the Agent log file:

```bash
cat /app/mw-agent/mw-agent.log
```

If the Agent is missing, verify that the Middleware buildpack was included in the latest application build.

### Application fails to start after adding the buildpack

If the application stops starting after Middleware installation:

- Run `heroku buildpacks -a $APPNAME`.
- Verify that the application's primary buildpack appears after the Middleware buildpack.
- Make sure buildpacks that modify `/app` appear before Middleware.
- Rebuild the application after correcting the order.

### No infrastructure metrics in Middleware

If the Agent is running but dyno metrics do not appear:

- Verify that `MW_API_KEY` and `MW_TARGET` are configured correctly.
- Check that `MW_AGENT_FEATURES_METRIC_COLLECTION` is not disabled.
- Confirm that outbound HTTPS access to Middleware is available.
- Review Agent logs for collection or export errors.

### Application traces are missing

If dyno metrics appear but application traces do not:

- Verify that your application has an OpenTelemetry SDK or Middleware APM SDK installed.
- Check that the application sends telemetry to the correct local Agent endpoint.
- Verify that `OTEL_SERVICE_NAME` is configured.
- Generate application traffic and check [**APM → Services**](https://app.middleware.io/apm/services).

### Dynos appear as new hosts after restarts

If dynos appear with different hostnames after each restart:

- Enable runtime dyno metadata.
- Set `MW_DYNO_HOSTNAME=true`.
- Restart the dynos to apply the updated configuration.

### Application logs are missing

If application logs do not appear in Middleware:

- Verify that the Heroku Log Drain integration is configured.
- Check that Heroku is forwarding logs to the configured destination.
- Confirm that the destination is reachable.
- Do not rely on the Middleware buildpack for log collection.

## Uninstall

#### 1 Remove the Middleware buildpack

Run:

```bash
heroku buildpacks:remove https://github.com/middleware-labs/heroku-buildpack-middleware.git -a $APPNAME
```

#### 2 Remove Middleware configuration variables

```bash
heroku config:unset MW_API_KEY MW_TARGET MW_AGENT_VERSION MW_DYNO_DISABLE_AGENT \
MW_DYNO_HOSTNAME MW_DYNO_PREEXEC_SCRIPT MW_HOST_TAGS MW_FLUENT_PORT \
MW_AGENT_FEATURES_METRIC_COLLECTION MW_AGENT_FEATURES_LOG_COLLECTION -a $APPNAME
```

#### 3 Rebuild the application

For Git-based deployments:

```bash
git commit --allow-empty -m "Remove Middleware buildpack"

git push heroku main
```

This rebuilds the application without the Middleware Agent.

**Note**: Removing the buildpack does not remove a separately configured Heroku Log Drain. Remove that integration separately if you also want to stop forwarding logs.

If you need assistance, 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.