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

1export 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:

1cd <HEROKU_APPLICATION_DIRECTORY>

Enable Heroku runtime dyno metadata:

1heroku labs:enable runtime-dyno-metadata -a $APPNAME

This provides dyno metadata used to maintain consistent host identification.

Next, configure your Middleware credentials:

1heroku config:set MW_API_KEY=<MW_API_KEY> -a $APPNAME
2
3heroku config:set MW_TARGET=https://<MW_UID>.middleware.io:443 -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:

1heroku 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:

1heroku 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:

11. https://github.com/heroku/heroku-buildpack-apt.git
22. https://github.com/middleware-labs/heroku-buildpack-middleware.git
33. 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:

1git commit --allow-empty -m "Add Middleware buildpack"
2
3git 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:

1heroku ps -a $APPNAME

Connect to a running dyno:

1heroku ps:exec -a $APPNAME

Inside the dyno, check the Middleware Agent process:

1ps aux | grep mw-agent

The output should show a running mw-agent process.

You can also inspect the Agent log file:

1cat /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 and verify that your Heroku dynos are reporting available resource metrics.

Application traces

If your application is instrumented with OpenTelemetry, go to 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:

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

For OTLP/gRPC:

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

Configure a service name to identify your application in Middleware:

1heroku 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.

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:

1heroku config:set MW_DYNO_HOSTNAME=true -a $APPNAME

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

1appname.type.num

For example:

1my-app.web.1
2my-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.

1heroku 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:

1heroku 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:

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

After updating the buildpack version, rebuild your application:

1git commit --allow-empty -m "Rebuild slug"
2
3git 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:

1#!/bin/bash
2
3DYNO_TYPE="${DYNO%%.*}"
4if [ "$DYNO_TYPE" == "run" ]; then
5  export MW_DYNO_DISABLE_AGENT=true
6fi

Configure the script path:

1heroku 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:

1heroku ps -a $APPNAME

Connect to a running dyno:

1heroku ps:exec -a $APPNAME

Verify the Agent process:

1ps aux | grep mw-agent

Inspect the Agent log file:

1cat /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.

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#