Accessing Application Logs from an Add-on

Last updated 15 November 2016

Add-on services can access an app’s log data. If you’re building an add-on service that requires this access, you can create a log drain on behalf of the app and receive the log data.

To set it up, you first need to request it through the manifest.

Add-on manifest

The manifest will need to tell Heroku that your add-on requires permission to set up the log drain. This is done by adding syslog_drain to the list if permissions in the requires property:

{
  "id": "myaddon",
  "api": {
    "requires": ["syslog_drain"]
    //...
  }
}

Provisioning call

When the add-on is provisioned, Heroku’s systems will generate a unique log token for that app/add-on instance combo. Add-on partners should use this to identify logs sent to the drain.

The provisioning call will contain the log drain token. Storing the token is recommended for partners, but not necessary as it’s possible to use another mechanism to separate traffic such as unique port+IP combinations per Heroku user/app. The content of our POST to the /heroku/resources endpoint is described here. When the syslog_drain feature is enabled, the log_drain_token field will be added to the provision payload:

{
  // ...
  "log_drain_token": "d.01234567-89ab-cdef-0123-456789abcdef"
}

and the response would be:

{
  "id": 456,
  "config": { ... },
  "log_drain_url": "syslog://1.1.1.1:67890/",
  "message": "your message here"
}

Heroku will then create the drain and start directing app logs to it. The log_drain_url can be syslog- or HTTPS-based. See the user docs on log drains for more details.

IP Whitelist API

The final piece of configuration is to whitelist Heroku’s Logplex IPs for incoming syslog traffic. Simply send HTTP GET request to https://api.heroku.com/vendor/logplex/whitelist using basic auth with your partner API credentials. The call returns a JSON array of IP addresses to whitelist:

[
  "184.73.5.216",
  "50.16.41.187",
  "50.19.0.98",
  "50.19.146.67",
  "184.72.174.202",
  "50.16.56.45",
  "50.16.160.94",
  "50.17.56.172"
]

When an app provisions an add-on successfully, the user will be able to see the drain created on behalf of the add-on in the log drain list.

$ heroku drains
syslog://two.example.org:584
-----------------------------
[Dummy Addon]