Heroku Log Drains

Heroku’s HTTP/S log drains buffer log messages and submit batches of messages to an HTTPS endpoint via a POST request. The POST body contains Syslog formatted messages, framed using the Syslog TCP protocol octet counting framing method.

Middleware’s HTTP API implements and understands the Logplex standard defined by the content-header application/logplex-1.

To setup HTTP/S log drains with Middleware, first setup APPNAME, SERVICE and MW_API_KEY environment variable:

export MW_API_KEY=<MW_API_KEY>
export APPNAME=<YOUR_HEROKU_APPNAME>
export SERVICE=<SERVICE_NAME>

Replace <MW_API_KEY> with your Middleware API Key.
Replace <YOUR_HEROKU_APPNAME> with the the Heroku application name you want to enable log drains for.
Replace <SERVICE_NAME> with something that represents the service for your Heroku application. For example, if your Heroku application is called payment-gateway, your SERVICE name could be billing-service.

Providing relevant values for APPNAME and SERVICE makes it easier to filter logs inside of the Middleware Platform.

Then configure the log drain using the following command:

heroku drains:add "https://<MW_UID>.middleware.io:443/heroku?mw-api-key=$MW_API_KEY&app=$APPNAME&service=$SERVICE" -a $APPNAME

Replace <MW_UID> with your Middleware account ID.

Heroku Log Categories

Heroku provides three categories of logs for a deployed application:

App Logs: These are the logs from your deployed application.
API Logs: These are the audit logs on administrative actions executed by you and other developers working on your application.
System Logs: These are the logs about actions taken by the Heroku platform infrastructure on behalf of your application.

Middleware collects all three categories of logs and creates attributes for them to make filtering easier and consistent. Below are some rules about the attributes collected:

If app name parameter is not provided, the default app name is set to herokuapp.
If source parameter is not provided, the default source is set to heroku.
If service parameter is not provided, the app parameter value is used as a service.name.
If both service and app attributes are not set, the default service.name is set to heroku.

App & API Logs Specific Attributes

For App & API category logs, the host.name attribute is added by combining the app name query query parameter value passed in the drain URL and the syslog.proc.id attribute value.

Heroku provides Syslog process ID as the Dyno ID. For example, if app name is billing-app and Syslog process ID is web.1234, host.name will be set to billing-app.web.1234.

All other attributes are parsed from Syslog formatted message metadata.

System Log Specific Attributes

For System category Logs, the host.name attribute is added by combining the app name query parameter value passed in the drain URL and dyno field from the message body itself. For example, if app name is billing-app and the dyno field is web.1234, host.name will be set to billing-app.web.1234.

dyno and dyno.type attributes are added by parsing relevant fields from the message body.

All other attributes are parsed from Syslog formatted message metadata and body.

Attributes added by Middleware make it easier to co-relate Heroku logs and metrics.

For example, using the same value for the MW_DYNO_HOSTNAME environment variable in the Heroku buildpack for Middleware and the app name query parameter in the log drains URL above makes it easier to correlate logs and metrics from the same host.

Custom attributes:

You can add custom attributes to your logs by adding query parameters in the URL of the drain command as follows:

heroku drains:add "https://<MW_UID>.middleware.io:443/heroku?my-attribute=my-value&mw-api-key=<MW_API_KEY>&app=$APPNAME&service=$SERVICE" -a $APPNAME

In the above command, my-attribute in query parameter is the custom attribute and my-value is the value for that attribute.